org.springframework.core.annotation

Interface MergedAnnotation<A extends java.lang.annotation.Annotation>

Type Parameters:

A - the annotation type

All Known Implementing Classes:

AbstractMergedAnnotation, MissingMergedAnnotation, TypeMappedAnnotation

public interface MergedAnnotation<A extends java.lang.annotation.Annotation>

A single merged annotation returned from a MergedAnnotations collection. Presents a view onto an annotation where attribute values may have been "merged" from different source values.

Attribute values may be accessed using the various get methods. For example, to access an int attribute the getInt(String) method would be used.

Note that attribute values are not converted when accessed. For example, it is not possible to call getString(String) if the underlying attribute is an int. The only exception to this rule is Class and Class[] values which may be accessed as String and String[] respectively to prevent potential early class initialization.

If necessary, a MergedAnnotation can be synthesized back into an actual Annotation.

Since:

5.2

Author:

Phillip Webb, Juergen Hoeller, Sam Brannen

See Also:

MergedAnnotations, MergedAnnotationPredicates

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	MergedAnnotation.Adapt Adaptations that can be applied to attributes values when creating Maps or AnnotationAttributes.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	VALUE The attribute name for annotations with a single element.

Method Summary

Modifier and Type	Method and Description
AnnotationAttributes	asAnnotationAttributes(MergedAnnotation.Adapt... adaptations) Create a new mutable AnnotationAttributes instance from this merged annotation.
<T extends java.util.Map<java.lang.String,java.lang.Object>> T	asMap(java.util.function.Function<MergedAnnotation<?>,T> factory, MergedAnnotation.Adapt... adaptations) Create a new Map instance of the given type that contains all the annotation attributes.
java.util.Map<java.lang.String,java.lang.Object>	asMap(MergedAnnotation.Adapt... adaptations) Return an immutable Map that contains all the annotation attributes.
MergedAnnotation<A>	filterAttributes(java.util.function.Predicate<java.lang.String> predicate) Create a new view of the annotation with only attributes that match the given predicate.
MergedAnnotation<A>	filterDefaultValues() Create a new view of the annotation with all attributes that have default values removed.
static <A extends java.lang.annotation.Annotation> MergedAnnotation<A>	from(A annotation) Create a new MergedAnnotation instance from the specified annotation.
static <A extends java.lang.annotation.Annotation> MergedAnnotation<A>	from(java.lang.reflect.AnnotatedElement source, java.lang.Class<A> annotationType, java.util.Map<java.lang.String,?> attributes) Create a new MergedAnnotation instance from the specified annotation type and attributes map.
static <A extends java.lang.annotation.Annotation> MergedAnnotation<A>	from(java.lang.Class<A> annotationType) Create a new MergedAnnotation instance from the specified annotation type.
static <A extends java.lang.annotation.Annotation> MergedAnnotation<A>	from(java.lang.Class<A> annotationType, java.util.Map<java.lang.String,?> attributes) Create a new MergedAnnotation instance from the specified annotation type and attributes map.
static <A extends java.lang.annotation.Annotation> MergedAnnotation<A>	from(java.lang.Object source, A annotation) Create a new MergedAnnotation instance from the specified annotation.
int	getAggregateIndex() Get the index of the aggregate collection containing this annotation.
<T extends java.lang.annotation.Annotation> MergedAnnotation<T>	getAnnotation(java.lang.String attributeName, java.lang.Class<T> type) Get a required annotation attribute value from the annotation.
<T extends java.lang.annotation.Annotation> MergedAnnotation<T>[]	getAnnotationArray(java.lang.String attributeName, java.lang.Class<T> type) Get a required annotation array attribute value from the annotation.
boolean	getBoolean(java.lang.String attributeName) Get a required boolean attribute value from the annotation.
boolean[]	getBooleanArray(java.lang.String attributeName) Get a required boolean array attribute value from the annotation.
byte	getByte(java.lang.String attributeName) Get a required byte attribute value from the annotation.
byte[]	getByteArray(java.lang.String attributeName) Get a required byte array attribute value from the annotation.
char	getChar(java.lang.String attributeName) Get a required char attribute value from the annotation.
char[]	getCharArray(java.lang.String attributeName) Get a required char array attribute value from the annotation.
java.lang.Class<?>	getClass(java.lang.String attributeName) Get a required class attribute value from the annotation.
java.lang.Class<?>[]	getClassArray(java.lang.String attributeName) Get a required class array attribute value from the annotation.
java.util.Optional<java.lang.Object>	getDefaultValue(java.lang.String attributeName) Get the default attribute value from the annotation as specified in the annotation declaration.
<T> java.util.Optional<T>	getDefaultValue(java.lang.String attributeName, java.lang.Class<T> type) Get the default attribute value from the annotation as specified in the annotation declaration.
int	getDepth() Get the depth of this annotation related to its use as a meta-annotation.
double	getDouble(java.lang.String attributeName) Get a required double attribute value from the annotation.
double[]	getDoubleArray(java.lang.String attributeName) Get a required double array attribute value from the annotation.
<E extends java.lang.Enum<E>> E	getEnum(java.lang.String attributeName, java.lang.Class<E> type) Get a required enum attribute value from the annotation.
<E extends java.lang.Enum<E>> E[]	getEnumArray(java.lang.String attributeName, java.lang.Class<E> type) Get a required enum array attribute value from the annotation.
float	getFloat(java.lang.String attributeName) Get a required float attribute value from the annotation.
float[]	getFloatArray(java.lang.String attributeName) Get a required float array attribute value from the annotation.
int	getInt(java.lang.String attributeName) Get a required int attribute value from the annotation.
int[]	getIntArray(java.lang.String attributeName) Get a required int array attribute value from the annotation.
long	getLong(java.lang.String attributeName) Get a required long attribute value from the annotation.
long[]	getLongArray(java.lang.String attributeName) Get a required long array attribute value from the annotation.
MergedAnnotation<?>	getParent() Get the parent of the meta-annotation, or null if the annotation is not meta-present.
short	getShort(java.lang.String attributeName) Get a required short attribute value from the annotation.
short[]	getShortArray(java.lang.String attributeName) Get a required short array attribute value from the annotation.
java.lang.Object	getSource() Get the source that ultimately declared the annotation, or null if the source is not known.
java.lang.String	getString(java.lang.String attributeName) Get a required string attribute value from the annotation.
java.lang.String[]	getStringArray(java.lang.String attributeName) Get a required string array attribute value from the annotation.
java.lang.Class<A>	getType() Get the Class reference for the actual annotation type.
java.util.Optional<java.lang.Object>	getValue(java.lang.String attributeName) Get an optional attribute value from the annotation.
<T> java.util.Optional<T>	getValue(java.lang.String attributeName, java.lang.Class<T> type) Get an optional attribute value from the annotation.
boolean	hasDefaultValue(java.lang.String attributeName) Determine if the specified attribute name has a default value when compared to the annotation declaration.
boolean	hasNonDefaultValue(java.lang.String attributeName) Determine if the specified attribute name has a non-default value when compared to the annotation declaration.
boolean	isDirectlyPresent() Determine if the annotation is directly present on the source.
boolean	isMetaPresent() Determine if the annotation is meta-present on the source.
boolean	isPresent() Determine if the annotation is present on the source.
static <A extends java.lang.annotation.Annotation> MergedAnnotation<A>	missing() Create a MergedAnnotation that represents a missing annotation (i.e.
A	synthesize() Create a type-safe synthesized version of this annotation that can be used directly in code.
java.util.Optional<A>	synthesize(java.util.function.Predicate<? super MergedAnnotation<A>> condition) Optionally create a type-safe synthesized version of this annotation based on a condition predicate.
MergedAnnotation<A>	withNonMergedAttributes() Create a new view of the annotation that exposes non-merged attribute values.

Field Detail

VALUE

static final java.lang.String VALUE

The attribute name for annotations with a single element.

See Also:

Constant Field Values

Method Detail

getType

java.lang.Class<A> getType()

Get the Class reference for the actual annotation type.

Returns:

the annotation type

isPresent

boolean isPresent()

Determine if the annotation is present on the source. Considers directly present and meta-present annotations within the context of the MergedAnnotations.SearchStrategy used.

Returns:

true if the annotation is present

isDirectlyPresent

boolean isDirectlyPresent()

Determine if the annotation is directly present on the source. A directly present annotation is one that the user has explicitly declared and not one that is meta-present or @Inherited.

Returns:

true if the annotation is directly present

isMetaPresent

boolean isMetaPresent()

Determine if the annotation is meta-present on the source. A meta-present annotation is an annotation that the user hasn't explicitly declared, but has been used as a meta-annotation somewhere in the annotation hierarchy.

Returns:

true if the annotation is meta-present

getDepth

int getDepth()

Get the depth of this annotation related to its use as a meta-annotation. A directly declared annotation has a depth of 0, a meta-annotation has a depth of 1, a meta-annotation on a meta-annotation has a depth of 2, etc. A missing annotation will always return a depth of -1.

Returns:

the annotation depth or -1 if the annotation is missing

getAggregateIndex

int getAggregateIndex()

Get the index of the aggregate collection containing this annotation. Can be used to reorder a stream of annotations, for example, to give a higher priority to annotations declared on a superclass or interface. A missing annotation will always return an aggregate index of -1.

Returns:

the aggregate index (starting at 0) or -1 if the annotation is missing

getSource

@Nullable
java.lang.Object getSource()

Get the source that ultimately declared the annotation, or null if the source is not known. If this merged annotation was created from an AnnotatedElement then this source will be an element of the same type. If the annotation was loaded without using reflection, the source can be of any type, but should have a sensible toString(). Meta-annotations will return the same source as the getParent().

Returns:

the source, or null

getParent

@Nullable
MergedAnnotation<?> getParent()

Get the parent of the meta-annotation, or null if the annotation is not meta-present.

Returns:

the parent annotation or null

hasNonDefaultValue

boolean hasNonDefaultValue(java.lang.String attributeName)

Determine if the specified attribute name has a non-default value when compared to the annotation declaration.

Parameters:

attributeName - the attribute name

Returns:

true if the attribute value is different from the default value

hasDefaultValue

boolean hasDefaultValue(java.lang.String attributeName)
                 throws java.util.NoSuchElementException

Determine if the specified attribute name has a default value when compared to the annotation declaration.

Parameters:

attributeName - the attribute name

Returns:

true if the attribute value is the same as the default value

Throws:

java.util.NoSuchElementException

getByte

byte getByte(java.lang.String attributeName)
      throws java.util.NoSuchElementException

Get a required byte attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a byte

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getByteArray

byte[] getByteArray(java.lang.String attributeName)
             throws java.util.NoSuchElementException

Get a required byte array attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a byte array

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getBoolean

boolean getBoolean(java.lang.String attributeName)
            throws java.util.NoSuchElementException

Get a required boolean attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a boolean

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getBooleanArray

boolean[] getBooleanArray(java.lang.String attributeName)
                   throws java.util.NoSuchElementException

Get a required boolean array attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a boolean array

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getChar

char getChar(java.lang.String attributeName)
      throws java.util.NoSuchElementException

Get a required char attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a char

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getCharArray

char[] getCharArray(java.lang.String attributeName)
             throws java.util.NoSuchElementException

Get a required char array attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a char array

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getShort

short getShort(java.lang.String attributeName)
        throws java.util.NoSuchElementException

Get a required short attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a short

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getShortArray

short[] getShortArray(java.lang.String attributeName)
               throws java.util.NoSuchElementException

Get a required short array attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a short array

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getInt

int getInt(java.lang.String attributeName)
    throws java.util.NoSuchElementException

Get a required int attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as an int

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getIntArray

int[] getIntArray(java.lang.String attributeName)
           throws java.util.NoSuchElementException

Get a required int array attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as an int array

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getLong

long getLong(java.lang.String attributeName)
      throws java.util.NoSuchElementException

Get a required long attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a long

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getLongArray

long[] getLongArray(java.lang.String attributeName)
             throws java.util.NoSuchElementException

Get a required long array attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a long array

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getDouble

double getDouble(java.lang.String attributeName)
          throws java.util.NoSuchElementException

Get a required double attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a double

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getDoubleArray

double[] getDoubleArray(java.lang.String attributeName)
                 throws java.util.NoSuchElementException

Get a required double array attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a double array

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getFloat

float getFloat(java.lang.String attributeName)
        throws java.util.NoSuchElementException

Get a required float attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a float

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getFloatArray

float[] getFloatArray(java.lang.String attributeName)
               throws java.util.NoSuchElementException

Get a required float array attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a float array

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getString

java.lang.String getString(java.lang.String attributeName)
                    throws java.util.NoSuchElementException

Get a required string attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a string

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getStringArray

java.lang.String[] getStringArray(java.lang.String attributeName)
                           throws java.util.NoSuchElementException

Get a required string array attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a string array

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getClass

java.lang.Class<?> getClass(java.lang.String attributeName)
                     throws java.util.NoSuchElementException

Get a required class attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a class

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getClassArray

java.lang.Class<?>[] getClassArray(java.lang.String attributeName)
                            throws java.util.NoSuchElementException

Get a required class array attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

the value as a class array

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getEnum

<E extends java.lang.Enum<E>> E getEnum(java.lang.String attributeName,
                                        java.lang.Class<E> type)
                                 throws java.util.NoSuchElementException

Get a required enum attribute value from the annotation.

Parameters:

attributeName - the attribute name

type - the enum type

Returns:

the value as a enum

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getEnumArray

<E extends java.lang.Enum<E>> E[] getEnumArray(java.lang.String attributeName,
                                               java.lang.Class<E> type)
                                        throws java.util.NoSuchElementException

Get a required enum array attribute value from the annotation.

Parameters:

attributeName - the attribute name

type - the enum type

Returns:

the value as a enum array

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getAnnotation

<T extends java.lang.annotation.Annotation> MergedAnnotation<T> getAnnotation(java.lang.String attributeName,
                                                                              java.lang.Class<T> type)
                                                                       throws java.util.NoSuchElementException

Get a required annotation attribute value from the annotation.

Parameters:

attributeName - the attribute name

type - the annotation type

Returns:

the value as a MergedAnnotation

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getAnnotationArray

<T extends java.lang.annotation.Annotation> MergedAnnotation<T>[] getAnnotationArray(java.lang.String attributeName,
                                                                                     java.lang.Class<T> type)
                                                                              throws java.util.NoSuchElementException

Get a required annotation array attribute value from the annotation.

Parameters:

attributeName - the attribute name

type - the annotation type

Returns:

the value as a MergedAnnotation array

Throws:

java.util.NoSuchElementException - if there is no matching attribute

getValue

java.util.Optional<java.lang.Object> getValue(java.lang.String attributeName)

Get an optional attribute value from the annotation.

Parameters:

attributeName - the attribute name

Returns:

an optional value or Optional.empty() if there is no matching attribute

getValue

<T> java.util.Optional<T> getValue(java.lang.String attributeName,
                                   java.lang.Class<T> type)

Get an optional attribute value from the annotation.

Parameters:

attributeName - the attribute name

type - the attribute type. Must be compatible with the underlying attribute type or Object.class.

Returns:

an optional value or Optional.empty() if there is no matching attribute

getDefaultValue

java.util.Optional<java.lang.Object> getDefaultValue(java.lang.String attributeName)

Get the default attribute value from the annotation as specified in the annotation declaration.

Parameters:

attributeName - the attribute name

Returns:

an optional of the default value or Optional.empty() if there is no matching attribute or no defined default

getDefaultValue

<T> java.util.Optional<T> getDefaultValue(java.lang.String attributeName,
                                          java.lang.Class<T> type)

Get the default attribute value from the annotation as specified in the annotation declaration.

Parameters:

attributeName - the attribute name

type - the attribute type. Must be compatible with the underlying attribute type or Object.class.

Returns:

an optional of the default value or Optional.empty() if there is no matching attribute or no defined default

filterDefaultValues

MergedAnnotation<A> filterDefaultValues()

Create a new view of the annotation with all attributes that have default values removed.

Returns:

a filtered view of the annotation without any attributes that have a default value

See Also:

filterAttributes(Predicate)

filterAttributes

MergedAnnotation<A> filterAttributes(java.util.function.Predicate<java.lang.String> predicate)

Create a new view of the annotation with only attributes that match the given predicate.

Parameters:

predicate - a predicate used to filter attribute names

Returns:

a filtered view of the annotation

See Also:

filterDefaultValues(), MergedAnnotationPredicates

withNonMergedAttributes

MergedAnnotation<A> withNonMergedAttributes()

Create a new view of the annotation that exposes non-merged attribute values.

Methods from this view will return attribute values with only alias mirroring rules applied. Aliases to parent attributes will not be applied.

Returns:

a non-merged view of the annotation

asAnnotationAttributes

AnnotationAttributes asAnnotationAttributes(MergedAnnotation.Adapt... adaptations)

Create a new mutable AnnotationAttributes instance from this merged annotation.

The adaptations may be used to change the way that values are added.

Parameters:

adaptations - adaptations that should be applied to the annotation values

Returns:

an immutable map containing the attributes and values

asMap

java.util.Map<java.lang.String,java.lang.Object> asMap(MergedAnnotation.Adapt... adaptations)

Return an immutable Map that contains all the annotation attributes.

The adaptations may be used to change the way that values are added.

Parameters:

adaptations - adaptations that should be applied to the annotation values

Returns:

an immutable map containing the attributes and values

asMap

<T extends java.util.Map<java.lang.String,java.lang.Object>> T asMap(java.util.function.Function<MergedAnnotation<?>,T> factory,
                                                                     MergedAnnotation.Adapt... adaptations)

Create a new Map instance of the given type that contains all the annotation attributes.

The adaptations may be used to change the way that values are added.

Parameters:

factory - a map factory

adaptations - adaptations that should be applied to the annotation values

Returns:

a map containing the attributes and values

synthesize

A synthesize()
      throws java.util.NoSuchElementException

Create a type-safe synthesized version of this annotation that can be used directly in code.

The result is synthesized using a JDK Proxy and as a result may incur a computational cost when first invoked.

Returns:

a synthesized version of the annotation.

Throws:

java.util.NoSuchElementException - on a missing annotation

synthesize

java.util.Optional<A> synthesize(java.util.function.Predicate<? super MergedAnnotation<A>> condition)
                          throws java.util.NoSuchElementException

Optionally create a type-safe synthesized version of this annotation based on a condition predicate.

The result is synthesized using a JDK Proxy and as a result may incur a computational cost when first invoked.

Parameters:

condition - the test to determine if the annotation can be synthesized

Returns:

a optional containing the synthesized version of the annotation or an empty optional if the condition doesn't match

Throws:

java.util.NoSuchElementException - on a missing annotation

See Also:

MergedAnnotationPredicates

missing

static <A extends java.lang.annotation.Annotation> MergedAnnotation<A> missing()

Create a MergedAnnotation that represents a missing annotation (i.e. one that is not present).

Returns:

an instance representing a missing annotation

from

static <A extends java.lang.annotation.Annotation> MergedAnnotation<A> from(A annotation)

Create a new MergedAnnotation instance from the specified annotation.

Parameters:

annotation - the annotation to include

Returns:

a MergedAnnotation instance containing the annotation

from

static <A extends java.lang.annotation.Annotation> MergedAnnotation<A> from(@Nullable
                                                                            java.lang.Object source,
                                                                            A annotation)

Create a new MergedAnnotation instance from the specified annotation.

Parameters:

source - the source for the annotation. 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.

annotation - the annotation to include

Returns:

a MergedAnnotation instance for the annotation

from

static <A extends java.lang.annotation.Annotation> MergedAnnotation<A> from(java.lang.Class<A> annotationType)

Create a new MergedAnnotation instance from the specified annotation type. The resulting annotation will not have any attribute values but may still be used to query default values.

Parameters:

annotationType - the annotation type

Returns:

a MergedAnnotation instance for the annotation

from

static <A extends java.lang.annotation.Annotation> MergedAnnotation<A> from(java.lang.Class<A> annotationType,
                                                                            @Nullable
                                                                            java.util.Map<java.lang.String,?> attributes)

Create a new MergedAnnotation instance from the specified annotation type and attributes map.

Parameters:

annotationType - the annotation type

attributes - the annotation attributes or null if just default values should be used

Returns:

a MergedAnnotation instance for the annotation and attributes

See Also:

from(AnnotatedElement, Class, Map)

from

static <A extends java.lang.annotation.Annotation> MergedAnnotation<A> from(@Nullable
                                                                            java.lang.reflect.AnnotatedElement source,
                                                                            java.lang.Class<A> annotationType,
                                                                            @Nullable
                                                                            java.util.Map<java.lang.String,?> attributes)

Create a new MergedAnnotation instance from the specified annotation type and attributes map.

Parameters:

source - the source for the annotation. 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.

annotationType - the annotation type

attributes - the annotation attributes or null if just default values should be used

Returns:

a MergedAnnotation instance for the annotation and attributes