1.注解@Conditional的定义
@Retention(RetentionPolicy.RUNTIME) @Target({ElementType.TYPE, ElementType.METHOD}) public @interface Conditional { /** * All {@link Condition}s that must {@linkplain Condition#matches match} * in order for the component to be registered. */ Class<? extends Condition>[] value(); }
注解@Conditional标识一个组件时，该组件只有全面满足value()指定的所有条件时才可以注册到容器中。
注解@Conditional的使用场景如下：
. 作为类型级别的注解，作用在一个直接或者间接@Component注解(包括@Configuration作为元注解的类)的类上，目标是组成自定义的steretype注解。
. 作为方法级别的注解，作用在任意的@Bean 方法上
如果一个标注了@Configuration的类，也标注了@Conditional，所有的@Bean方法，@Import和@ComponentScan注解关联的类将也满足这些Conditions。
注意，@Conditional注解不能继承，从父类或者重写方法的condition是不起作用的。
其中，一个Condition是要注册的Bean定义之前可以编程决定的状态。详细信息如下：
2 前生 Condition定义
public interface Condition { /** * Determine if the condition matches. * @param context the condition context * @param metadata metadata of the {@link org.springframework.core.type.AnnotationMetadata class} * or {@link org.springframework.core.type.MethodMetadata method} being checked. * @return {@code true} if the condition matches and the component can be registered * or {@code false} to veto registration. */ boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata); }
一个单独的condition是一个组件为注册为bean时必须满足matches()方法。
Conditions在要注册的组件变成bean definition之前必须检查立即检查所有的matches方法。
Condition也必须和BeanFactoryPostProcessor一样满足同样的限制条件。更细粒度的控制可以考虑使用ConfigurationCondition。
3.后世
spring-boot-autoconfigure condition相关的类如下：
3.1 ConditionalOnBean定义
@Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @Documented @Conditional(OnBeanCondition.class) public @interface ConditionalOnBean { /** * The class type of bean that should be checked. The condition matches when all of * the classes specified are contained in the {@link ApplicationContext}. * @return the class types of beans to check */ Class<?>[] value() default {}; /** * The class type names of bean that should be checked. The condition matches when all * of the classes specified are contained in the {@link ApplicationContext}. * @return the class type names of beans to check */ String[] type() default {}; /** * The annotation type decorating a bean that should be checked. The condition matches * when all of the annotations specified are defined on beans in the * {@link ApplicationContext}. * @return the class-level annotation types to check */ Class<? extends Annotation>[] annotation() default {}; /** * The names of beans to check. The condition matches when all of the bean names * specified are contained in the {@link ApplicationContext}. * @return the name of beans to check */ String[] name() default {}; /** * Strategy to decide if the application context hierarchy (parent contexts) should be * considered. * @return the search strategy */ SearchStrategy search() default SearchStrategy.ALL; }
ConditionalOnBean作用：当指定bean的类名或者名称已经在BeanFactory中存在时才算满足条件。
其实现类为OnBeanCondition，检查指定的bean是存在还是不存在。
@Order(Ordered.LOWEST_PRECEDENCE) class OnBeanCondition extends SpringBootCondition implements ConfigurationCondition { /** * Bean definition attribute name for factory beans to signal their product type (if * known and it can't be deduced from the factory bean class). */ public static final String FACTORY_BEAN_OBJECT_TYPE = BeanTypeRegistry.FACTORY_BEAN_OBJECT_TYPE; @Override public ConfigurationPhase getConfigurationPhase() { return ConfigurationPhase.REGISTER_BEAN; } @Override public ConditionOutcome getMatchOutcome(ConditionContext context, AnnotatedTypeMetadata metadata) { ConditionMessage matchMessage = ConditionMessage.empty(); if (metadata.isAnnotated(ConditionalOnBean.class.getName())) { BeanSearchSpec spec = new BeanSearchSpec(context, metadata, ConditionalOnBean.class); MatchResult matchResult = getMatchingBeans(context, spec); if (!matchResult.isAllMatched()) { String reason = createOnBeanNoMatchReason(matchResult); return ConditionOutcome.noMatch(ConditionMessage .forCondition(ConditionalOnBean.class, spec).because(reason)); } matchMessage = matchMessage.andCondition(ConditionalOnBean.class, spec) .found("bean", "beans") .items(Style.QUOTE, matchResult.getNamesOfAllMatches()); } if (metadata.isAnnotated(ConditionalOnSingleCandidate.class.getName())) { BeanSearchSpec spec = new SingleCandidateBeanSearchSpec(context, metadata, ConditionalOnSingleCandidate.class); MatchResult matchResult = getMatchingBeans(context, spec); if (!matchResult.isAllMatched()) { return ConditionOutcome.noMatch(ConditionMessage .forCondition(ConditionalOnSingleCandidate.class, spec) .didNotFind("any beans").atAll()); } else if (!hasSingleAutowireCandidate(context.getBeanFactory(), matchResult.getNamesOfAllMatches(), spec.getStrategy() == SearchStrategy.ALL)) { return ConditionOutcome.noMatch(ConditionMessage .forCondition(ConditionalOnSingleCandidate.class, spec) .didNotFind("a primary bean from beans") .items(Style.QUOTE, matchResult.getNamesOfAllMatches())); } matchMessage = matchMessage .andCondition(ConditionalOnSingleCandidate.class, spec) .found("a primary bean from beans") .items(Style.QUOTE, matchResult.namesOfAllMatches); } if (metadata.isAnnotated(ConditionalOnMissingBean.class.getName())) { BeanSearchSpec spec = new BeanSearchSpec(context, metadata, ConditionalOnMissingBean.class); MatchResult matchResult = getMatchingBeans(context, spec); if (matchResult.isAnyMatched()) { String reason = createOnMissingBeanNoMatchReason(matchResult); return ConditionOutcome.noMatch(ConditionMessage .forCondition(ConditionalOnMissingBean.class, spec) .because(reason)); } matchMessage = matchMessage.andCondition(ConditionalOnMissingBean.class, spec) .didNotFind("any beans").atAll(); } return ConditionOutcome.match(matchMessage); } }
3.2 ConditionalOnClass
当指定的类在classpath下认定满足条件，实现类为：OnClassCondition。
定义如下：
@Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @Documented @Conditional(OnClassCondition.class) public @interface ConditionalOnClass { /** * The classes that must be present. Since this annotation parsed by loading class * bytecode it is safe to specify classes here that may ultimately not be on the * classpath. * @return the classes that must be present */ Class<?>[] value() default {}; /** * The classes names that must be present. * @return the class names that must be present. */ String[] name() default {}; }
3.3 ConditionalOnCloudPlatform
指定的云平台激活时满足条件。实现类为：OnCloudPlatformCondition
@Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @Documented @Conditional(OnCloudPlatformCondition.class) public @interface ConditionalOnCloudPlatform { /** * The {@link CloudPlatform cloud platform} that must be active. * @return the expected cloud platform */ CloudPlatform value(); }
3.4 ConditionalOnExpression
/** * Configuration annotation for a conditional element that depends on the value of a SpEL * expression. * * @author Dave Syer */ @Retention(RetentionPolicy.RUNTIME) @Target({ ElementType.TYPE, ElementType.METHOD }) @Documented @Conditional(OnExpressionCondition.class) public @interface ConditionalOnExpression { /** * The SpEL expression to evaluate. Expression should return {@code true} if the * condition passes or {@code false} if it fails. * @return the SpEL expression */ String value() default "true"; }
3.5 ConditionalOnJava
/** * {@link Conditional} that matches based on the JVM version the application is running * on. * * @author Oliver Gierke * @author Phillip Webb * @author Andy Wilkinson * @since 1.1.0 */ @Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @Documented @Conditional(OnJavaCondition.class) public @interface ConditionalOnJava { /** * Configures whether the value configured in {@link #value()} shall be considered the * upper exclusive or lower inclusive boundary. Defaults to * {@link Range#EQUAL_OR_NEWER}. * @return the range */ Range range() default Range.EQUAL_OR_NEWER; /** * The {@link JavaVersion} to check for. Use {@link #range()} to specify whether the * configured value is an upper-exclusive or lower-inclusive boundary. * @return the java version */ JavaVersion value(); /** * Range options. */ enum Range { /** * Equal to, or newer than the specified {@link JavaVersion}. */ EQUAL_OR_NEWER, /** * Older than the specified {@link JavaVersion}. */ OLDER_THAN } /** * Java versions. */ enum JavaVersion { /** * Java 1.9. */ NINE(9, "1.9", "java.security.cert.URICertStoreParameters"), /** * Java 1.8. */ EIGHT(8, "1.8", "java.util.function.Function"); private final int value; private final String name; private final boolean available; JavaVersion(int value, String name, String className) { this.value = value; this.name = name; this.available = ClassUtils.isPresent(className, getClass().getClassLoader()); } /** * Determines if this version is within the specified range of versions. * @param range the range * @param version the bounds of the range * @return if this version is within the specified range */ public boolean isWithin(Range range, JavaVersion version) { Assert.notNull(range, "Range must not be null"); Assert.notNull(version, "Version must not be null"); switch (range) { case EQUAL_OR_NEWER: return this.value >= version.value; case OLDER_THAN: return this.value < version.value; } throw new IllegalStateException("Unknown range " + range); } @Override public String toString() { return this.name; } /** * Returns the {@link JavaVersion} of the current runtime. * @return the {@link JavaVersion} */ public static JavaVersion getJavaVersion() { for (JavaVersion candidate : JavaVersion.values()) { if (candidate.available) { return candidate; } } return EIGHT; } } }
3.6 ConditionalOnJndi
/** * {@link Conditional} that matches based on the availability of a JNDI * {@link InitialContext} and the ability to lookup specific locations. * * @author Phillip Webb * @since 1.2.0 */ @Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @Documented @Conditional(OnJndiCondition.class) public @interface ConditionalOnJndi { /** * JNDI Locations, one of which must exist. If no locations are specific the condition * matches solely based on the presence of an {@link InitialContext}. * @return the JNDI locations */ String[] value() default {}; }
3.7 ConditionalOnMissingBean
/** * {@link Conditional} that only matches when the specified bean classes and/or names are * not already contained in the {@link BeanFactory}. * <p> * The condition can only match the bean definitions that have been processed by the * application context so far and, as such, it is strongly recommended to use this * condition on auto-configuration classes only. If a candidate bean may be created by * another auto-configuration, make sure that the one using this condition runs after. * * @author Phillip Webb * @author Andy Wilkinson */ @Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @Documented @Conditional(OnBeanCondition.class) public @interface ConditionalOnMissingBean { /** * The class type of bean that should be checked. The condition matches when each * class specified is missing in the {@link ApplicationContext}. * @return the class types of beans to check */ Class<?>[] value() default {}; /** * The class type names of bean that should be checked. The condition matches when * each class specified is missing in the {@link ApplicationContext}. * @return the class type names of beans to check */ String[] type() default {}; /** * The class type of beans that should be ignored when identifying matching beans. * @return the class types of beans to ignore * @since 1.2.5 */ Class<?>[] ignored() default {}; /** * The class type names of beans that should be ignored when identifying matching * beans. * @return the class type names of beans to ignore * @since 1.2.5 */ String[] ignoredType() default {}; /** * The annotation type decorating a bean that should be checked. The condition matches * when each annotation specified is missing from all beans in the * {@link ApplicationContext}. * @return the class-level annotation types to check */ Class<? extends Annotation>[] annotation() default {}; /** * The names of beans to check. The condition matches when each bean name specified is * missing in the {@link ApplicationContext}. * @return the name of beans to check */ String[] name() default {}; /** * Strategy to decide if the application context hierarchy (parent contexts) should be * considered. * @return the search strategy */ SearchStrategy search() default SearchStrategy.ALL; }
3.8 ConditionalOnMissingClass
/** * {@link Conditional} that only matches when the specified classes are not on the * classpath. * * @author Dave Syer */ @Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @Documented @Conditional(OnClassCondition.class) public @interface ConditionalOnMissingClass { /** * The names of the classes that must not be present. * @return the names of the classes that must not be present */ String[] value() default {}; }
3.9 ConditionalOnNotWebApplication
/** * {@link Conditional} that only matches when the application context is a not a web * application context. * * @author Dave Syer */ @Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @Documented @Conditional(OnWebApplicationCondition.class) public @interface ConditionalOnNotWebApplication { }
3.10 ConditionalOnProperty
/** * {@link Conditional} that checks if the specified properties have a specific value. By * default the properties must be present in the {@link Environment} and * <strong>not</strong> equal to {@code false}. The {@link #havingValue()} and * {@link #matchIfMissing()} attributes allow further customizations. * * <p> * The {@link #havingValue} attribute can be used to specify the value that the property * should have. The table below shows when a condition matches according to the property * value and the {@link #havingValue()} attribute: * * <table summary="having values" border="1"> * <tr> * <th>Property Value</th> * <th>{@code havingValue=""}</th> * <th>{@code havingValue="true"}</th> * <th>{@code havingValue="false"}</th> * <th>{@code havingValue="foo"}</th> * </tr> * <tr> * <td>{@code "true"}</td> * <td>yes</td> * <td>yes</td> * <td>no</td> * <td>no</td> * </tr> * <tr> * <td>{@code "false"}</td> * <td>no</td> * <td>no</td> * <td>yes</td> * <td>no</td> * </tr> * <tr> * <td>{@code "foo"}</td> * <td>yes</td> * <td>no</td> * <td>no</td> * <td>yes</td> * </tr> * </table> * * <p> * If the property is not contained in the {@link Environment} at all, the * {@link #matchIfMissing()} attribute is consulted. By default missing attributes do not * match. * * @author Maciej Walkowiak * @author Stephane Nicoll * @author Phillip Webb * @since 1.1.0 */ @Retention(RetentionPolicy.RUNTIME) @Target({ ElementType.TYPE, ElementType.METHOD }) @Documented @Conditional(OnPropertyCondition.class) public @interface ConditionalOnProperty { /** * Alias for {@link #name()}. * @return the names */ String[] value() default {}; /** * A prefix that should be applied to each property. The prefix automatically ends * with a dot if not specified. * @return the prefix */ String prefix() default ""; /** * The name of the properties to test. If a prefix has been defined, it is applied to * compute the full key of each property. For instance if the prefix is * {@code app.config} and one value is {@code my-value}, the fully key would be * {@code app.config.my-value} * <p> * Use the dashed notation to specify each property, that is all lower case with a "-" * to separate words (e.g. {@code my-long-property}). * @return the names */ String[] name() default {}; /** * The string representation of the expected value for the properties. If not * specified, the property must <strong>not</strong> be equals to {@code false}. * @return the expected value */ String havingValue() default ""; /** * Specify if the condition should match if the property is not set. Defaults to * {@code false}. * @return if should match if the property is missing */ boolean matchIfMissing() default false; /** * If relaxed names should be checked. Defaults to {@code true}. * @return if relaxed names are used */ boolean relaxedNames() default true; }
3.11 ConditionalOnResource
/** * {@link Conditional} that only matches when the specified resources are on the * classpath. * * @author Dave Syer */ @Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @Documented @Conditional(OnResourceCondition.class) public @interface ConditionalOnResource { /** * The resources that must be present. * @return the resource paths that must be present. */ String[] resources() default {}; }
3.12 ConditionalOnSingleCandidate
/** * {@link Conditional} that only matches when the specified bean class is already * contained in the {@link BeanFactory} and a single candidate can be determined. * <p> * The condition will also match if multiple matching bean instances are already contained * in the {@link BeanFactory} but a primary candidate has been defined; essentially, the * condition match if auto-wiring a bean with the defined type will succeed. * <p> * The condition can only match the bean definitions that have been processed by the * application context so far and, as such, it is strongly recommended to use this * condition on auto-configuration classes only. If a candidate bean may be created by * another auto-configuration, make sure that the one using this condition runs after. * * @author Stephane Nicoll * @since 1.3.0 */ @Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @Documented @Conditional(OnBeanCondition.class) public @interface ConditionalOnSingleCandidate { /** * The class type of bean that should be checked. The condition match if the class * specified is contained in the {@link ApplicationContext} and a primary candidate * exists in case of multiple instances. * <p> * This attribute may <strong>not</strong> be used in conjunction with {@link #type()} * , but it may be used instead of {@link #type()}. * @return the class type of the bean to check */ Class<?> value() default Object.class; /** * The class type name of bean that should be checked. The condition matches if the * class specified is contained in the {@link ApplicationContext} and a primary * candidate exists in case of multiple instances. * <p> * This attribute may <strong>not</strong> be used in conjunction with * {@link #value()}, but it may be used instead of {@link #value()}. * @return the class type name of the bean to check */ String type() default ""; /** * Strategy to decide if the application context hierarchy (parent contexts) should be * considered. * @return the search strategy */ SearchStrategy search() default SearchStrategy.ALL; }
3.13 ConditionalOnWebApplication
/** * {@link Conditional} that matches when the application is a web application. By default, * any web application will match but it can be narrowed using the {@link #type()} * attribute. * * @author Dave Syer * @author Stephane Nicoll */ @Target({ ElementType.TYPE, ElementType.METHOD }) @Retention(RetentionPolicy.RUNTIME) @Documented @Conditional(OnWebApplicationCondition.class) public @interface ConditionalOnWebApplication { /** * The required type of the web application. * @return the required web application type */ Type type() default Type.ANY; /** * Available application types. */ enum Type { /** * Any web application will match. */ ANY, /** * Only servlet-based web application will match. */ SERVLET, /** * Only reactive-based web application will match. */ REACTIVE } }