Clarify edge case docs on ConditionalOnClass

When used as a meta-annotation the value() attribute of
@ConditionalOnClass will fail silently resulting in the @Conditional
nature of the annotation being ignored.

See gh-8185
pull/8929/head
Phillip Verheyden 8 years ago committed by Stephane Nicoll
parent a8860ba7e9
commit 08f8219248

@ -36,9 +36,14 @@ import org.springframework.context.annotation.Conditional;
public @interface ConditionalOnClass {
/**
* <p>
* 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.
* classpath, only if this annotation is directly on the affected component and
* <b>not</b> if this annotation is used as a composed, meta-annotation. If this
* is used as a meta annotation and the given class is not available at runtime
* then this {@link @Conditional} will effectively be ignored. In order to use
* this annotation as a meta-annotation, only use the {@link #name} attribute.
* @return the classes that must be present
*/
Class<?>[] value() default {};

@ -5839,11 +5839,16 @@ code by annotating `@Configuration` classes or individual `@Bean` methods.
[[boot-features-class-conditions]]
==== Class conditions
The `@ConditionalOnClass` and `@ConditionalOnMissingClass` annotations allows
configuration to be included based on the presence or absence of specific classes. Due to
the fact that annotation metadata is parsed using http://asm.ow2.org/[ASM] you can
actually use the `value` attribute to refer to the real class, even though that class
might not actually appear on the running application classpath. You can also use the
`name` attribute if you prefer to specify the class name using a `String` value.
configuration to be included based on the presence or absence of specific classes.
If you are using the `@ConditionalOnClass` annotation directly on the class you are conditionally
registering, you can actually use the `value` attribute to refer to the real class,
even though that class might not actually appear on the running application classpath.
This is due to the fact that annotation metadata directly on a class is parsed
using http://asm.ow2.org/[ASM]. You can also use the `name` attribute if you prefer to
specify the class name using a `String` value, which is required if you are using
`@ConditionalOnClass` or `@ConditionalOnMissingClass` as apart of a meta-annotation to
compose your own composed annotations or in an `@Bean` method as neither of these cases
are handled by ASM.

Loading…
Cancel
Save