Package org.jboss.jandex

Class AnnotationInstance

java.lang.Object
org.jboss.jandex.AnnotationInstance
public final class AnnotationInstance extends Object
An annotation instance represents a specific usage of an annotation on a target. It contains a set of values, 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.
Author:
Jason T. Greene

  • Method Details

    • builder

      public static AnnotationInstanceBuilder builder(Class<? extends 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 values 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 values of this annotation instance
      Returns:
      the new mock Annotation Instance

    • create

      public static AnnotationInstance create(DotName name, AnnotationTarget target, 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 values of this annotation instance
      Returns:
      the new mock Annotation Instance

    • create

      public static AnnotationInstance create(DotName name, boolean visible, AnnotationTarget target, 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 values of this annotation instance
      Returns:
      the new mock Annotation Instance

    • name

      public DotName name()
      The name of this annotation in DotName form.
      Returns:
      the name of this annotation

    • target

      public AnnotationTarget target()
      The Java element that this annotation was declared on. This can be a class, a field, a method, or a method parameter. 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(String name)
      Returns a value that corresponds with the specified parameter name. If the parameter was not specified by this instance then null is returned. Note that this also applies to a defaulted parameter, which is not recorded in the target class.
      Parameters:
      name - the parameter name
      Returns:
      the value of the specified parameter, or null if not provided

    • value

      public AnnotationValue value()
      Returns the value that is associated with the special default "value" parameter.
      Returns:
      the "value" value

    • valueWithDefault

      public AnnotationValue valueWithDefault(IndexView index, String name)
      Returns a value that corresponds with the specified parameter 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 parameter 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
      name - the name of the annotation parameter
      Returns:
      the value of the specified parameter, the default, or null
      Throws:
      IllegalArgumentException - if index does not contain the defining annotation class
      Since:
      2.1

    • valueWithDefault

      public AnnotationValue valueWithDefault(IndexView index)
      Returns the value that is associated with the special default "value" parameter, also accounting for a value default. 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" parameter 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" value, or its default, or null
      Throws:
      IllegalArgumentException - if index does not contain the defining annotation class
      Since:
      2.1

    • valuesWithDefaults

      public List<AnnotationValue> valuesWithDefaults(IndexView index)
      Returns a list of all parameter values on this annotation instance, including default values id 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:
      the parameter values of this annotation
      Throws:
      IllegalArgumentException - if index does not contain the defining annotation class
      Since:
      2.1

    • values

      public List<AnnotationValue> values()
      Returns a list of all parameter values on 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:
      the parameter values of this annotation

    • runtimeVisible

      public boolean runtimeVisible()
      Returns true if this annotation uses RetentionPolicy.RUNTIME and is visible to runtime reflection.
      Since:
      3.0

    • toString

      public 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 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 Object
      Returns:
      a simple string representation for this annotation instance

    • equals

      public boolean equals(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. The latter restriction may be softened in future versions.
      Overrides:
      equals in class Object
      Parameters:
      o - the annotation instance to compare to.
      Returns:
      true if equal, false if not
      See Also:

    • hashCode

      public int hashCode()
      Returns a hash code representing this object.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code of this object
      See Also: