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
All Methods Static Methods Instance Methods Concrete Methods 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 givenannotationType
.static AnnotationInstanceBuilder
builder(ClassInfo annotationType)
Creates a builder of annotation instances of givenannotationType
.static AnnotationInstanceBuilder
builder(DotName annotationType)
Creates a builder of annotation instances of givenannotationType
.static AnnotationInstanceBuilder
builder(DotName annotationType, boolean runtimeVisible)
Creates a builder of annotation instances of givenannotationType
.(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 theother
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 namevalue
.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 namevalue
, 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.
-
-
-
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 givenannotationType
. This allows creating anAnnotationInstance
in a nicer way than using any of thecreate()
methods.- Parameters:
annotationType
- the type of annotation whose instance will be created, must not benull
- Returns:
- a builder instance, never
null
-
builder
public static AnnotationInstanceBuilder builder(ClassInfo annotationType)
Creates a builder of annotation instances of givenannotationType
. This allows creating anAnnotationInstance
in a nicer way than using any of thecreate()
methods.- Parameters:
annotationType
- the type of annotation whose instance will be created, must not benull
- Returns:
- a builder instance, never
null
-
builder
public static AnnotationInstanceBuilder builder(DotName annotationType)
Creates a builder of annotation instances of givenannotationType
. This allows creating anAnnotationInstance
in a nicer way than using any of thecreate()
methods.The given
annotationType
is assumed to have the runtime retention.- Parameters:
annotationType
- the type of annotation whose instance will be created, must not benull
- Returns:
- a builder instance, never
null
-
builder
public static AnnotationInstanceBuilder builder(DotName annotationType, boolean runtimeVisible)
Creates a builder of annotation instances of givenannotationType
. This allows creating anAnnotationInstance
in a nicer way than using any of thecreate()
methods.- Parameters:
annotationType
- the type of annotation whose instance will be created, must not benull
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 passedvalues
array will be defensively copied. It is assumed that the annotation isruntimeVisible()
.- Parameters:
name
- the name of the annotation instancetarget
- the thing the annotation is declared onvalues
- 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 passedvalues
array will be defensively copied.- Parameters:
name
- the name of the annotation instancevisible
- whether the annotation is visible at runtime via the reflection APItarget
- the thing the annotation is declared onvalues
- 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 passedvalues
list will be defensively copied. It is assumed that the annotation isruntimeVisible()
.- Parameters:
name
- the name of the annotation instancetarget
- the thing the annotation is declared onvalues
- 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 passedvalues
list will be defensively copied.- Parameters:
name
- the name of the annotation instancevisible
- whether the annotation is visible at runtime via the reflection APItarget
- the thing the annotation is declared onvalues
- 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 benull
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 namevalue
.- 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 anIllegalArgumentException
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. Otherwisenull
is returned.- Parameters:
index
- the index containing the defining annotation classname
- 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 namevalue
, 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 anIllegalArgumentException
will be thrown to prevent non-deterministic results.If the
value
member was not specified by this instance, then the annotation'sClassInfo
is checked for a default value. If there is a default, that value is returned. Otherwisenull
is returned.- Parameters:
index
- the index containing the defining annotation class- Returns:
- the
value
annotation member, ornull
- 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 anIllegalArgumentException
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 callingtoString(boolean)
with a value oftrue
.- Overrides:
toString
in classjava.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 sameAnnotationTarget
instance.- Overrides:
equals
in classjava.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 classjava.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 theother
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 withequivalentTo(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.
-
-