From 08f8219248eb2cc9b256970d7ad3633c264b88c1 Mon Sep 17 00:00:00 2001 From: Phillip Verheyden Date: Thu, 2 Feb 2017 16:19:31 -0600 Subject: [PATCH 1/2] 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 --- .../condition/ConditionalOnClass.java | 7 ++++++- .../src/main/asciidoc/spring-boot-features.adoc | 15 ++++++++++----- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnClass.java b/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnClass.java index ebc959dbd3..3a32320d61 100644 --- a/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnClass.java +++ b/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnClass.java @@ -36,9 +36,14 @@ import org.springframework.context.annotation.Conditional; 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. + * classpath, only if this annotation is directly on the affected component and + * not 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 {}; diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index e2c09eb2d8..774f340a4e 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -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. From 0a55e3e7365a44d2b1986954912f938be5a77398 Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Mon, 10 Apr 2017 16:12:11 +0200 Subject: [PATCH 2/2] Polish "Clarify edge case docs on ConditionalOnClass" Closes gh-8185 --- .../condition/ConditionalOnClass.java | 13 +++++------ .../main/asciidoc/spring-boot-features.adoc | 22 ++++++++++--------- 2 files changed, 17 insertions(+), 18 deletions(-) diff --git a/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnClass.java b/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnClass.java index 3a32320d61..a030852261 100644 --- a/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnClass.java +++ b/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnClass.java @@ -1,5 +1,5 @@ /* - * Copyright 2012-2015 the original author or authors. + * Copyright 2012-2017 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -36,14 +36,11 @@ import org.springframework.context.annotation.Conditional; 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 + * The classes that must be present. Since this annotation is parsed by loading class + * bytecode, it is safe to specify classes here that may ultimately not be on the * classpath, only if this annotation is directly on the affected component and - * not 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. + * not if this annotation is used as a composed, meta-annotation. 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 {}; diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index 774f340a4e..529f0e93a0 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -5839,16 +5839,18 @@ 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. -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. +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. + +[TIP] +==== +If you are using `@ConditionalOnClass` or `@ConditionalOnMissingClass` as apart of a +meta-annotation to compose your own composed annotations you must use `name` as referring +to the class in such a case is not handled. +====