root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 8 Packages Projects Releases Wiki Activity

Document "present" terminology in AnnotationUtils 

Prior to this commit, the documentation in AnnotationUtils was
inconsistent, and at times even misleading, with regard to finding
annotations that are "present" or "directly present" on annotated
elements.

This commit defines the terminology used within AnnotationUtils and
introduces the explicit notion of "meta-present" to denote that
annotations are present within annotation hierarchies above annotated
elements.

Issue: SPR-13030
This commit is contained in:
Sam Brannen 2015-05-14 21:25:24 +02:00
parent ca410fea53
commit 477d4c5126
1 changed files with 95 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

177
spring-core/src/main/java/org/springframework/core/annotation/AnnotationUtils.java
View File

@ -54,12 +54,20 @@ import org.springframework.util.StringUtils;
* ({@link #getAnnotation(Method, Class)}) and a <em>find</em> lookup in the entire * ({@link #getAnnotation(Method, Class)}) and a <em>find</em> lookup in the entire
* inheritance hierarchy of the given method ({@link #findAnnotation(Method, Class)}). * inheritance hierarchy of the given method ({@link #findAnnotation(Method, Class)}).
* *
* <h3>Terminology</h3>
* The terms <em>directly present</em> and <em>present</em> have the same
* meanings as defined in the class-level Javadoc for {@link AnnotatedElement}.
*
* <p>An annotation is <em>meta-present</em> on an element if the annotation
* is declared as a meta-annotation on some other annotation which is
* <em>present</em> on the element.
*
* <h3>Meta-annotation Support</h3> * <h3>Meta-annotation Support</h3>
* <p>Most {@code find*()} methods and some {@code get*()} methods in this class * <p>Most {@code find*()} methods and some {@code get*()} methods in this
* provide support for meta-annotations. Consult the Javadoc for each method in * class provide support for finding annotations used as meta-annotations.
* this class for details. For support for meta-annotations with * Consult the Javadoc for each method in this class for details. For support
* <em>attribute overrides</em> in <em>composed annotations</em>, use * for meta-annotations with <em>attribute overrides</em> in
* {@link AnnotatedElementUtils} instead. * <em>composed annotations</em>, use {@link AnnotatedElementUtils} instead.
* *
* <h3>Search Scope</h3> * <h3>Search Scope</h3>
* <p>The search algorithms used by methods in this class stop searching for * <p>The search algorithms used by methods in this class stop searching for
@ -122,8 +130,8 @@ public abstract class AnnotationUtils {
/** /**
* Get a single {@link Annotation} of {@code annotationType} from the supplied * Get a single {@link Annotation} of {@code annotationType} from the supplied
* {@link AnnotatedElement}, where the {@code AnnotatedElement} is either * {@link AnnotatedElement}, where the annotation is either <em>present</em> or
* directly annotated or meta-annotated with the {@code annotationType}. * <em>meta-present</em> on the {@code AnnotatedElement}.
* <p>Note that this method supports only a single level of meta-annotations. * <p>Note that this method supports only a single level of meta-annotations.
* For support for arbitrary levels of meta-annotations, use * For support for arbitrary levels of meta-annotations, use
* {@link #findAnnotation(AnnotatedElement, Class)} instead. * {@link #findAnnotation(AnnotatedElement, Class)} instead.
@ -154,8 +162,8 @@ public abstract class AnnotationUtils {
/** /**
* Get a single {@link Annotation} of {@code annotationType} from the * Get a single {@link Annotation} of {@code annotationType} from the
* supplied {@link Method}, where the method is either directly annotated * supplied {@link Method}, where the annotation is either <em>present</em>
* or meta-annotated with the {@code annotationType}. * or <em>meta-present</em> on the method.
* <p>Correctly handles bridge {@link Method Methods} generated by the compiler. * <p>Correctly handles bridge {@link Method Methods} generated by the compiler.
* <p>Note that this method supports only a single level of meta-annotations. * <p>Note that this method supports only a single level of meta-annotations.
* For support for arbitrary levels of meta-annotations, use * For support for arbitrary levels of meta-annotations, use
@ -216,15 +224,17 @@ public abstract class AnnotationUtils {
} }
/** /**
* Get the possibly repeating {@link Annotation}s of {@code annotationType} * Get the <em>repeatable</em> {@link Annotation}s of {@code annotationType}
* from the supplied {@link Method}. * from the supplied {@link Method}, where such annotations are either
* <p>Deals with both a single direct annotation and repeating annotations * <em>present</em> or <em>meta-present</em> on the method.
* nested within a containing annotation. * <p>Handles both single annotations and annotations nested within a
* <em>containing annotation</em>.
* <p>Correctly handles bridge {@link Method Methods} generated by the compiler. * <p>Correctly handles bridge {@link Method Methods} generated by the compiler.
* <p>Meta-annotations will be searched if the annotation is not * <p>Meta-annotations will be searched if the annotation is not
* <em>directly present</em> on the supplied method. * <em>present</em> on the supplied method.
* @param method the method to look for annotations on * @param method the method to look for annotations on; never {@code null}
* @param containerAnnotationType the class of the container that holds the annotations * @param containerAnnotationType the type of the container that holds the
* annotations; may be {@code null} if a container is not supported
* @param annotationType the annotation type to look for * @param annotationType the annotation type to look for
* @return the annotations found or an empty set; never {@code null} * @return the annotations found or an empty set; never {@code null}
* @since 4.0 * @since 4.0
@ -239,14 +249,16 @@ public abstract class AnnotationUtils {
} }
/** /**
* Get the possibly repeating {@link Annotation}s of {@code annotationType} from the * Get the <em>repeatable</em> {@link Annotation}s of {@code annotationType}
* supplied {@link AnnotatedElement}. * from the supplied {@link AnnotatedElement}, where such annotations are
* <p>Deals with both a single direct annotation and repeating annotations * either <em>present</em> or <em>meta-present</em> on the element.
* nested within a containing annotation. * <p>Handles both single annotations and annotations nested within a
* <em>containing annotation</em>.
* <p>Meta-annotations will be searched if the annotation is not * <p>Meta-annotations will be searched if the annotation is not
* <em>directly present</em> on the supplied element. * <em>present</em> on the supplied element.
* @param annotatedElement the element to look for annotations on * @param annotatedElement the element to look for annotations on; never {@code null}
* @param containerAnnotationType the class of the container that holds the annotations * @param containerAnnotationType the type of the container that holds the
* annotations; may be {@code null} if a container is not supported
* @param annotationType the annotation type to look for * @param annotationType the annotation type to look for
* @return the annotations found or an empty set; never {@code null} * @return the annotations found or an empty set; never {@code null}
* @since 4.0 * @since 4.0
@ -328,7 +340,8 @@ public abstract class AnnotationUtils {
/** /**
* Find a single {@link Annotation} of {@code annotationType} on the supplied * Find a single {@link Annotation} of {@code annotationType} on the supplied
* {@link Method}, traversing its super methods (i.e., from superclasses and * {@link Method}, traversing its super methods (i.e., from superclasses and
* interfaces) if no annotation can be found on the given method itself. * interfaces) if the annotation is not <em>directly present</em> on the given
* method itself.
* <p>Correctly handles bridge {@link Method Methods} generated by the compiler. * <p>Correctly handles bridge {@link Method Methods} generated by the compiler.
* <p>Meta-annotations will be searched if the annotation is not * <p>Meta-annotations will be searched if the annotation is not
* <em>directly present</em> on the method. * <em>directly present</em> on the method.
@ -423,8 +436,8 @@ public abstract class AnnotationUtils {
/** /**
* Find a single {@link Annotation} of {@code annotationType} on the * Find a single {@link Annotation} of {@code annotationType} on the
* supplied {@link Class}, traversing its interfaces, annotations, and * supplied {@link Class}, traversing its interfaces, annotations, and
* superclasses if the annotation is not <em>present</em> on the given class * superclasses if the annotation is not <em>directly present</em> on
* itself. * the given class itself.
* <p>This method explicitly handles class-level annotations which are not * <p>This method explicitly handles class-level annotations which are not
* declared as {@link java.lang.annotation.Inherited inherited} <em>as well * declared as {@link java.lang.annotation.Inherited inherited} <em>as well
* as meta-annotations and annotations on interfaces</em>. * as meta-annotations and annotations on interfaces</em>.
@ -505,21 +518,22 @@ public abstract class AnnotationUtils {
} }
/** /**
* Find the first {@link Class} in the inheritance hierarchy of the specified {@code clazz} * Find the first {@link Class} in the inheritance hierarchy of the
* (including the specified {@code clazz} itself) which declares an annotation for the * specified {@code clazz} (including the specified {@code clazz} itself)
* specified {@code annotationType}, or {@code null} if not found. If the supplied * on which an annotation of the specified {@code annotationType} is
* {@code clazz} is {@code null}, {@code null} will be returned. * <em>directly present</em>.
* <p>If the supplied {@code clazz} is an interface, only the interface itself will be checked; * <p>If the supplied {@code clazz} is an interface, only the interface
* the inheritance hierarchy for interfaces will not be traversed. * itself will be checked; the inheritance hierarchy for interfaces will
* not be traversed.
* <p>Meta-annotations will <em>not</em> be searched. * <p>Meta-annotations will <em>not</em> be searched.
* <p>The standard {@link Class} API does not provide a mechanism for determining which class * <p>The standard {@link Class} API does not provide a mechanism for
* in an inheritance hierarchy actually declares an {@link Annotation}, so we need to handle * determining which class in an inheritance hierarchy actually declares
* this explicitly. * an {@link Annotation}, so we need to handle this explicitly.
* @param annotationType the annotation type to look for, both locally and as a meta-annotation * @param annotationType the annotation type to look for
* @param clazz the class on which to check for the annotation (may be {@code null}) * @param clazz the class to check for the annotation on (may be {@code null})
* @return the first {@link Class} in the inheritance hierarchy of the specified {@code clazz} * @return the first {@link Class} in the inheritance hierarchy that
* which declares an annotation of the specified {@code annotationType}, or {@code null} * declares an annotation of the specified {@code annotationType}, or
* if not found * {@code null} if not found
* @see Class#isAnnotationPresent(Class) * @see Class#isAnnotationPresent(Class)
* @see Class#getDeclaredAnnotations() * @see Class#getDeclaredAnnotations()
* @see #findAnnotationDeclaringClassForTypes(List, Class) * @see #findAnnotationDeclaringClassForTypes(List, Class)
@ -537,25 +551,22 @@ public abstract class AnnotationUtils {
} }
/** /**
* Find the first {@link Class} in the inheritance hierarchy of the specified * Find the first {@link Class} in the inheritance hierarchy of the
* {@code clazz} (including the specified {@code clazz} itself) which declares * specified {@code clazz} (including the specified {@code clazz} itself)
* at least one of the specified {@code annotationTypes}, or {@code null} if * on which at least one of the specified {@code annotationTypes} is
* none of the specified annotation types could be found. * <em>directly present</em>.
* <p>If the supplied {@code clazz} is {@code null}, {@code null} will be * <p>If the supplied {@code clazz} is an interface, only the interface
* returned. * itself will be checked; the inheritance hierarchy for interfaces will
* <p>If the supplied {@code clazz} is an interface, only the interface itself * not be traversed.
* will be checked; the inheritance hierarchy for interfaces will not be traversed.
* <p>Meta-annotations will <em>not</em> be searched. * <p>Meta-annotations will <em>not</em> be searched.
* <p>The standard {@link Class} API does not provide a mechanism for determining * <p>The standard {@link Class} API does not provide a mechanism for
* which class in an inheritance hierarchy actually declares one of several * determining which class in an inheritance hierarchy actually declares
* candidate {@linkplain Annotation annotations}, so we need to handle this * one of several candidate {@linkplain Annotation annotations}, so we
* explicitly. * need to handle this explicitly.
* @param annotationTypes the list of Class objects corresponding to the * @param annotationTypes the annotation types to look for
* annotation types * @param clazz the class to check for the annotations on, or {@code null}
* @param clazz the Class object corresponding to the class on which to check * @return the first {@link Class} in the inheritance hierarchy that
* for the annotations, or {@code null} * declares an annotation of at least one of the specified
* @return the first {@link Class} in the inheritance hierarchy of the specified
* {@code clazz} which declares an annotation of at least one of the specified
* {@code annotationTypes}, or {@code null} if not found * {@code annotationTypes}, or {@code null} if not found
* @since 3.2.2 * @since 3.2.2
* @see Class#isAnnotationPresent(Class) * @see Class#isAnnotationPresent(Class)
@ -577,18 +588,19 @@ public abstract class AnnotationUtils {
} }
/** /**
* Determine whether an annotation of the specified {@code annotationType} is * Determine whether an annotation of the specified {@code annotationType}
* declared locally (i.e., <em>directly present</em>) on the supplied * is declared locally (i.e., <em>directly present</em>) on the supplied
* {@code clazz}. The supplied {@link Class} may represent any type. * {@code clazz}.
* <p>The supplied {@link Class} may represent any type.
* <p>Meta-annotations will <em>not</em> be searched. * <p>Meta-annotations will <em>not</em> be searched.
* <p>Note: This method does <strong>not</strong> determine if the annotation is * <p>Note: This method does <strong>not</strong> determine if the annotation
* {@linkplain java.lang.annotation.Inherited inherited}. For greater clarity * is {@linkplain java.lang.annotation.Inherited inherited}. For greater
* regarding inherited annotations, consider using * clarity regarding inherited annotations, consider using
* {@link #isAnnotationInherited(Class, Class)} instead. * {@link #isAnnotationInherited(Class, Class)} instead.
* @param annotationType the Class object corresponding to the annotation type * @param annotationType the annotation type to look for
* @param clazz the Class object corresponding to the class on which to check for the annotation * @param clazz the class to check for the annotation on
* @return {@code true} if an annotation of the specified {@code annotationType} * @return {@code true} if an annotation of the specified {@code annotationType}
* is <em>directly present</em> on the supplied {@code clazz} * is <em>directly present</em>
* @see java.lang.Class#getDeclaredAnnotations() * @see java.lang.Class#getDeclaredAnnotations()
* @see java.lang.Class#getDeclaredAnnotation(Class) * @see java.lang.Class#getDeclaredAnnotation(Class)
* @see #isAnnotationInherited(Class, Class) * @see #isAnnotationInherited(Class, Class)
@ -596,12 +608,10 @@ public abstract class AnnotationUtils {
public static boolean isAnnotationDeclaredLocally(Class<? extends Annotation> annotationType, Class<?> clazz) { public static boolean isAnnotationDeclaredLocally(Class<? extends Annotation> annotationType, Class<?> clazz) {
Assert.notNull(annotationType, "Annotation type must not be null"); Assert.notNull(annotationType, "Annotation type must not be null");
Assert.notNull(clazz, "Class must not be null"); Assert.notNull(clazz, "Class must not be null");
boolean declaredLocally = false;
try { try {
for (Annotation ann : clazz.getDeclaredAnnotations()) { for (Annotation ann : clazz.getDeclaredAnnotations()) {
if (ann.annotationType().equals(annotationType)) { if (ann.annotationType().equals(annotationType)) {
declaredLocally = true; return true;
break;
} }
} }
} }
@ -609,22 +619,25 @@ public abstract class AnnotationUtils {
// Assuming nested Class values not resolvable within annotation attributes... // Assuming nested Class values not resolvable within annotation attributes...
logIntrospectionFailure(clazz, ex); logIntrospectionFailure(clazz, ex);
} }
return declaredLocally; return false;
} }
/** /**
* Determine whether an annotation of the specified {@code annotationType} is <em>present</em> * Determine whether an annotation of the specified {@code annotationType}
* on the supplied {@code clazz} and is {@linkplain java.lang.annotation.Inherited inherited} * is <em>present</em> on the supplied {@code clazz} and is
* (i.e., not declared locally for the class). * {@linkplain java.lang.annotation.Inherited inherited} (i.e., not
* <em>directly present</em>).
* <p>Meta-annotations will <em>not</em> be searched. * <p>Meta-annotations will <em>not</em> be searched.
* <p>If the supplied {@code clazz} is an interface, only the interface itself will be checked. * <p>If the supplied {@code clazz} is an interface, only the interface
* In accordance with standard meta-annotation semantics, the inheritance hierarchy for interfaces * itself will be checked. In accordance with standard meta-annotation
* will not be traversed. See the {@linkplain java.lang.annotation.Inherited Javadoc} for the * semantics in Java, the inheritance hierarchy for interfaces will not
* {@code @Inherited} meta-annotation for further details regarding annotation inheritance. * be traversed. See the {@linkplain java.lang.annotation.Inherited Javadoc}
* @param annotationType the Class object corresponding to the annotation type * for the {@code @Inherited} meta-annotation for further details regarding
* @param clazz the Class object corresponding to the class on which to check for the annotation * annotation inheritance.
* @return {@code true} if an annotation of the specified {@code annotationType} is present * @param annotationType the annotation type to look for
* on the supplied {@code clazz} and is <em>inherited</em> * @param clazz the class to check for the annotation on
* @return {@code true} if an annotation of the specified {@code annotationType}
* is <em>present</em> and <em>inherited</em>
* @see Class#isAnnotationPresent(Class) * @see Class#isAnnotationPresent(Class)
* @see #isAnnotationDeclaredLocally(Class, Class) * @see #isAnnotationDeclaredLocally(Class, Class)
*/ */