Interface MergedAnnotations
- All Superinterfaces:
Iterable<MergedAnnotation<Annotation>>
Class
or Method
.
Each merged annotation represents a view where the attribute values may be "merged" from different source values, typically:
- Explicit and Implicit
@AliasFor
declarations on one or more attributes within the annotation - Explicit
@AliasFor
declarations for a meta-annotation - Convention based attribute aliases for a meta-annotation
- From a meta-annotation declaration
For example, a @PostMapping
annotation might be defined as follows:
@Retention(RetentionPolicy.RUNTIME) @RequestMapping(method = RequestMethod.POST) public @interface PostMapping { @AliasFor(attribute = "path") String[] value() default {}; @AliasFor(attribute = "value") String[] path() default {}; }
If a method is annotated with @PostMapping("/home")
it will contain
merged annotations for both @PostMapping
and the meta-annotation
@RequestMapping
. The merged view of the @RequestMapping
annotation will contain the following attributes:
Name | Value | Source |
---|---|---|
value | "/home" | Declared in @PostMapping |
path | "/home" | Explicit @AliasFor |
method | RequestMethod.POST | Declared in meta-annotation |
MergedAnnotations
can be obtained from any Java AnnotatedElement
. They may also be used for sources that
don't use reflection (such as those that directly parse bytecode).
Different search strategies can be used to locate
related source elements that contain the annotations to be aggregated. For
example, MergedAnnotations.SearchStrategy.TYPE_HIERARCHY
will search both superclasses and
implemented interfaces.
From a MergedAnnotations
instance you can either
get a single annotation, or stream all annotations or just those that match a specific type. You can also quickly tell if an annotation
is present.
Here are some typical examples:
// is an annotation present or meta-present? mergedAnnotations.isPresent(ExampleAnnotation.class); // get the merged "value" attribute of ExampleAnnotation (either directly or // meta-present) mergedAnnotations.get(ExampleAnnotation.class).getString("value"); // get all meta-annotations but no directly present annotations mergedAnnotations.stream().filter(MergedAnnotation::isMetaPresent); // get all ExampleAnnotation declarations (including any meta-annotations) and // print the merged "value" attributes mergedAnnotations.stream(ExampleAnnotation.class) .map(mergedAnnotation -> mergedAnnotation.getString("value")) .forEach(System.out::println);
NOTE: The MergedAnnotations
API and its underlying model have
been designed for composable annotations in Spring's common component model,
with a focus on attribute aliasing and meta-annotation relationships.
There is no support for retrieving plain Java annotations with this API;
please use standard Java reflection or Spring's AnnotationUtils
for simple annotation retrieval purposes.
- Since:
- 5.2
- Author:
- Phillip Webb, Sam Brannen
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic enum
Search strategies supported byfrom(AnnotatedElement, SearchStrategy)
. -
Method Summary
Modifier and TypeMethodDescriptionstatic MergedAnnotations
from
(Annotation... annotations) Create a newMergedAnnotations
instance from the specified annotations.static MergedAnnotations
from
(Object source, Annotation... annotations) Create a newMergedAnnotations
instance from the specified annotations.static MergedAnnotations
from
(Object source, Annotation[] annotations, RepeatableContainers repeatableContainers) Create a newMergedAnnotations
instance from the specified annotations.static MergedAnnotations
from
(Object source, Annotation[] annotations, RepeatableContainers repeatableContainers, AnnotationFilter annotationFilter) Create a newMergedAnnotations
instance from the specified annotations.static MergedAnnotations
from
(AnnotatedElement element) Create a newMergedAnnotations
instance containing all annotations and meta-annotations from the specified element.static MergedAnnotations
from
(AnnotatedElement element, MergedAnnotations.SearchStrategy searchStrategy) Create a newMergedAnnotations
instance containing all annotations and meta-annotations from the specified element and, depending on theMergedAnnotations.SearchStrategy
, related inherited elements.static MergedAnnotations
from
(AnnotatedElement element, MergedAnnotations.SearchStrategy searchStrategy, RepeatableContainers repeatableContainers) Create a newMergedAnnotations
instance containing all annotations and meta-annotations from the specified element and, depending on theMergedAnnotations.SearchStrategy
, related inherited elements.static MergedAnnotations
from
(AnnotatedElement element, MergedAnnotations.SearchStrategy searchStrategy, RepeatableContainers repeatableContainers, AnnotationFilter annotationFilter) Create a newMergedAnnotations
instance containing all annotations and meta-annotations from the specified element and, depending on theMergedAnnotations.SearchStrategy
, related inherited elements.<A extends Annotation>
MergedAnnotation<A>Get the nearest matching annotation or meta-annotation of the specified type, orMergedAnnotation.missing()
if none is present.<A extends Annotation>
MergedAnnotation<A>get
(Class<A> annotationType, Predicate<? super MergedAnnotation<A>> predicate) Get the nearest matching annotation or meta-annotation of the specified type, orMergedAnnotation.missing()
if none is present.<A extends Annotation>
MergedAnnotation<A>get
(Class<A> annotationType, Predicate<? super MergedAnnotation<A>> predicate, MergedAnnotationSelector<A> selector) Get a matching annotation or meta-annotation of the specified type, orMergedAnnotation.missing()
if none is present.<A extends Annotation>
MergedAnnotation<A>Get the nearest matching annotation or meta-annotation of the specified type, orMergedAnnotation.missing()
if none is present.<A extends Annotation>
MergedAnnotation<A>get
(String annotationType, Predicate<? super MergedAnnotation<A>> predicate) Get the nearest matching annotation or meta-annotation of the specified type, orMergedAnnotation.missing()
if none is present.<A extends Annotation>
MergedAnnotation<A>get
(String annotationType, Predicate<? super MergedAnnotation<A>> predicate, MergedAnnotationSelector<A> selector) Get a matching annotation or meta-annotation of the specified type, orMergedAnnotation.missing()
if none is present.<A extends Annotation>
booleanisDirectlyPresent
(Class<A> annotationType) Determine if the specified annotation is directly present.boolean
isDirectlyPresent
(String annotationType) Determine if the specified annotation is directly present.<A extends Annotation>
booleanDetermine if the specified annotation is either directly present or meta-present.boolean
Determine if the specified annotation is either directly present or meta-present.static MergedAnnotations
of
(Collection<MergedAnnotation<?>> annotations) Create a newMergedAnnotations
instance from the specified collection of directly present annotations.stream()
Stream all annotations and meta-annotations contained in this collection.<A extends Annotation>
Stream<MergedAnnotation<A>>Stream all annotations and meta-annotations that match the specified type.<A extends Annotation>
Stream<MergedAnnotation<A>>Stream all annotations and meta-annotations that match the specified type.Methods inherited from interface java.lang.Iterable
forEach, iterator, spliterator
-
Method Details
-
isPresent
Determine if the specified annotation is either directly present or meta-present.Equivalent to calling
get(annotationType).isPresent()
.- Parameters:
annotationType
- the annotation type to check- Returns:
true
if the annotation is present
-
isPresent
Determine if the specified annotation is either directly present or meta-present.Equivalent to calling
get(annotationType).isPresent()
.- Parameters:
annotationType
- the fully qualified class name of the annotation type to check- Returns:
true
if the annotation is present
-
isDirectlyPresent
Determine if the specified annotation is directly present.Equivalent to calling
get(annotationType).isDirectlyPresent()
.- Parameters:
annotationType
- the annotation type to check- Returns:
true
if the annotation is directly present
-
isDirectlyPresent
Determine if the specified annotation is directly present.Equivalent to calling
get(annotationType).isDirectlyPresent()
.- Parameters:
annotationType
- the fully qualified class name of the annotation type to check- Returns:
true
if the annotation is directly present
-
get
Get the nearest matching annotation or meta-annotation of the specified type, orMergedAnnotation.missing()
if none is present.- Parameters:
annotationType
- the annotation type to get- Returns:
- a
MergedAnnotation
instance
-
get
<A extends Annotation> MergedAnnotation<A> get(Class<A> annotationType, @Nullable Predicate<? super MergedAnnotation<A>> predicate) Get the nearest matching annotation or meta-annotation of the specified type, orMergedAnnotation.missing()
if none is present.- Parameters:
annotationType
- the annotation type to getpredicate
- a predicate that must match, ornull
if only type matching is required- Returns:
- a
MergedAnnotation
instance - See Also:
-
get
<A extends Annotation> MergedAnnotation<A> get(Class<A> annotationType, @Nullable Predicate<? super MergedAnnotation<A>> predicate, @Nullable MergedAnnotationSelector<A> selector) Get a matching annotation or meta-annotation of the specified type, orMergedAnnotation.missing()
if none is present.- Parameters:
annotationType
- the annotation type to getpredicate
- a predicate that must match, ornull
if only type matching is requiredselector
- a selector used to choose the most appropriate annotation within an aggregate, ornull
to select the nearest- Returns:
- a
MergedAnnotation
instance - See Also:
-
get
Get the nearest matching annotation or meta-annotation of the specified type, orMergedAnnotation.missing()
if none is present.- Parameters:
annotationType
- the fully qualified class name of the annotation type to get- Returns:
- a
MergedAnnotation
instance
-
get
<A extends Annotation> MergedAnnotation<A> get(String annotationType, @Nullable Predicate<? super MergedAnnotation<A>> predicate) Get the nearest matching annotation or meta-annotation of the specified type, orMergedAnnotation.missing()
if none is present.- Parameters:
annotationType
- the fully qualified class name of the annotation type to getpredicate
- a predicate that must match, ornull
if only type matching is required- Returns:
- a
MergedAnnotation
instance - See Also:
-
get
<A extends Annotation> MergedAnnotation<A> get(String annotationType, @Nullable Predicate<? super MergedAnnotation<A>> predicate, @Nullable MergedAnnotationSelector<A> selector) Get a matching annotation or meta-annotation of the specified type, orMergedAnnotation.missing()
if none is present.- Parameters:
annotationType
- the fully qualified class name of the annotation type to getpredicate
- a predicate that must match, ornull
if only type matching is requiredselector
- a selector used to choose the most appropriate annotation within an aggregate, ornull
to select the nearest- Returns:
- a
MergedAnnotation
instance - See Also:
-
stream
Stream all annotations and meta-annotations that match the specified type. The resulting stream follows the same ordering rules asstream()
.- Parameters:
annotationType
- the annotation type to match- Returns:
- a stream of matching annotations
-
stream
Stream all annotations and meta-annotations that match the specified type. The resulting stream follows the same ordering rules asstream()
.- Parameters:
annotationType
- the fully qualified class name of the annotation type to match- Returns:
- a stream of matching annotations
-
stream
Stream<MergedAnnotation<Annotation>> stream()Stream all annotations and meta-annotations contained in this collection. The resulting stream is ordered first by the aggregate index and then by the annotation distance (with the closest annotations first). This ordering means that, for most use-cases, the most suitable annotations appear earliest in the stream.- Returns:
- a stream of annotations
-
from
Create a newMergedAnnotations
instance containing all annotations and meta-annotations from the specified element. The resulting instance will not include any inherited annotations. If you want to include those as well you should usefrom(AnnotatedElement, SearchStrategy)
with an appropriateMergedAnnotations.SearchStrategy
.- Parameters:
element
- the source element- Returns:
- a
MergedAnnotations
instance containing the element's annotations
-
from
static MergedAnnotations from(AnnotatedElement element, MergedAnnotations.SearchStrategy searchStrategy) Create a newMergedAnnotations
instance containing all annotations and meta-annotations from the specified element and, depending on theMergedAnnotations.SearchStrategy
, related inherited elements.- Parameters:
element
- the source elementsearchStrategy
- the search strategy to use- Returns:
- a
MergedAnnotations
instance containing the merged element annotations
-
from
static MergedAnnotations from(AnnotatedElement element, MergedAnnotations.SearchStrategy searchStrategy, RepeatableContainers repeatableContainers) Create a newMergedAnnotations
instance containing all annotations and meta-annotations from the specified element and, depending on theMergedAnnotations.SearchStrategy
, related inherited elements.- Parameters:
element
- the source elementsearchStrategy
- the search strategy to userepeatableContainers
- the repeatable containers that may be used by the element annotations or the meta-annotations- Returns:
- a
MergedAnnotations
instance containing the merged element annotations
-
from
static MergedAnnotations from(AnnotatedElement element, MergedAnnotations.SearchStrategy searchStrategy, RepeatableContainers repeatableContainers, AnnotationFilter annotationFilter) Create a newMergedAnnotations
instance containing all annotations and meta-annotations from the specified element and, depending on theMergedAnnotations.SearchStrategy
, related inherited elements.- Parameters:
element
- the source elementsearchStrategy
- the search strategy to userepeatableContainers
- the repeatable containers that may be used by the element annotations or the meta-annotationsannotationFilter
- an annotation filter used to restrict the annotations considered- Returns:
- a
MergedAnnotations
instance containing the merged annotations for the supplied element
-
from
Create a newMergedAnnotations
instance from the specified annotations.- Parameters:
annotations
- the annotations to include- Returns:
- a
MergedAnnotations
instance containing the annotations - See Also:
-
from
Create a newMergedAnnotations
instance from the specified annotations.- Parameters:
source
- the source for the annotations. This source is used only for information and logging. It does not need to actually contain the specified annotations, and it will not be searched.annotations
- the annotations to include- Returns:
- a
MergedAnnotations
instance containing the annotations - See Also:
-
from
static MergedAnnotations from(Object source, Annotation[] annotations, RepeatableContainers repeatableContainers) Create a newMergedAnnotations
instance from the specified annotations.- Parameters:
source
- the source for the annotations. This source is used only for information and logging. It does not need to actually contain the specified annotations, and it will not be searched.annotations
- the annotations to includerepeatableContainers
- the repeatable containers that may be used by meta-annotations- Returns:
- a
MergedAnnotations
instance containing the annotations
-
from
static MergedAnnotations from(Object source, Annotation[] annotations, RepeatableContainers repeatableContainers, AnnotationFilter annotationFilter) Create a newMergedAnnotations
instance from the specified annotations.- Parameters:
source
- the source for the annotations. This source is used only for information and logging. It does not need to actually contain the specified annotations, and it will not be searched.annotations
- the annotations to includerepeatableContainers
- the repeatable containers that may be used by meta-annotationsannotationFilter
- an annotation filter used to restrict the annotations considered- Returns:
- a
MergedAnnotations
instance containing the annotations
-
of
Create a newMergedAnnotations
instance from the specified collection of directly present annotations. This method allows aMergedAnnotations
instance to be created from annotations that are not necessarily loaded using reflection. The provided annotations must all bedirectly present
and must have anaggregate index
of0
.The resulting
MergedAnnotations
instance will contain both the specified annotations, and any meta-annotations that can be read using reflection.- Parameters:
annotations
- the annotations to include- Returns:
- a
MergedAnnotations
instance containing the annotations - See Also:
-