AnnotationElement (Java SE 12 & JDK 12 )
Keywords: jdk.jfr.AnnotationElement class

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
    --- | --- | ---
    `<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 Detail

    - #### 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 Detail

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