Module jdk.jfr
Package jdk.jfr

# Class AnnotationElement

java.lang.Object
jdk.jfr.AnnotationElement

public final class AnnotationElement extends Object
Describes event metadata, such as labels, descriptions and units.

The following example shows how `AnnotationElement` can be used to dynamically define events.

       List<AnnotationElement> typeAnnotations = new ArrayList<>();
       typeAnnotations.add(new AnnotationElement(Name.class, "com.example.HelloWorld"));
       typeAnnotations.add(new AnnotationElement(Label.class, "Hello World"));
       typeAnnotations.add(new AnnotationElement(Description.class, "Helps programmer getting started"));

       List<AnnotationElement> fieldAnnotations = new ArrayList<>();
       fieldAnnotations.add(new AnnotationElement(Label.class, "Message"));

       List<ValueDescriptor> fields = new ArrayList<>();
       fields.add(new ValueDescriptor(String.class, "message", fieldAnnotations));

       EventFactory f = EventFactory.create(typeAnnotations, fields);
       Event event = f.newEvent();
       event.commit();

Since:
  9

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AnnotationElement(Class<? extends Annotation> annotationType)`
  Creates an annotation element to use for dynamically defined events.
  `AnnotationElement(Class<? extends Annotation> annotationType, Object value)`
  Creates an annotation element to use for dynamically defined events.
  `AnnotationElement(Class<? extends Annotation> annotationType, Map<String,Object> values)`
  Creates an annotation element to use for dynamically defined events.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final <A> A`
  `getAnnotation(Class<? extends Annotation> annotationType)`
  Returns the first annotation for the specified type if an `AnnotationElement` with the same name exists, else `null`.
  `List<AnnotationElement>`
  `getAnnotationElements()`
  Returns an immutable list of annotation elements for this `AnnotationElement`.
  `long`
  `getTypeId()`
  Returns the type ID for this `AnnotationElement`.
  `String`
  `getTypeName()`
  Returns the fully qualified name of the annotation type that corresponds to this `AnnotationElement` (for example, `"jdk.jfr.Label"`).
  `Object`
  `getValue(String name)`
  Returns a value for this `AnnotationElement`.
  `List<ValueDescriptor>`
  `getValueDescriptors()`
  Returns an immutable list of descriptors that describes the annotation values for this `AnnotationElement`.
  `List<Object>`
  `getValues()`
  Returns an immutable list of annotation values in an order that matches the value descriptors for this `AnnotationElement`.
  `boolean`
  `hasValue(String name)`
  Returns `true` if an annotation value with the specified name exists in this `AnnotationElement`.

  ### Methods declared in class java.lang.Object

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

- ## Constructor Details

  - ### AnnotationElement

    public AnnotationElement(Class<? extends Annotation> annotationType, Map<String,Object> values)
    Creates an annotation element to use for dynamically defined events.

    Supported value types are `byte`, `int`, `short`, `long`, `double`, `float`, `boolean`, `char`, and `String`. Enums, arrays and classes, are not supported.

    If `annotationType` has annotations (directly present, indirectly present, or associated), then those annotation are recursively included. However, both the `annotationType` and any annotation found recursively must have the `MetadataDefinition` annotation.

    To statically define events, see `Event` class.

    Parameters:
      `annotationType` - interface extending `java.lang.annotation.Annotation`, not `null`
      `values` - a `Map` with keys that match method names of the specified annotation interface
    Throws:
      `IllegalArgumentException` - if value/key is `null`, an unsupported value type is used, or a value/key is used that doesn't match the signatures in the `annotationType`

  - ### AnnotationElement

    public AnnotationElement(Class<? extends Annotation> annotationType, Object value)
    Creates an annotation element to use for dynamically defined events.

    Supported value types are `byte`, `int`, `short`, `long`, `double`, `float`, `boolean`, `char`, and `String`. Enums, arrays, and classes are not supported.

    If `annotationType` has annotations (directly present, indirectly present, or associated), then those annotations are recursively included. However, both `annotationType` and any annotation found recursively must have the `MetadataDefinition` annotation.

    To statically define events, see `Event` class.

    Parameters:
      `annotationType` - interface extending `java.lang.annotation.Annotation,` not `null`
      `value` - the value that matches the `value` method of the specified `annotationType`
    Throws:
      `IllegalArgumentException` - if value/key is `null`, an unsupported value type is used, or a value/key is used that doesn't match the signatures in the `annotationType`

  - ### AnnotationElement

    public AnnotationElement(Class<? extends Annotation> annotationType)
    Creates an annotation element to use for dynamically defined events.

    Supported value types are `byte`, `short`, `int`, `long`, `double`, `float`, `boolean`, `char`, and `String`. Enums, arrays, and classes are not supported.

    If `annotationType` has annotations (directly present, indirectly present or associated), then those annotation are recursively included. However, both `annotationType` and any annotation found recursively must have the `MetadataDefinition` annotation.

    To statically define events, see `Event` class.

    Parameters:
      `annotationType` - interface extending java.lang.annotation.Annotation, not `null`

- ## Method Details

  - ### getValues

    public List<Object> getValues()
    Returns an immutable list of annotation values in an order that matches the value descriptors for this `AnnotationElement`.
    Returns:
      list of values, not `null`

  - ### getValueDescriptors

    public List<ValueDescriptor> getValueDescriptors()
    Returns an immutable list of descriptors that describes the annotation values for this `AnnotationElement`.
    Returns:
      the list of value descriptors for this `Annotation`, not `null`

  - ### getAnnotationElements

    public List<AnnotationElement> getAnnotationElements()
    Returns an immutable list of annotation elements for this `AnnotationElement`.
    Returns:
      a list of meta annotation, not `null`

  - ### getTypeName

    public String getTypeName()
    Returns the fully qualified name of the annotation type that corresponds to this `AnnotationElement` (for example, `"jdk.jfr.Label"`).
    Returns:
      type name, not `null`

  - ### getValue

    public Object getValue(String name)
    Returns a value for this `AnnotationElement`.
    Parameters:
      `name` - the name of the method in the annotation interface, not `null`.
    Returns:
      the annotation value, not `null`.
    Throws:
      `IllegalArgumentException` - if a method with the specified name does not exist in the annotation

  - ### hasValue

    public boolean hasValue(String name)
    Returns `true` if an annotation value with the specified name exists in this `AnnotationElement`.
    Parameters:
      `name` - name of the method in the annotation interface to find, not `null`
    Returns:
      `true` if method exists, `false` otherwise

  - ### getAnnotation

    public final <A> A getAnnotation(Class<? extends Annotation> annotationType)
    Returns the first annotation for the specified type if an `AnnotationElement` with the same name exists, else `null`.
    Type Parameters:
      `A` - the type of the annotation to query for and return if it exists
    Parameters:
      `annotationType` - the `Class object` corresponding to the annotation type, not `null`
    Returns:
      this element's annotation for the specified annotation type if it exists, else `null`

  - ### getTypeId

    public long getTypeId()
    Returns the type ID for this `AnnotationElement`.

    The ID is a unique identifier for the type in the Java Virtual Machine (JVM). The ID might not be the same between JVM instances.

    Returns:
      the type ID, not negative