org.springframework.test.util

Class MetaAnnotationUtils

java.lang.Object

org.springframework.test.util.MetaAnnotationUtils

public abstract class MetaAnnotationUtils
extends java.lang.Object

MetaAnnotationUtils is a collection of utility methods that complements the standard support already available in AnnotationUtils.

Whereas AnnotationUtils provides utilities for getting or finding an annotation, MetaAnnotationUtils goes a step further by providing support for determining the root class on which an annotation is declared, either directly or indirectly via a composed annotation. This additional information is encapsulated in an MetaAnnotationUtils.AnnotationDescriptor.

The additional information provided by an AnnotationDescriptor is required by the Spring TestContext Framework in order to be able to support class hierarchy traversals for annotations such as @ContextConfiguration, @TestExecutionListeners, and @ActiveProfiles which offer support for merging and overriding various inherited annotation attributes (e.g. ContextConfiguration.inheritLocations()).

Since:

4.0

Author:

Sam Brannen

See Also:

AnnotationUtils, MetaAnnotationUtils.AnnotationDescriptor

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MetaAnnotationUtils.AnnotationDescriptor<T extends java.lang.annotation.Annotation> Descriptor for an Annotation, including the class on which the annotation is declared as well as the actual annotation instance.
static class	MetaAnnotationUtils.UntypedAnnotationDescriptor Untyped extension of AnnotationDescriptor that is used to describe the declaration of one of several candidate annotation types where the actual annotation type cannot be predetermined.

Constructor Summary

Constructors

Constructor and Description
MetaAnnotationUtils()

Method Summary

Modifier and Type	Method and Description
private static void	assertNonEmptyAnnotationTypeArray(java.lang.Class<?>[] annotationTypes, java.lang.String message)
static <T extends java.lang.annotation.Annotation> MetaAnnotationUtils.AnnotationDescriptor<T>	findAnnotationDescriptor(java.lang.Class<?> clazz, java.lang.Class<T> annotationType) Find the MetaAnnotationUtils.AnnotationDescriptor for the supplied annotationType on the supplied Class, traversing its annotations and superclasses if no annotation can be found on the given class itself.
private static <T extends java.lang.annotation.Annotation> MetaAnnotationUtils.AnnotationDescriptor<T>	findAnnotationDescriptor(java.lang.Class<?> clazz, java.util.Set<java.lang.annotation.Annotation> visited, java.lang.Class<T> annotationType) Perform the search algorithm for findAnnotationDescriptor(Class, Class), avoiding endless recursion by tracking which annotations have already been visited.
static MetaAnnotationUtils.UntypedAnnotationDescriptor	findAnnotationDescriptorForTypes(java.lang.Class<?> clazz, java.lang.Class<? extends java.lang.annotation.Annotation>... annotationTypes) Find the MetaAnnotationUtils.UntypedAnnotationDescriptor for the first Class in the inheritance hierarchy of the specified clazz (including the specified clazz itself) which declares at least one of the specified annotationTypes.
private static MetaAnnotationUtils.UntypedAnnotationDescriptor	findAnnotationDescriptorForTypes(java.lang.Class<?> clazz, java.util.Set<java.lang.annotation.Annotation> visited, java.lang.Class<? extends java.lang.annotation.Annotation>... annotationTypes) Perform the search algorithm for findAnnotationDescriptorForTypes(Class, Class...), avoiding endless recursion by tracking which annotations have already been visited.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetaAnnotationUtils

public MetaAnnotationUtils()

Method Detail

findAnnotationDescriptor

public static <T extends java.lang.annotation.Annotation> MetaAnnotationUtils.AnnotationDescriptor<T> findAnnotationDescriptor(java.lang.Class<?> clazz,
                                                                                                                               java.lang.Class<T> annotationType)

Find the MetaAnnotationUtils.AnnotationDescriptor for the supplied annotationType on the supplied Class, traversing its annotations and superclasses if no annotation can be found on the given class itself.

This method explicitly handles class-level annotations which are not declared as inherited as well as meta-annotations.

The algorithm operates as follows:

1. Search for the annotation on the given class and return a corresponding AnnotationDescriptor if found.
2. Recursively search through all annotations that the given class declares.
3. Recursively search through the superclass hierarchy of the given class.

In this context, the term recursively means that the search process continues by returning to step #1 with the current annotation or superclass as the class to look for annotations on.

If the supplied clazz is an interface, only the interface itself will be checked; the inheritance hierarchy for interfaces will not be traversed.

Parameters:

clazz - the class to look for annotations on

annotationType - the type of annotation to look for

Returns:

the corresponding annotation descriptor if the annotation was found; otherwise null

See Also:

AnnotationUtils.findAnnotationDeclaringClass(Class, Class), findAnnotationDescriptorForTypes(Class, Class...)

findAnnotationDescriptor

private static <T extends java.lang.annotation.Annotation> MetaAnnotationUtils.AnnotationDescriptor<T> findAnnotationDescriptor(java.lang.Class<?> clazz,
                                                                                                                                java.util.Set<java.lang.annotation.Annotation> visited,
                                                                                                                                java.lang.Class<T> annotationType)

Perform the search algorithm for findAnnotationDescriptor(Class, Class), avoiding endless recursion by tracking which annotations have already been visited.

Parameters:

clazz - the class to look for annotations on

visited - the set of annotations that have already been visited

annotationType - the type of annotation to look for

Returns:

the corresponding annotation descriptor if the annotation was found; otherwise null

findAnnotationDescriptorForTypes

public static MetaAnnotationUtils.UntypedAnnotationDescriptor findAnnotationDescriptorForTypes(java.lang.Class<?> clazz,
                                                                                               java.lang.Class<? extends java.lang.annotation.Annotation>... annotationTypes)

Find the MetaAnnotationUtils.UntypedAnnotationDescriptor for the first Class in the inheritance hierarchy of the specified clazz (including the specified clazz itself) which declares at least one of the specified annotationTypes.

This method traverses the annotations and superclasses of the specified clazz if no annotation can be found on the given class itself.

This method explicitly handles class-level annotations which are not declared as inherited as well as meta-annotations.

The algorithm operates as follows:

1. Search for a local declaration of one of the annotation types on the given class and return a corresponding UntypedAnnotationDescriptor if found.
2. Recursively search through all annotations that the given class declares.
3. Recursively search through the superclass hierarchy of the given class.

In this context, the term recursively means that the search process continues by returning to step #1 with the current annotation or superclass as the class to look for annotations on.

If the supplied clazz is an interface, only the interface itself will be checked; the inheritance hierarchy for interfaces will not be traversed.

Parameters:

clazz - the class to look for annotations on

annotationTypes - the types of annotations to look for

Returns:

the corresponding annotation descriptor if one of the annotations was found; otherwise null

See Also:

AnnotationUtils.findAnnotationDeclaringClassForTypes(java.util.List, Class), findAnnotationDescriptor(Class, Class)

findAnnotationDescriptorForTypes

private static MetaAnnotationUtils.UntypedAnnotationDescriptor findAnnotationDescriptorForTypes(java.lang.Class<?> clazz,
                                                                                                java.util.Set<java.lang.annotation.Annotation> visited,
                                                                                                java.lang.Class<? extends java.lang.annotation.Annotation>... annotationTypes)

Perform the search algorithm for findAnnotationDescriptorForTypes(Class, Class...), avoiding endless recursion by tracking which annotations have already been visited.

Parameters:

clazz - the class to look for annotations on

visited - the set of annotations that have already been visited

annotationTypes - the types of annotations to look for

Returns:

the corresponding annotation descriptor if one of the annotations was found; otherwise null

assertNonEmptyAnnotationTypeArray

private static void assertNonEmptyAnnotationTypeArray(java.lang.Class<?>[] annotationTypes,
                                                      java.lang.String message)