Class AnnotationMirrors

java.lang.Object

org.microbean.construct.element.AnnotationMirrors

public final class AnnotationMirrors
extends Object

A utility class for working with annotations as represented by AnnotationMirrors, ExecutableElements, and AnnotationValues.

Author:

Laird Nelson

Method Summary

Modifier and Type	Method	Description
static final List<? extends AnnotationMirror>	allAnnotationMirrors(Element e)	Returns a determinate, non-null, immutable List of AnnotationMirrors present on the supplied Element.
static final SequencedMap<ExecutableElement, AnnotationValue>	allAnnotationValues(AnnotationMirror a)	For the supplied AnnotationMirror, returns an immutable, determinate Map of AnnotationValue instances indexed by its ExecutableElements to which they apply.
static final Object	get(Map<? extends ExecutableElement, ? extends AnnotationValue> values, CharSequence name)	A convenience method that returns a value for an annotation interface element named by the supplied CharSequence and found in the supplied Map, or null if no such value exists.
static final AnnotationMirror	get(AnnotatedConstruct ac, CharSequence name)	Returns the (determinate) AnnotationMirror directly present on the supplied AnnotatedConstruct whose annotation type's TypeElement bears the supplied fullyQualifiedName, or null if no such AnnotationMirror exists.
static final Object	get(AnnotationMirror am, CharSequence name)	A convenience method that returns a value for an annotation interface element named by the supplied CharSequence and logically owned by the supplied AnnotationMirror, or null if no such value exists.
static final boolean	inherited(AnnotationMirror a)	Returns true if and only if the supplied AnnotationMirror's annotation type is declared by an element that has been (meta-) annotated with Inherited.
static final boolean	inherited(TypeElement annotationInterface)	Returns true if and only if the supplied TypeElement represents an annotation interface and if it has been (meta-) annotated with Inherited.
static final RetentionPolicy	retentionPolicy(AnnotationMirror a)	Returns a RetentionPolicy for the supplied AnnotationMirror, or RetentionPolicy.CLASS if, for any reason, a retention policy cannot be found or computed.
static final RetentionPolicy	retentionPolicy(TypeElement annotationInterface)	Returns a RetentionPolicy for the supplied TypeElement representing an annotation interface, or RetentionPolicy.CLASS if, for any reason, a retention policy cannot be found or computed.
static final boolean	sameAnnotation(AnnotationMirror am0, AnnotationMirror am1)	Determines whether the two AnnotationMirrors represent the same (otherwise opaque) annotation.
static final boolean	sameAnnotation(AnnotationMirror am0, AnnotationMirror am1, Predicate<? super ExecutableElement> p)	Determines whether the two AnnotationMirrors represent the same (underlying, otherwise opaque) annotation.
static final Stream<AnnotationMirror>	streamBreadthFirst(Collection<? extends AnnotationMirror> ams)	Returns a non-null, sequential, Stream that traverses the supplied AnnotationMirrors, and their (meta-) annotations, in breadth-first order.
static final Stream<AnnotationMirror>	streamBreadthFirst(Collection<? extends AnnotationMirror> ams, Predicate<? super ExecutableElement> p)	Returns a non-null, sequential, Stream that traverses the supplied AnnotationMirrors, and their (meta-) annotations, in breadth-first order.
static final Stream<AnnotationMirror>	streamBreadthFirst(AnnotatedConstruct ac)	Returns a non-null, sequential, Stream that traverses the supplied AnnotatedConstruct's annotations, and their (meta-) annotations, in breadth-first order.
static final Stream<AnnotationMirror>	streamBreadthFirst(AnnotatedConstruct ac, Predicate<? super ExecutableElement> p)	Returns a non-null, sequential, Stream that traverses the supplied AnnotatedConstruct's annotations, and their (meta-) annotations, in breadth-first order.
static final Stream<AnnotationMirror>	streamDepthFirst(Collection<? extends AnnotationMirror> ams)	Returns a non-null, sequential Stream that traverses the supplied AnnotationMirrors, and their (meta-) annotations, in depth-first order.
static final Stream<AnnotationMirror>	streamDepthFirst(Collection<? extends AnnotationMirror> ams, Predicate<? super ExecutableElement> p)	Returns a non-null, sequential Stream that traverses the supplied AnnotationMirrors, and their (meta-) annotations, in depth-first order.
static final Stream<AnnotationMirror>	streamDepthFirst(AnnotatedConstruct ac)	Returns a non-null, sequential Stream that traverses the supplied AnnotatedConstruct's annotations, and their (meta-) annotations, in depth-first order.
static final Stream<AnnotationMirror>	streamDepthFirst(AnnotatedConstruct ac, Predicate<? super ExecutableElement> p)	Returns a non-null, sequential Stream that traverses the supplied AnnotatedConstruct's annotations, and their (meta-) annotations, in depth-first order.
static final Set<ElementType>	targetElementTypes(AnnotationMirror a)	Returns a non-null, determinate, immutable Set of ElementTypes describing restrictions concerning where the annotation interface represented by the supplied AnnotationMirror may be applied.
static final Set<ElementType>	targetElementTypes(TypeElement annotationInterface)	Returns a non-null, determinate, immutable Set of ElementTypes describing restrictions concerning where the supplied annotation interface may be applied.
static final boolean	validAnnotationInterfaceElement(ExecutableElement e)	Returns true if and only if the supplied ExecutableElement represents a valid annotation interface element as defined by the Java Language Specification.
static final boolean	validAnnotationInterfaceElementType(TypeMirror t)	Returns true if and only if the supplied TypeMirror is a valid type for an annotation interface element as defined by the Java Language Specification.

Methods inherited from class Object

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

Method Details

allAnnotationMirrors

public static final List<? extends AnnotationMirror> allAnnotationMirrors(Element e)

Returns a determinate, non-null, immutable List of AnnotationMirrors present on the supplied Element.

This method is a more capable, better-typed replacement of the Elements.getAllAnnotationMirrors(Element) method, and should be preferred.

Parameters:

e - an Element; must not be null

Returns:

a determinate, non-null, immutable List of AnnotationMirrors present on the supplied Element

Throws:

NullPointerException - if e is null

See Also:

• Elements.getAllAnnotationMirrors(Element)

allAnnotationValues

public static final SequencedMap<ExecutableElement, AnnotationValue> allAnnotationValues(AnnotationMirror a)

For the supplied AnnotationMirror, returns an immutable, determinate Map of AnnotationValue instances indexed by its ExecutableElements to which they apply.

Each ExecutableElement represents an annotation interface element and meets the requirements of such an element.

Each AnnotationValue represents the value of an annotation interface element and meets the requirements for annotation values.

This method is a more capable, better-typed replacement of the Elements.getElementValuesWithDefaults(AnnotationMirror) method, and should be preferred.

Parameters:

a - an AnnotationMirror; may be null in which case an empty, immutable, determinate Map will be returned

Returns:

an immutable, determinate Map of AnnotationValue instances indexed by ExecutableElements

See Also:

• Elements.getElementValuesWithDefaults(AnnotationMirror)

External Specifications

• Java Language Specification, section 9.6.1

get

public static final AnnotationMirror get(AnnotatedConstruct ac,
 CharSequence name)

Returns the (determinate) AnnotationMirror directly present on the supplied AnnotatedConstruct whose annotation type's TypeElement bears the supplied fullyQualifiedName, or null if no such AnnotationMirror exists.

Parameters:

ac - an AnnotatedConstruct; must not be null

name - a CharSequence; may be null in which case null will be returned

Returns:

an AnnotationMirror, or null

Throws:

NullPointerException - if ac is null

See Also:

• streamBreadthFirst(AnnotatedConstruct)
• streamDepthFirst(AnnotatedConstruct)
• AnnotationMirror.getAnnotationType()
• DeclaredType.asElement()
• TypeElement.getQualifiedName()
• Name.contentEquals(CharSequence)

get

public static final Object get(AnnotationMirror am,
 CharSequence name)

A convenience method that returns a value for an annotation interface element named by the supplied CharSequence and logically owned by the supplied AnnotationMirror, or null if no such value exists.

Parameters:

am - an AnnotationMirror; must not be null

name - a CharSequence; may be null in which case null will be returned

Returns:

the result of invoking getValue() on an AnnotationValue, or null

Throws:

NullPointerException - if am is null

See Also:

• AnnotationValue
• allAnnotationValues(AnnotationMirror)
• get(Map, CharSequence)

get

public static final Object get(Map<? extends ExecutableElement, ? extends AnnotationValue> values,
 CharSequence name)

A convenience method that returns a value for an annotation interface element named by the supplied CharSequence and found in the supplied Map, or null if no such value exists.

Parameters:

values - a Map as returned by the allAnnotationValues(AnnotationMirror) method; must not be null

name - a CharSequence; may be null in which case null will be returned

Returns:

the result of invoking getValue() on a suitable AnnotationValue found in the supplied Map, or null

Throws:

NullPointerException - if values is null

See Also:

• AnnotationValue
• allAnnotationValues(AnnotationMirror)

inherited

public static final boolean inherited(AnnotationMirror a)

Returns true if and only if the supplied AnnotationMirror's annotation type is declared by an element that has been (meta-) annotated with Inherited.

Parameters:

a - an AnnotationMirror; must not be null

Returns:

true if and only if the supplied AnnotationMirror's annotation type is declared by an element that has been (meta-) annotated with Inherited

Throws:

NullPointerException - if a is null

See Also:

• inherited(TypeElement)

inherited

public static final boolean inherited(TypeElement annotationInterface)

Returns true if and only if the supplied TypeElement represents an annotation interface and if it has been (meta-) annotated with Inherited.

Parameters:

annotationInterface - a TypeElement representing an annotation interface; must not be null

Returns:

true if and only if the supplied TypeElement represents an annotation interface and if it has been (meta-) annotated with Inherited

Throws:

NullPointerException - if annotationInterface is null

External Specifications

• Java Language Specification, section 9.6.4.3

retentionPolicy

public static final RetentionPolicy retentionPolicy(AnnotationMirror a)

Returns a RetentionPolicy for the supplied AnnotationMirror, or RetentionPolicy.CLASS if, for any reason, a retention policy cannot be found or computed.

Parameters:

a - an AnnotationMirror; must not be null

Returns:

the RetentionPolicy for the supplied AnnotationMirror; never null

Throws:

NullPointerException - if a is null

See Also:

• retentionPolicy(TypeElement)

retentionPolicy

public static final RetentionPolicy retentionPolicy(TypeElement annotationInterface)

Returns a RetentionPolicy for the supplied TypeElement representing an annotation interface, or RetentionPolicy.CLASS if, for any reason, a retention policy cannot be found or computed.

Parameters:

annotationInterface - a TypeElement; must be non-null and should represent an annotation interface

Returns:

the RetentionPolicy for the supplied TypeElement; never null

Throws:

NullPointerException - if annotationInterface is null

See Also:

• RetentionPolicy

External Specifications

• Java Language Specification, section 9.6.4.2

sameAnnotation

public static final boolean sameAnnotation(AnnotationMirror am0,
 AnnotationMirror am1)

Determines whether the two AnnotationMirrors represent the same (otherwise opaque) annotation.

Parameters:

am0 - an AnnotationMirror; may be null

am1 - an AnnotationMirror; may be null

Returns:

true if the supplied AnnotationMirrors represent the same (otherwise opaque) annotation; false otherwise

See Also:

• sameAnnotation(AnnotationMirror, AnnotationMirror)

sameAnnotation

public static final boolean sameAnnotation(AnnotationMirror am0,
 AnnotationMirror am1,
 Predicate<? super ExecutableElement> p)

Determines whether the two AnnotationMirrors represent the same (underlying, otherwise opaque) annotation.

Parameters:

am0 - an AnnotationMirror; may be null

am1 - an AnnotationMirror; may be null

p - a Predicate that returns true if a given ExecutableElement, representing an annotation interface element, is to be included in the computation; may be null in which case it is as if ()-> true were supplied instead

Returns:

true if the supplied AnnotationMirrors represent the same (underlying, otherwise opaque) annotation; false otherwise

See Also:

• SameAnnotationValueVisitor
• allAnnotationValues(AnnotationMirror)

streamBreadthFirst

public static final Stream<AnnotationMirror> streamBreadthFirst(AnnotatedConstruct ac)

Returns a non-null, sequential, Stream that traverses the supplied AnnotatedConstruct's annotations, and their (meta-) annotations, in breadth-first order.

Cycles are avoided via usage of the sameAnnotation(AnnotationMirror, AnnotationMirror) method.

Parameters:

ac - an AnnotatedConstruct; must not be null

Returns:

a non-null Stream of AnnotationMirrors

Throws:

NullPointerException - if ac is null

See Also:

• sameAnnotation(AnnotationMirror, AnnotationMirror)

streamBreadthFirst

public static final Stream<AnnotationMirror> streamBreadthFirst(AnnotatedConstruct ac,
 Predicate<? super ExecutableElement> p)

Returns a non-null, sequential, Stream that traverses the supplied AnnotatedConstruct's annotations, and their (meta-) annotations, in breadth-first order.

Cycles and duplicates are avoided via usage of the sameAnnotation(AnnotationMirror, AnnotationMirror, Predicate) method.

Parameters:

ac - an AnnotatedConstruct; must not be null

p - a Predicate that returns true if a given ExecutableElement, representing an annotation interface element, is to be included in comparison operations; may be null in which case it is as if ()-> true were supplied instead

Returns:

a non-null Stream of AnnotationMirrors

Throws:

NullPointerException - if ac is null

See Also:

• streamBreadthFirst(Collection, Predicate)
• sameAnnotation(AnnotationMirror, AnnotationMirror)

streamBreadthFirst

public static final Stream<AnnotationMirror> streamBreadthFirst(Collection<? extends AnnotationMirror> ams)

Returns a non-null, sequential, Stream that traverses the supplied AnnotationMirrors, and their (meta-) annotations, in breadth-first order.

Cycles and duplicates are avoided via usage of the sameAnnotation(AnnotationMirror, AnnotationMirror) method. Consequently the returned Stream yields only semantically distinct elements.

Parameters:

ams - a Collection of AnnotationMirrors; must not be null

Returns:

a non-null Stream of (distinct) AnnotationMirrors

Throws:

NullPointerException - if ams is null

See Also:

• sameAnnotation(AnnotationMirror, AnnotationMirror)

streamBreadthFirst

public static final Stream<AnnotationMirror> streamBreadthFirst(Collection<? extends AnnotationMirror> ams,
 Predicate<? super ExecutableElement> p)

Returns a non-null, sequential, Stream that traverses the supplied AnnotationMirrors, and their (meta-) annotations, in breadth-first order.

Cycles and duplicates are avoided via usage of the sameAnnotation(AnnotationMirror, AnnotationMirror, Predicate) method. Consequently the returned Stream yields only semantically distinct elements.

Parameters:

ams - a Collection of AnnotationMirrors; must not be null

p - a Predicate that returns true if a given ExecutableElement, representing an annotation element, is to be included in comparison operations; may be null in which case it is as if ()-> true were supplied instead

Returns:

a non-null Stream of (distinct) AnnotationMirrors

Throws:

NullPointerException - if ams is null

See Also:

• sameAnnotation(AnnotationMirror, AnnotationMirror, Predicate)

streamDepthFirst

public static final Stream<AnnotationMirror> streamDepthFirst(AnnotatedConstruct ac)

Returns a non-null, sequential Stream that traverses the supplied AnnotatedConstruct's annotations, and their (meta-) annotations, in depth-first order.

Cycles are avoided via usage of the sameAnnotation(AnnotationMirror, AnnotationMirror) method.

Parameters:

ac - an AnnotatedConstruct; must not be null

Returns:

a non-null Stream of AnnotationMirrors

Throws:

NullPointerException - if ac is null

See Also:

• streamDepthFirst(AnnotatedConstruct, Predicate)
• sameAnnotation(AnnotationMirror, AnnotationMirror)

streamDepthFirst

public static final Stream<AnnotationMirror> streamDepthFirst(AnnotatedConstruct ac,
 Predicate<? super ExecutableElement> p)

Returns a non-null, sequential Stream that traverses the supplied AnnotatedConstruct's annotations, and their (meta-) annotations, in depth-first order.

Cycles and duplicates are avoided via usage of the sameAnnotation(AnnotationMirror, AnnotationMirror, Predicate) method.

Parameters:

ac - an AnnotatedConstruct; must not be null

p - a Predicate that returns true if a given ExecutableElement, representing an annotation element, is to be included in comparison operations; may be null in which case it is as if ()-> true were supplied instead

Returns:

a non-null Stream of AnnotationMirrors

Throws:

NullPointerException - if ac is null

See Also:

• sameAnnotation(AnnotationMirror, AnnotationMirror)

streamDepthFirst

public static final Stream<AnnotationMirror> streamDepthFirst(Collection<? extends AnnotationMirror> ams)

Returns a non-null, sequential Stream that traverses the supplied AnnotationMirrors, and their (meta-) annotations, in depth-first order.

Cycles and duplicates are avoided via usage of the sameAnnotation(AnnotationMirror, AnnotationMirror) method.

Parameters:

ams - a non-null Collection of AnnotationMirrors

Returns:

a non-null Stream of AnnotationMirrors

Throws:

NullPointerException - if ams is null

See Also:

• streamDepthFirst(Collection, Predicate)
• sameAnnotation(AnnotationMirror, AnnotationMirror)

streamDepthFirst

public static final Stream<AnnotationMirror> streamDepthFirst(Collection<? extends AnnotationMirror> ams,
 Predicate<? super ExecutableElement> p)

Returns a non-null, sequential Stream that traverses the supplied AnnotationMirrors, and their (meta-) annotations, in depth-first order.

Cycles and duplicates are avoided via usage of the sameAnnotation(AnnotationMirror, AnnotationMirror, Predicate) method.

Parameters:

ams - a non-null Collection of AnnotationMirrors

p - a Predicate that returns true if a given ExecutableElement, representing an annotation element, is to be included in comparison operations; may be null in which case it is as if ()-> true were supplied instead

Returns:

a non-null Stream of AnnotationMirrors

Throws:

NullPointerException - if ams is null

See Also:

• sameAnnotation(AnnotationMirror, AnnotationMirror)

targetElementTypes

public static final Set<ElementType> targetElementTypes(AnnotationMirror a)

Returns a non-null, determinate, immutable Set of ElementTypes describing restrictions concerning where the annotation interface represented by the supplied AnnotationMirror may be applied.

Parameters:

a - an AnnotationMirror; must not be null

Returns:

a non-null, determinate, immutable Set of ElementTypes describing restrictions concerning where the annotation interface represented by the supplied AnnotationMirror may be applied

Throws:

NullPointerException - if a is null

targetElementTypes

public static final Set<ElementType> targetElementTypes(TypeElement annotationInterface)

Returns a non-null, determinate, immutable Set of ElementTypes describing restrictions concerning where the supplied annotation interface may be applied.

Parameters:

annotationInterface - a TypeElement representing an annotation interface; must not be null

Returns:

a non-null, determinate, immutable Set of ElementTypes describing restrictions concerning where the supplied annotation interface may be applied

Throws:

NullPointerException - if annotationInterface is null

See Also:

• ElementType
• Target

External Specifications

• Java Language Specification, section 9.6.4.1

validAnnotationInterfaceElement

public static final boolean validAnnotationInterfaceElement(ExecutableElement e)

Returns true if and only if the supplied ExecutableElement represents a valid annotation interface element as defined by the Java Language Specification.

Parameters:

e - an ExecutableElement; must not be null

Returns:

true if and only if the supplied ExecutableElement represents a valid annotation interface element as defined by the Java Language Specification

Throws:

NullPointerException - if e is null

External Specifications

• Java Language Specification, section 9.6.1

validAnnotationInterfaceElementType

public static final boolean validAnnotationInterfaceElementType(TypeMirror t)

Returns true if and only if the supplied TypeMirror is a valid type for an annotation interface element as defined by the Java Language Specification.

Parameters:

t - a TypeMirror; must not be null

Returns:

true if and only if the supplied TypeMirror is a valid type for an annotation interface element as defined by the Java Language Specification

Throws:

NullPointerException - if t is null

External Specifications

• Java Language Specification, section 9.6.1