Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8294530

Update specification of jdk.jfr.consumer.Recording::dump(Path) in case of an in memory recording

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P3
    • 20
    • hotspot
    • None
    • jfr
    • minimal
    • The change describes the current behavior, but doesn't change it.
    • Java API

    Description

      Summary

      Update the specification of jdk.jfr.consumer.Recording::dump(Path) to make it clear when a dump may succeed.

      Problem

      Users may believe a dump didn't succeed because of the destination path, not the state the recording is in.

      Solution

      Update the documentation to make existing behaviour clear.

      Specification

       /**
        * Writes recording data to a file.
        * <p>
      
       /**
        * Writes recording data to a file.
        * <p>
      - * Recording must be started, but not necessarily stopped.
      + * For a dump to succeed, the recording must either be 1) running, or 2) stopped
      + * and to disk. If the recording is in any other state, an
      + * {@link IOException} is thrown.
        *
        * @param destination the location where recording data is written, not
        *        {@code null}
        *
      - * @throws IOException if the recording can't be copied to the specified
      - *         location
      + * @throws IOException if recording data can't be copied to the specified
      + *         location, for example, if the recording is closed or the
      + *         destination path is not writable
        *
        * @throws SecurityException if a security manager exists and the caller doesn't
        *         have {@code FilePermission} to write to the destination path
      + *
      + * @see #getState()
      + * @see #isToDisk()
        */

      Attachments

        Issue Links

          Activity

            People

              egahlin Erik Gahlin
              egahlin Erik Gahlin
              Markus Gr├Ânlund
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: