Package org.jboss.jandex

Class AnnotationInstance

java.lang.Object

org.jboss.jandex.AnnotationInstance

public final class AnnotationInstance
extends java.lang.Object

An annotation instance represents a specific usage of an annotation on a target. It contains a set of members, as well as a reference to the target itself (e.g. class, field, method, etc).

Thread-Safety

This class is immutable and can be shared between threads without safe publication.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) static class	AnnotationInstance.NameComparator

Field Summary

Fields

Modifier and Type	Field	Description
(package private) static AnnotationInstance[]	EMPTY_ARRAY
private DotName	name
(package private) static AnnotationInstance.NameComparator	NAME_COMPARATOR
private boolean	runtimeVisible
private AnnotationTarget	target
private AnnotationValue[]	values

Constructor Summary

Constructors

Modifier	Constructor	Description
private	AnnotationInstance(DotName name, AnnotationTarget target, AnnotationValue[] values, boolean runtimeVisible)

Method Summary

Modifier and Type	Method	Description
(package private) static AnnotationInstance	binarySearch(AnnotationInstance[] annotations, DotName name)
static AnnotationInstanceBuilder	builder(java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)	Creates a builder of annotation instances of given annotationType.
static AnnotationInstanceBuilder	builder(ClassInfo annotationType)	Creates a builder of annotation instances of given annotationType.
static AnnotationInstanceBuilder	builder(DotName annotationType)	Creates a builder of annotation instances of given annotationType.
static AnnotationInstanceBuilder	builder(DotName annotationType, boolean runtimeVisible)	Creates a builder of annotation instances of given annotationType.
(package private) static AnnotationInstance	create(AnnotationInstance instance, AnnotationTarget target)
static AnnotationInstance	create(DotName name, boolean visible, AnnotationTarget target, java.util.List<AnnotationValue> values)	Construct a new mock annotation instance.
static AnnotationInstance	create(DotName name, boolean visible, AnnotationTarget target, AnnotationValue[] values)	Construct a new mock annotation instance.
static AnnotationInstance	create(DotName name, AnnotationTarget target, java.util.List<AnnotationValue> values)	Construct a new mock annotation instance.
static AnnotationInstance	create(DotName name, AnnotationTarget target, AnnotationValue[] values)	Construct a new mock annotation instance.
AnnotationInstanceEquivalenceProxy	createEquivalenceProxy()	Returns an equivalence proxy for this annotation instance.
boolean	equals(java.lang.Object o)	Returns whether this annotation instance is equal to another instance.
int	equivalenceHashCode()	Returns an equivalence hash code.
boolean	equivalentTo(AnnotationInstance other)	Returns whether this annotation instance is equivalent to the other annotation instance.
int	hashCode()	Returns a hash code representing this object.
DotName	name()	The name of this annotation in DotName form.
boolean	runtimeVisible()	Returns true if this annotation uses RetentionPolicy.RUNTIME and is visible to runtime reflection.
AnnotationTarget	target()	The program element that this annotation was declared on.
java.lang.String	toString()	Returns a string representation for this annotation instance.
java.lang.String	toString(boolean simple)	Returns an optionally simplified string that represents this annotation instance.
AnnotationValue	value()	Returns the member that has the special default name value.
AnnotationValue	value(java.lang.String name)	Returns the member of this annotation that has the specified name.
(package private) AnnotationValue[]	valueArray()
java.util.List<AnnotationValue>	values()	Returns an immutable list of all members of this annotation instance.
java.util.List<AnnotationValue>	valuesWithDefaults(IndexView index)	Returns a list of all members of this annotation instance, including default values if defined.
AnnotationValue	valueWithDefault(IndexView index)	Returns the member of this annotation that has special name value, accounting for its default value.
AnnotationValue	valueWithDefault(IndexView index, java.lang.String name)	Returns the member of this annotation that has the specified name, accounting for its default value.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NAME_COMPARATOR

static final AnnotationInstance.NameComparator NAME_COMPARATOR

EMPTY_ARRAY

static final AnnotationInstance[] EMPTY_ARRAY

name

private final DotName name

target

private final AnnotationTarget target

values

private final AnnotationValue[] values

runtimeVisible

private final boolean runtimeVisible

Constructor Detail

AnnotationInstance

private AnnotationInstance(DotName name,
                           AnnotationTarget target,
                           AnnotationValue[] values,
                           boolean runtimeVisible)

Method Detail

create

static AnnotationInstance create(AnnotationInstance instance,
                                 AnnotationTarget target)

builder

public static AnnotationInstanceBuilder builder(java.lang.Class<? extends java.lang.annotation.Annotation> annotationType)

Creates a builder of annotation instances of given annotationType. This allows creating an AnnotationInstance in a nicer way than using any of the create() methods.

Parameters:

annotationType - the type of annotation whose instance will be created, must not be null

Returns:

a builder instance, never null

builder

public static AnnotationInstanceBuilder builder(ClassInfo annotationType)

Creates a builder of annotation instances of given annotationType. This allows creating an AnnotationInstance in a nicer way than using any of the create() methods.

Parameters:

annotationType - the type of annotation whose instance will be created, must not be null

Returns:

a builder instance, never null

builder

public static AnnotationInstanceBuilder builder(DotName annotationType)

Creates a builder of annotation instances of given annotationType. This allows creating an AnnotationInstance in a nicer way than using any of the create() methods.

The given annotationType is assumed to have the runtime retention.

Parameters:

annotationType - the type of annotation whose instance will be created, must not be null

Returns:

a builder instance, never null

builder

public static AnnotationInstanceBuilder builder(DotName annotationType,
                                                boolean runtimeVisible)

Creates a builder of annotation instances of given annotationType. This allows creating an AnnotationInstance in a nicer way than using any of the create() methods.

Parameters:

annotationType - the type of annotation whose instance will be created, must not be null

runtimeVisible - whether the annotation type has the runtime retention

Returns:

a builder instance, never null

create

public static AnnotationInstance create(DotName name,
                                        AnnotationTarget target,
                                        AnnotationValue[] values)

Construct a new mock annotation instance. The passed values array will be defensively copied. It is assumed that the annotation is runtimeVisible().

Parameters:

name - the name of the annotation instance

target - the thing the annotation is declared on

values - the members of this annotation instance

Returns:

the new mock Annotation Instance

create

public static AnnotationInstance create(DotName name,
                                        boolean visible,
                                        AnnotationTarget target,
                                        AnnotationValue[] values)

Construct a new mock annotation instance. The passed values array will be defensively copied.

Parameters:

name - the name of the annotation instance

visible - whether the annotation is visible at runtime via the reflection API

target - the thing the annotation is declared on

values - the members of this annotation instance

Returns:

the new mock Annotation Instance

create

public static AnnotationInstance create(DotName name,
                                        AnnotationTarget target,
                                        java.util.List<AnnotationValue> values)

Construct a new mock annotation instance. The passed values list will be defensively copied. It is assumed that the annotation is runtimeVisible().

Parameters:

name - the name of the annotation instance

target - the thing the annotation is declared on

values - the members of this annotation instance

Returns:

the new mock Annotation Instance

create

public static AnnotationInstance create(DotName name,
                                        boolean visible,
                                        AnnotationTarget target,
                                        java.util.List<AnnotationValue> values)

Construct a new mock annotation instance. The passed values list will be defensively copied.

Parameters:

name - the name of the annotation instance

visible - whether the annotation is visible at runtime via the reflection API

target - the thing the annotation is declared on

values - the members of this annotation instance

Returns:

the new mock Annotation Instance

binarySearch

static AnnotationInstance binarySearch(AnnotationInstance[] annotations,
                                       DotName name)

name

public DotName name()

The name of this annotation in DotName form.

Returns:

the name of this annotation

target

public AnnotationTarget target()

The program element that this annotation was declared on. This can be a class, a field, a method, a method parameter, or a type in case of type annotations. In addition, it may be null if this instance is a nested annotation, in which case there is no target.

Returns:

the target this annotation instance refers to

value

public AnnotationValue value(java.lang.String name)

Returns the member of this annotation that has the specified name. If the member was not specified by this instance, null is returned. Note that this also applies to a defaulted member, whose value is not recorded in the target class file.

Parameters:

name - the name of the annotation member

Returns:

the annotation member with specified name, or null

value

public AnnotationValue value()

Returns the member that has the special default name value.

Returns:

the value member

valueWithDefault

public AnnotationValue valueWithDefault(IndexView index,
                                        java.lang.String name)

Returns the member of this annotation that has the specified name, accounting for its default value. Since an annotation's defaults are only stored on the annotation's defining class, and not usages of the annotation, an index containing the annotation class must be provided as a parameter. If the index does not contain the defining annotation class, then an IllegalArgumentException will be thrown to prevent non-deterministic results.

If the member was not specified by this annotation instance, then the annotation's ClassInfo is checked for a default value. If there is a default, that value is returned. Otherwise null is returned.

Parameters:

index - the index containing the defining annotation class

name - the name of the annotation member

Returns:

the annotation member with specified name, or null

Throws:

java.lang.IllegalArgumentException - if index does not contain the defining annotation class

Since:

2.1

valueWithDefault

public AnnotationValue valueWithDefault(IndexView index)

Returns the member of this annotation that has special name value, accounting for its default value. Since an annotation's defaults are only stored on the annotation's defining class, and not usages of the annotation, an index containing the annotation class must be provided as a parameter. If the index does not contain the defining annotation class, then an IllegalArgumentException will be thrown to prevent non-deterministic results.

If the value member was not specified by this instance, then the annotation's ClassInfo is checked for a default value. If there is a default, that value is returned. Otherwise null is returned.

Parameters:

index - the index containing the defining annotation class

Returns:

the value annotation member, or null

Throws:

java.lang.IllegalArgumentException - if index does not contain the defining annotation class

Since:

2.1

valuesWithDefaults

public java.util.List<AnnotationValue> valuesWithDefaults(IndexView index)

Returns a list of all members of this annotation instance, including default values if defined. Since an annotation's defaults are only stored on the annotation's defining class, and not usages of the annotation, an index containing the annotation class must be provided as a parameter. If the index does not contain the defining annotation class, then an IllegalArgumentException will be thrown to prevent non-deterministic results.

The order of this list is undefined.

Returns:

immutable list of this annotation's members

Throws:

java.lang.IllegalArgumentException - if index does not contain the defining annotation class

Since:

2.1

values

public java.util.List<AnnotationValue> values()

Returns an immutable list of all members of this annotation instance. While random access is allowed, the ordering algorithm of the list should not be relied upon. Although it will be consistent for the life of this instance.

Returns:

immutable list of this annotation's members

valueArray

AnnotationValue[] valueArray()

runtimeVisible

public boolean runtimeVisible()

Returns true if this annotation uses RetentionPolicy.RUNTIME and is visible to runtime reflection.

Since:

3.0

toString

public java.lang.String toString(boolean simple)

Returns an optionally simplified string that represents this annotation instance. If simplified the output is smaller but missing information, such as the package qualifier.

Parameters:

simple - whether to provide a simpler string representation

Returns:

a string representation for this object

Since:

2.0

toString

public java.lang.String toString()

Returns a string representation for this annotation instance. This method is equivalent to calling toString(boolean) with a value of true.

Overrides:

toString in class java.lang.Object

Returns:

a simple string representation for this annotation instance

equals

public boolean equals(java.lang.Object o)

Returns whether this annotation instance is equal to another instance. Two annotation instances are equal if their names and values of their members are equal, and they share the exact same AnnotationTarget instance.

Overrides:

equals in class java.lang.Object

Parameters:

o - the annotation instance to compare to

Returns:

true if equal, false if not

See Also:

Object.equals(Object)

hashCode

public int hashCode()

Returns a hash code representing this object.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code of this object

See Also:

Object.hashCode()

equivalentTo

public boolean equivalentTo(AnnotationInstance other)

Returns whether this annotation instance is equivalent to the other annotation instance. Two annotation instances are equivalent if their names and members are equal. No attention is paid to the annotation target.

Parameters:

other - the annotation instance to compare to

Returns:

true if equivalent, false if not

See Also:

equals(Object)

equivalenceHashCode

public int equivalenceHashCode()

Returns an equivalence hash code. This is consistent with equivalentTo(AnnotationInstance), therefore no attention is paid to the annotation target.

Returns:

hash code consistent with annotation equivalence

createEquivalenceProxy

public AnnotationInstanceEquivalenceProxy createEquivalenceProxy()

Returns an equivalence proxy for this annotation instance.