ValueDescriptor (Java SE 26 & JDK 26)
Description: declaration: module: jdk.jfr, package: jdk.jfr, class: ValueDescriptor
Keywords: jdk.jfr.ValueDescriptor class

# Class ValueDescriptor

java.lang.Object
jdk.jfr.ValueDescriptor

public final class ValueDescriptor extends Object
Describes the event fields and annotation elements.

The following example shows how the `ValueDescriptor` class can be used to list field information of all types.

    void printTypes() {
        Map<String, List<ValueDescriptor>> typeMap = new LinkedHashMap<>();
        for (EventType eventType : FlightRecorder.getFlightRecorder().getEventTypes()) {
            findTypes(typeMap, eventType.getName(), eventType.getFields());
        }
        for (String type : typeMap.keySet()) {
            System.out.println("Type: " + type);
            for (ValueDescriptor field : typeMap.get(type)) {
                System.out.println(" Field: " + field.getName());
                String arrayBrackets = field.isArray() ? "[]" : "";
                System.out.println("  Type: " + field.getTypeName() + arrayBrackets);
                if (field.getLabel() != null) {
                    System.out.println("  Label: " + field.getLabel());
                }
                if (field.getDescription() != null) {
                    System.out.println("  Description: " + field.getDescription());
                }
                if (field.getContentType() != null) {
                    System.out.println("  Content Types: " + field.getContentType());
                }
            }
            System.out.println();
        }
    }

    void findTypes(Map<String, List<ValueDescriptor>> typeMap, String typeName, List<ValueDescriptor> fields) {
        if (!typeMap.containsKey(typeName)) {
            typeMap.put(typeName, fields);
            for (ValueDescriptor subField : fields) {
                findTypes(typeMap, subField.getTypeName(), subField.getFields());
            }
        }
    }

Since:
  9

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ValueDescriptor(Class<?> type, String name)`
  Constructs a value descriptor, useful for dynamically creating event types and annotations.
  `ValueDescriptor(Class<?> type, String name, List<AnnotationElement> annotations)`
  Constructs a value descriptor, useful for dynamically creating event types and annotations.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<A extends Annotation>
  A`
  `getAnnotation(Class<A> annotationType)`
  Returns the first annotation for the specified type if an annotation element with the same name is directly present for this value descriptor, `null` otherwise.
  `List<AnnotationElement>`
  `getAnnotationElements()`
  Returns an immutable list of annotation elements for this value descriptor.
  `String`
  `getContentType()`
  Returns a textual identifier that specifies how a value represented by this `ValueDescriptor` is interpreted or formatted.
  `String`
  `getDescription()`
  Returns a sentence describing the value (for example, `"Maximum throughput in the transaction system. Value is reset after each new batch."`).
  `List<ValueDescriptor>`
  `getFields()`
  Returns an immutable list of value descriptors if the type is complex, else an empty list.
  `String`
  `getLabel()`
  Returns a human-readable name that describes the value (for example, `"Maximum Throughput"`).
  `String`
  `getName()`
  Returns the name of the value (for example, `"maxThroughput"`).
  `long`
  `getTypeId()`
  Returns a unique ID for the type in the Java virtual Machine (JVM).
  `String`
  `getTypeName()`
  Returns the fully qualified class name of the type that is associated with this value descriptor.
  `boolean`
  `isArray()`
  Returns if this value descriptor is an array type.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Constructor Details

  - ### ValueDescriptor

    public ValueDescriptor(Class<?> type, String name)

    Constructs a value descriptor, useful for dynamically creating event types and annotations.

    The following types are supported:

    - `byte.class`
    - `short.class`
    - `int.class`
    - `long.class`
    - `char.class`
    - `float.class`
    - `double.class`
    - `boolean.class`
    - `String.class`
    - `Class.class`
    - `Thread.class`

    The name must be a valid Java identifier (for example, `"maxThroughput"`). See section 3.8 and 3.9 of the Java Language Specification for more information.

    Parameters:
      `type` - the type, not `null`
      `name` - the name, not `null`
    Throws:
      `IllegalArgumentException` - if the name is not a valid Java identifier

  - ### ValueDescriptor

    public ValueDescriptor(Class<?> type, String name, List<AnnotationElement> annotations)

    Constructs a value descriptor, useful for dynamically creating event types and annotations.

    The following types are supported:

    - `byte.class`
    - `short.class`
    - `int.class`
    - `long.class`
    - `char.class`
    - `float.class`
    - `double.class`
    - `boolean.class`
    - `String.class`
    - `Class.class`
    - `Thread.class`

    The name must be a valid Java identifier (for example, `"maxThroughput"`). See section 3.8 and 3.9 of the Java Language Specification for more information.

    Parameters:
      `type` - the type, not `null`
      `name` - the name, not `null`
      `annotations` - the annotations on the value descriptors, not `null`
    Throws:
      `IllegalArgumentException` - if the name is not a valid Java identifier

- ## Method Details

  - ### getLabel

    public String getLabel()
    Returns a human-readable name that describes the value (for example, `"Maximum Throughput"`).
    Returns:
      a human-readable name, or `null` if doesn't exist

  - ### getName

    public String getName()
    Returns the name of the value (for example, `"maxThroughput"`).
    Returns:
      the name, not `null`

  - ### getDescription

    public String getDescription()
    Returns a sentence describing the value (for example, `"Maximum throughput in the transaction system. Value is reset after each new batch."`).
    Returns:
      the description, or `null` if doesn't exist

  - ### getContentType

    public String getContentType()
    Returns a textual identifier that specifies how a value represented by this `ValueDescriptor` is interpreted or formatted.

    For example, if the value descriptor's type is `float` and the event value is `0.5f`, a content type of `"jdk.jfr.Percentage"` hints to a client that the value is a percentage and that it should be rendered as `"50%"`.

    The JDK provides the following predefined content types:

    - jdk.jfr.Percentage
    - jdk.jfr.Timespan
    - jdk.jfr.Timestamp
    - jdk.jfr.Frequency
    - jdk.jfr.Flag
    - jdk.jfr.MemoryAddress
    - jdk.jfr.DataAmount
    - jdk.jfr.NetworkAddress

    User-defined content types can be created by using the `ContentType` class.

    Returns:
      the content type, or `null` if doesn't exist
    See Also:
      - `ContentType`

  - ### getTypeName

    public String getTypeName()
    Returns the fully qualified class name of the type that is associated with this value descriptor.
    Returns:
      the type name, not `null`
    See Also:
      - `getTypeId()`

  - ### getTypeId

    public long getTypeId()
    Returns a unique ID 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

  - ### isArray

    public boolean isArray()
    Returns if this value descriptor is an array type.
    Returns:
      `true` if it is an array type, `false` otherwise

  - ### getAnnotation

    public <A extends Annotation> A getAnnotation(Class<A> annotationType)
    Returns the first annotation for the specified type if an annotation element with the same name is directly present for this value descriptor, `null` otherwise.
    Type Parameters:
      `A` - the type of the annotation to query for and return if present
    Parameters:
      `annotationType` - the Class object that corresponds to the annotation type, not `null`
    Returns:
      this element's annotation for the specified annotation type if directly present, else `null`

  - ### getAnnotationElements

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

  - ### getFields

    public List<ValueDescriptor> getFields()
    Returns an immutable list of value descriptors if the type is complex, else an empty list.
    Returns:
      a list of value descriptors, not `null`