RecordedObject (Java SE 15 & JDK 15)
Description: declaration: module: jdk.jfr, package: jdk.jfr.consumer, class: RecordedObject
Keywords: jdk.jfr.consumer.RecordedObject class

Module jdk.jfr
Package jdk.jfr.consumer

# Class RecordedObject

java.lang.Object
jdk.jfr.consumer.RecordedObject

Direct Known Subclasses:
  `RecordedClass`, `RecordedClassLoader`, `RecordedEvent`, `RecordedFrame`, `RecordedMethod`, `RecordedStackTrace`, `RecordedThread`, `RecordedThreadGroup`

    public class RecordedObject
    extends Object

A complex data type that consists of one or more fields.

This class provides methods to select and query nested objects by passing a dot `"."` delimited `String` object (for instance, `"aaa.bbb"`). A method evaluates a nested object from left to right, and if a part is `null`, it throws `NullPointerException`.

Since:
  9

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `boolean` | `getBoolean​(String name)` | Returns the value of a field of type `boolean`.
  `byte` | `getByte​(String name)` | Returns the value of a field of type `byte`.
  `char` | `getChar​(String name)` | Returns the value of a field of type `char`.
  `RecordedClass` | `getClass​(String name)` | Returns the value of a field of type `Class`.
  `double` | `getDouble​(String name)` | Returns the value of a field of type `double` or of another primitive type that is convertible to type `double` by a widening conversion.
  `Duration` | `getDuration​(String name)` | Returns the value of a timespan field.
  `List<ValueDescriptor>` | `getFields()` | Returns an immutable list of the fields for this object.
  `float` | `getFloat​(String name)` | Returns the value of a field of type `float` or of another primitive type convertible to type `float` by a widening conversion.
  `Instant` | `getInstant​(String name)` | Returns the value of a timestamp field.
  `int` | `getInt​(String name)` | Returns the value of a field of type `int` or of another primitive type that is convertible to type `int` by a widening conversion.
  `long` | `getLong​(String name)` | Returns the value of a field of type `long` or of another primitive type that is convertible to type `long` by a widening conversion.
  `short` | `getShort​(String name)` | Returns the value of a field of type `short` or of another primitive type convertible to type `short` by a widening conversion.
  `String` | `getString​(String name)` | Returns the value of a field of type `String`.
  `RecordedThread` | `getThread​(String name)` | Returns the value of a field of type `Thread`.
  `<T> T` | `getValue​(String name)` | Returns the value of the field with the given name.
  `boolean` | `hasField​(String name)` | Returns `true` if a field with the given name exists, `false` otherwise.
  `protected Object` | `objectAt​(int index)` |
  `String` | `toString()` | Returns a textual representation of this object.

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

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

- ## Method Details

  - ### hasField

    public boolean hasField​(String name)
    Returns `true` if a field with the given name exists, `false` otherwise.
    Parameters:
      `name` - name of the field to get, not `null`
    Returns:
      `true` if the field exists, `false` otherwise
    See Also:
      `getFields()`

  - ### getValue

    public final <T> T getValue​(String name)
    Returns the value of the field with the given name.

    The return type may be a primitive type or a subclass of `RecordedObject`.

    It's possible to index into a nested object by using `"."` (for instance `"thread.group.parent.name`").

    A field might change or be removed in a future JDK release. A best practice for callers of this method is to validate the field before attempting access.

    Example

         if (event.hasField("intValue")) {
           int intValue = event.getValue("intValue");
           System.out.println("Int value: " + intValue);
         }

         if (event.hasField("objectClass")) {
           RecordedClass clazz = event.getValue("objectClass");
           System.out.println("Class name: " + clazz.getName());
         }

         if (event.hasField("sampledThread")) {
           RecordedThread sampledThread = event.getValue("sampledThread");
           System.out.println("Sampled thread: " + sampledThread.getJavaName());
         }

    Type Parameters:
      `T` - the return type
    Parameters:
      `name` - of the field to get, not `null`
    Returns:
      the value, can be `null`
    Throws:
      `IllegalArgumentException` - if no field called `name` exists
    See Also:
      `hasField(String)`

  - ### objectAt

    protected Object objectAt​(int index)

  - ### getFields

    public List<ValueDescriptor> getFields()
    Returns an immutable list of the fields for this object.
    Returns:
      the fields, not `null`

  - ### getBoolean

    public final boolean getBoolean​(String name)
    Returns the value of a field of type `boolean`.

    It's possible to index into a nested object using `"."` (for example, `"aaa.bbb"`).

    A field might change or be removed in a future JDK release. A best practice for callers of this method is to validate the field before attempting access.

    Parameters:
      `name` - name of the field to get, not `null`
    Returns:
      the value of the field, `true` or `false`
    Throws:
      `IllegalArgumentException` - if the field doesn't exist, or the field is not of type `boolean`
    See Also:
      `hasField(String)`, `getValue(String)`

  - ### getByte

    public final byte getByte​(String name)
    Returns the value of a field of type `byte`.

    It's possible to index into a nested object using `"."` (for example, `"foo.bar"`).

    A field might change or be removed in a future JDK release. A best practice for callers of this method is to validate the field before attempting access.

    Parameters:
      `name` - of the field to get, not `null`
    Returns:
      the value of the field
    Throws:
      `IllegalArgumentException` - if the field doesn't exist, or the field is not of type `byte`
    See Also:
      `hasField(String)`, `getValue(String)`

  - ### getChar

    public final char getChar​(String name)
    Returns the value of a field of type `char`.

    It's possible to index into a nested object using `"."` (for example, `"aaa.bbb"`).

    A field might change or be removed in a future JDK release. A best practice for callers of this method is to validate the field before attempting access.

    Parameters:
      `name` - of the field to get, not `null`
    Returns:
      the value of the field as a `char`
    Throws:
      `IllegalArgumentException` - if the field doesn't exist, or the field is not of type `char`
    See Also:
      `hasField(String)`, `getValue(String)`

  - ### getShort

    public final short getShort​(String name)
    Returns the value of a field of type `short` or of another primitive type convertible to type `short` by a widening conversion.

    This method can be used on the following types: `short` and `byte`.

    If the field has the `@Unsigned` annotation and is of a narrower type than `short`, then the value is returned as an unsigned.

    It's possible to index into a nested object using `"."` (for example, `"aaa.bbb"`).

    A field might change or be removed in a future JDK release. A best practice for callers of this method is to validate the field before attempting access.

    Parameters:
      `name` - of the field to get, not `null`
    Returns:
      the value of the field converted to type `short`
    Throws:
      `IllegalArgumentException` - if the field doesn't exist, or the field value can't be converted to the type `short` by a widening conversion
    See Also:
      `hasField(String)`, `getValue(String)`

  - ### getInt

    public final int getInt​(String name)
    Returns the value of a field of type `int` or of another primitive type that is convertible to type `int` by a widening conversion.

    This method can be used on fields of the following types: `int`, `short`, `char`, and `byte`.

    If the field has the `@Unsigned` annotation and is of a narrower type than `int`, then the value will be returned as an unsigned.

    It's possible to index into a nested object using `"."` (for example, `"aaa.bbb"`).

    A field might change or be removed in a future JDK release. A best practice for callers of this method is to validate the field before attempting access.

    Parameters:
      `name` - of the field to get, not `null`
    Returns:
      the value of the field converted to type `int`
    Throws:
      `IllegalArgumentException` - if the field doesn't exist, or the field value can't be converted to the type `int` by a widening conversion
    See Also:
      `hasField(String)`, `getValue(String)`

  - ### getFloat

    public final float getFloat​(String name)
    Returns the value of a field of type `float` or of another primitive type convertible to type `float` by a widening conversion.

    This method can be used on fields of the following types: `float`, `long`, `int`, `short`, `char`, and `byte`.

    It's possible to index into a nested object using `"."` (for example, `"aaa.bbb"`).

    A field might change or be removed in a future JDK release. A best practice for callers of this method is to validate the field before attempting access.

    Parameters:
      `name` - of the field to get, not `null`
    Returns:
      the value of the field converted to type `float`
    Throws:
      `IllegalArgumentException` - if the field doesn't exist, or the field value can't be converted to the type `float` by a widening conversion
    See Also:
      `hasField(String)`, `getValue(String)`

  - ### getLong

    public final long getLong​(String name)
    Returns the value of a field of type `long` or of another primitive type that is convertible to type `long` by a widening conversion.

    This method can be used on fields of the following types: `long`, `int`, `short`, `char`, and `byte`.

    If the field has the `@Unsigned` annotation and is of a narrower type than `long`, then the value will be returned as an unsigned.

    It's possible to index into a nested object using `"."` (for example, `"aaa.bbb"`).

    A field might change or be removed in a future JDK release. A best practice for callers of this method is to validate the field before attempting access.

    Parameters:
      `name` - of the field to get, not `null`
    Returns:
      the value of the field converted to type `long`
    Throws:
      `IllegalArgumentException` - if the field doesn't exist, or the field value can't be converted to the type `long` via a widening conversion
    See Also:
      `hasField(String)`, `getValue(String)`

  - ### getDouble

    public final double getDouble​(String name)
    Returns the value of a field of type `double` or of another primitive type that is convertible to type `double` by a widening conversion.

    This method can be used on fields of the following types: `double`, `float`, `long`, `int`, `short`, `char`, and `byte`.

    It's possible to index into a nested object using `"."` (for example, `"aaa.bbb"`).

    A field might change or be removed in a future JDK release. A best practice for callers of this method is to validate the field before attempting access.

    Parameters:
      `name` - of the field to get, not `null`
    Returns:
      the value of the field converted to type `double`
    Throws:
      `IllegalArgumentException` - if the field doesn't exist, or the field value can't be converted to the type `double` by a widening conversion
    See Also:
      `hasField(String)`, `getValue(String)`

  - ### getString

    public final String getString​(String name)
    Returns the value of a field of type `String`.

    It's possible to index into a nested object using `"."` (for example, `"foo.bar"`).

    A field might change or be removed in a future JDK release. A best practice for callers of this method is to validate the field before attempting access.

    Parameters:
      `name` - of the field to get, not `null`
    Returns:
      the value of the field as a `String`, can be `null`
    Throws:
      `IllegalArgumentException` - if the field doesn't exist, or the field isn't of type `String`
    See Also:
      `hasField(String)`, `getValue(String)`

  - ### getDuration

    public final Duration getDuration​(String name)
    Returns the value of a timespan field.

    This method can be used on fields annotated with `@Timespan`, and of the following types: `long`, `int`, `short`, `char`, and `byte`.

    It's possible to index into a nested object using `"."` (for example, `"aaa.bbb"`).

    A field might change or be removed in a future JDK release. A best practice for callers of this method is to validate the field before attempting access.

    Parameters:
      `name` - of the field to get, not `null`
    Returns:
      a time span represented as a `Duration`, not `null`
    Throws:
      `IllegalArgumentException` - if the field doesn't exist, or the field value can't be converted to a `Duration` object
    See Also:
      `hasField(String)`, `getValue(String)`

  - ### getInstant

    public final Instant getInstant​(String name)
    Returns the value of a timestamp field.

    This method can be used on fields annotated with `@Timestamp`, and of the following types: `long`, `int`, `short`, `char` and `byte`.

    It's possible to index into a nested object using `"."` (for example, `"aaa.bbb"`).

    A field might change or be removed in a future JDK release. A best practice for callers of this method is to validate the field before attempting access.

    Parameters:
      `name` - of the field to get, not `null`
    Returns:
      a timstamp represented as an `Instant`, not `null`
    Throws:
      `IllegalArgumentException` - if the field doesn't exist, or the field value can't be converted to an `Instant` object
    See Also:
      `hasField(String)`, `getValue(String)`

  - ### getClass

    public final RecordedClass getClass​(String name)
    Returns the value of a field of type `Class`.

    It's possible to index into a nested object using `"."` (for example, `"aaa.bbb"`).

    A field might change or be removed in a future JDK release. A best practice for callers of this method is to validate the field before attempting access.

    Parameters:
      `name` - of the field to get, not `null`
    Returns:
      the value of the field as a `RecordedClass`, can be `null`
    Throws:
      `IllegalArgumentException` - if the field doesn't exist, or the field isn't of type `Class`
    See Also:
      `hasField(String)`, `getValue(String)`

  - ### getThread

    public final RecordedThread getThread​(String name)
    Returns the value of a field of type `Thread`.

    It's possible to index into a nested object using `"."` (for example, `"foo.bar"`).

    A field might change or be removed in a future JDK release. A best practice for callers of this method is to validate the field before attempting access.

    Parameters:
      `name` - of the field to get, not `null`
    Returns:
      the value of the field as a `RecordedThread` object, can be `null`
    Throws:
      `IllegalArgumentException` - if the field doesn't exist, or the field isn't of type `Thread`
    See Also:
      `hasField(String)`, `getValue(String)`

  - ### toString

    public final String toString()
    Returns a textual representation of this object.
    Overrides:
      `toString` in class `Object`
    Returns:
      textual description of this object