public interface MergedAnnotations extends Iterable<MergedAnnotation<Annotation>>
Class
or Method
.
Each merged annotation represents a view where the attribute values may be "merged" from different source values, typically:
@AliasFor
declarations on one or
more attributes within the annotation@AliasFor
declarations for a meta-annotationFor 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.
MergedAnnotation
,
MergedAnnotationCollectors
,
MergedAnnotationPredicates
,
MergedAnnotationSelectors
Modifier and Type | Interface and Description |
---|---|
static class |
MergedAnnotations.SearchStrategy
Search strategies supported by
from(AnnotatedElement, SearchStrategy) and
variants of that method. |
Modifier and Type | Method and Description |
---|---|
static MergedAnnotations |
from(AnnotatedElement element)
Create a new
MergedAnnotations instance containing all
annotations and meta-annotations from the specified element. |
static MergedAnnotations |
from(AnnotatedElement element,
MergedAnnotations.SearchStrategy searchStrategy)
Create a new
MergedAnnotations instance containing all
annotations and meta-annotations from the specified element and,
depending on the MergedAnnotations.SearchStrategy , related inherited elements. |
static MergedAnnotations |
from(AnnotatedElement element,
MergedAnnotations.SearchStrategy searchStrategy,
RepeatableContainers repeatableContainers)
Create a new
MergedAnnotations instance containing all
annotations and meta-annotations from the specified element and,
depending on the MergedAnnotations.SearchStrategy , related inherited elements. |
static MergedAnnotations |
from(AnnotatedElement element,
MergedAnnotations.SearchStrategy searchStrategy,
RepeatableContainers repeatableContainers,
AnnotationFilter annotationFilter)
Create a new
MergedAnnotations instance containing all
annotations and meta-annotations from the specified element and,
depending on the MergedAnnotations.SearchStrategy , related inherited elements. |
static MergedAnnotations |
from(Annotation... annotations)
Create a new
MergedAnnotations instance from the specified
annotations. |
static MergedAnnotations |
from(Object source,
Annotation... annotations)
Create a new
MergedAnnotations instance from the specified
annotations. |
static MergedAnnotations |
from(Object source,
Annotation[] annotations,
RepeatableContainers repeatableContainers)
Create a new
MergedAnnotations instance from the specified
annotations. |
static MergedAnnotations |
from(Object source,
Annotation[] annotations,
RepeatableContainers repeatableContainers,
AnnotationFilter annotationFilter)
Create a new
MergedAnnotations instance from the specified
annotations. |
<A extends Annotation> |
get(Class<A> annotationType)
Get the nearest matching
annotation or meta-annotation of the specified type, or
MergedAnnotation.missing() if none is present. |
<A extends Annotation> |
get(Class<A> annotationType,
Predicate<? super MergedAnnotation<A>> predicate)
Get the nearest matching
annotation or meta-annotation of the specified type, or
MergedAnnotation.missing() if none is present. |
<A extends Annotation> |
get(Class<A> annotationType,
Predicate<? super MergedAnnotation<A>> predicate,
MergedAnnotationSelector<A> selector)
Get a matching annotation or meta-annotation of the specified type, or
MergedAnnotation.missing() if none is present. |
<A extends Annotation> |
get(String annotationType)
Get the nearest matching
annotation or meta-annotation of the specified type, or
MergedAnnotation.missing() if none is present. |
<A extends Annotation> |
get(String annotationType,
Predicate<? super MergedAnnotation<A>> predicate)
Get the nearest matching
annotation or meta-annotation of the specified type, or
MergedAnnotation.missing() if none is present. |
<A extends Annotation> |
get(String annotationType,
Predicate<? super MergedAnnotation<A>> predicate,
MergedAnnotationSelector<A> selector)
Get a matching annotation or meta-annotation of the specified type, or
MergedAnnotation.missing() if none is present. |
<A extends Annotation> |
isDirectlyPresent(Class<A> annotationType)
Determine if the specified annotation type is directly present.
|
boolean |
isDirectlyPresent(String annotationType)
Determine if the specified annotation type is directly present.
|
<A extends Annotation> |
isPresent(Class<A> annotationType)
Determine if the specified annotation type is either directly present or
meta-present.
|
boolean |
isPresent(String annotationType)
Determine if the specified annotation type is either directly present or
meta-present.
|
static MergedAnnotations |
of(Collection<MergedAnnotation<?>> annotations)
Create a new
MergedAnnotations instance from the specified
collection of directly present annotations. |
Stream<MergedAnnotation<Annotation>> |
stream()
Stream all annotations and meta-annotations contained in this collection.
|
<A extends Annotation> |
stream(Class<A> annotationType)
Stream all annotations and meta-annotations that match the specified
type.
|
<A extends Annotation> |
stream(String annotationType)
Stream all annotations and meta-annotations that match the specified
type.
|
forEach, iterator, spliterator
<A extends Annotation> boolean isPresent(Class<A> annotationType)
Equivalent to calling get(annotationType).isPresent()
.
annotationType
- the annotation type to checktrue
if the annotation is presentboolean isPresent(String annotationType)
Equivalent to calling get(annotationType).isPresent()
.
annotationType
- the fully qualified class name of the annotation type
to checktrue
if the annotation is present<A extends Annotation> boolean isDirectlyPresent(Class<A> annotationType)
Equivalent to calling get(annotationType).isDirectlyPresent()
.
annotationType
- the annotation type to checktrue
if the annotation is directly presentboolean isDirectlyPresent(String annotationType)
Equivalent to calling get(annotationType).isDirectlyPresent()
.
annotationType
- the fully qualified class name of the annotation type
to checktrue
if the annotation is directly present<A extends Annotation> MergedAnnotation<A> get(Class<A> annotationType)
MergedAnnotation.missing()
if none is present.annotationType
- the annotation type to getMergedAnnotation
instance<A extends Annotation> MergedAnnotation<A> get(Class<A> annotationType, @Nullable Predicate<? super MergedAnnotation<A>> predicate)
MergedAnnotation.missing()
if none is present.annotationType
- the annotation type to getpredicate
- a predicate that must match, or null
if only
type matching is requiredMergedAnnotation
instanceMergedAnnotationPredicates
<A extends Annotation> MergedAnnotation<A> get(Class<A> annotationType, @Nullable Predicate<? super MergedAnnotation<A>> predicate, @Nullable MergedAnnotationSelector<A> selector)
MergedAnnotation.missing()
if none is present.annotationType
- the annotation type to getpredicate
- a predicate that must match, or null
if only
type matching is requiredselector
- a selector used to choose the most appropriate annotation
within an aggregate, or null
to select the
nearestMergedAnnotation
instanceMergedAnnotationPredicates
,
MergedAnnotationSelectors
<A extends Annotation> MergedAnnotation<A> get(String annotationType)
MergedAnnotation.missing()
if none is present.annotationType
- the fully qualified class name of the annotation type
to getMergedAnnotation
instance<A extends Annotation> MergedAnnotation<A> get(String annotationType, @Nullable Predicate<? super MergedAnnotation<A>> predicate)
MergedAnnotation.missing()
if none is present.annotationType
- the fully qualified class name of the annotation type
to getpredicate
- a predicate that must match, or null
if only
type matching is requiredMergedAnnotation
instanceMergedAnnotationPredicates
<A extends Annotation> MergedAnnotation<A> get(String annotationType, @Nullable Predicate<? super MergedAnnotation<A>> predicate, @Nullable MergedAnnotationSelector<A> selector)
MergedAnnotation.missing()
if none is present.annotationType
- the fully qualified class name of the annotation type
to getpredicate
- a predicate that must match, or null
if only
type matching is requiredselector
- a selector used to choose the most appropriate annotation
within an aggregate, or null
to select the
nearestMergedAnnotation
instanceMergedAnnotationPredicates
,
MergedAnnotationSelectors
<A extends Annotation> Stream<MergedAnnotation<A>> stream(Class<A> annotationType)
The resulting stream follows the same ordering rules as stream()
.
annotationType
- the annotation type to match<A extends Annotation> Stream<MergedAnnotation<A>> stream(String annotationType)
The resulting stream follows the same ordering rules as stream()
.
annotationType
- the fully qualified class name of the annotation type
to matchStream<MergedAnnotation<Annotation>> stream()
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.
static MergedAnnotations from(AnnotatedElement element)
MergedAnnotations
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 use
from(AnnotatedElement, SearchStrategy)
with an appropriate
MergedAnnotations.SearchStrategy
.
element
- the source elementMergedAnnotations
instance containing the element's
annotationsstatic MergedAnnotations from(AnnotatedElement element, MergedAnnotations.SearchStrategy searchStrategy)
MergedAnnotations
instance containing all
annotations and meta-annotations from the specified element and,
depending on the MergedAnnotations.SearchStrategy
, related inherited elements.element
- the source elementsearchStrategy
- the search strategy to useMergedAnnotations
instance containing the merged
element annotationsstatic MergedAnnotations from(AnnotatedElement element, MergedAnnotations.SearchStrategy searchStrategy, RepeatableContainers repeatableContainers)
MergedAnnotations
instance containing all
annotations and meta-annotations from the specified element and,
depending on the MergedAnnotations.SearchStrategy
, related inherited elements.element
- the source elementsearchStrategy
- the search strategy to userepeatableContainers
- the repeatable containers that may be used by
the element annotations or the meta-annotationsMergedAnnotations
instance containing the merged
element annotationsstatic MergedAnnotations from(AnnotatedElement element, MergedAnnotations.SearchStrategy searchStrategy, RepeatableContainers repeatableContainers, AnnotationFilter annotationFilter)
MergedAnnotations
instance containing all
annotations and meta-annotations from the specified element and,
depending on the MergedAnnotations.SearchStrategy
, related inherited elements.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 consideredMergedAnnotations
instance containing the merged
annotations for the supplied elementstatic MergedAnnotations from(Annotation... annotations)
MergedAnnotations
instance from the specified
annotations.annotations
- the annotations to includeMergedAnnotations
instance containing the annotationsfrom(Object, Annotation...)
static MergedAnnotations from(Object source, Annotation... annotations)
MergedAnnotations
instance from the specified
annotations.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 includeMergedAnnotations
instance containing the annotationsfrom(Annotation...)
,
from(AnnotatedElement)
static MergedAnnotations from(Object source, Annotation[] annotations, RepeatableContainers repeatableContainers)
MergedAnnotations
instance from the specified
annotations.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-annotationsMergedAnnotations
instance containing the annotationsstatic MergedAnnotations from(Object source, Annotation[] annotations, RepeatableContainers repeatableContainers, AnnotationFilter annotationFilter)
MergedAnnotations
instance from the specified
annotations.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 consideredMergedAnnotations
instance containing the annotationsstatic MergedAnnotations of(Collection<MergedAnnotation<?>> annotations)
MergedAnnotations
instance from the specified
collection of directly present annotations. This method allows a
MergedAnnotations
instance to be created from annotations that
are not necessarily loaded using reflection. The provided annotations
must all be directly present
and must have an aggregate
index
of 0
.
The resulting MergedAnnotations
instance will contain both the
specified annotations and any meta-annotations that can be read using
reflection.
annotations
- the annotations to includeMergedAnnotations
instance containing the annotationsMergedAnnotation.of(ClassLoader, Object, Class, java.util.Map)