Class 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.
    • Method Detail

      • 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
      • 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
      • 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