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

# Class RecordingFile

java.lang.Object
jdk.jfr.consumer.RecordingFile

All Implemented Interfaces:
  `Closeable, AutoCloseable`

public final class RecordingFile extends Object implements Closeable
A recording file.

The following example shows how to read and print all events in a recording file.

    try (RecordingFile recordingFile = new RecordingFile(Paths.get("recording.jfr"))) {
        while (recordingFile.hasMoreEvents()) {
            RecordedEvent event = recordingFile.readEvent();
            System.out.println(event);
        }
    }

Since:
  9

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `RecordingFile(Path file)`
  Creates a recording file.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Closes this recording file and releases any system resources that are associated with it.
  `boolean`
  `hasMoreEvents()`
  Returns `true` if unread events exist in the recording file, `false` otherwise.
  `static List<RecordedEvent>`
  `readAllEvents(Path path)`
  Returns a list of all events in a file.
  `RecordedEvent`
  `readEvent()`
  Reads the next event in the recording.
  `List<EventType>`
  `readEventTypes()`
  Returns a list of all event types in this recording.
  `void`
  `write(Path destination, Predicate<RecordedEvent> filter)`
  Filter out events and write them to a new file.

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

  - ### RecordingFile

    public RecordingFile(Path file) throws IOException
    Creates a recording file.

    Only recording files from trusted sources should be used.

    Parameters:
      `file` - the path of the file to open, not `null`
    Throws:
      `IOException` - if it's not a valid recording file, or an I/O error occurred
      `NoSuchFileException` - if the `file` can't be located

- ## Method Details

  - ### readEvent

    public RecordedEvent readEvent() throws IOException
    Reads the next event in the recording.
    Returns:
      the next event, not `null`
    Throws:
      `EOFException` - if no more events exist in the recording file
      `IOException` - if an I/O error occurs
    See Also:
      - `hasMoreEvents()`

  - ### hasMoreEvents

    public boolean hasMoreEvents()
    Returns `true` if unread events exist in the recording file, `false` otherwise.
    Returns:
      `true` if unread events exist in the recording, `false` otherwise.

  - ### readEventTypes

    public List<EventType> readEventTypes() throws IOException
    Returns a list of all event types in this recording.
    Returns:
      a list of event types, not `null`
    Throws:
      `IOException` - if an I/O error occurred while reading from the file
    See Also:
      - `hasMoreEvents()`

  - ### close

    public void close() throws IOException
    Closes this recording file and releases any system resources that are associated with it.
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Throws:
      `IOException` - if an I/O error occurred

  - ### write

    public void write(Path destination, Predicate<RecordedEvent> filter) throws IOException
    Filter out events and write them to a new file.
    Parameters:
      `destination` - path where the new file should be written, not `null`
      `filter` - filter that determines if an event should be included, not `null`
    Throws:
      `IOException` - if an I/O error occurred, it's not a Flight Recorder file or a version of a JFR file that can't be parsed
    Since:
      19

  - ### readAllEvents

    public static List<RecordedEvent> readAllEvents(Path path) throws IOException
    Returns a list of all events in a file.

    This method is intended for simple cases where it's convenient to read all events in a single operation. It isn't intended for reading large files.

    Only recording files from trusted sources should be used.

    Parameters:
      `path` - the path to the file, not `null`
    Returns:
      the events from the file as a `List` object; whether the `List` is modifiable or not is implementation dependent and therefore not specified, not `null`
    Throws:
      `IOException` - if an I/O error occurred, it's not a Flight Recorder file or a version of a JFR file that can't be parsed