1 /*
   2  * Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package jdk.management.jfr;
  27 
  28 import java.io.IOException;
  29 import java.lang.management.PlatformManagedObject;
  30 import java.time.Instant;
  31 import java.util.List;
  32 import java.util.Map;
  33 
  34 import jdk.jfr.Configuration;
  35 import jdk.jfr.EventType;
  36 import jdk.jfr.Recording;
  37 
  38 /**
  39  * Management interface for controlling Flight Recorder.
  40  * <p>
  41  * The object name for identifying the MXBean in the platform MBean
  42  * server is: <blockquote> {@code jdk.management.jfr:type=FlightRecorder} </blockquote>
  43  * <p>
  44  * Flight Recorder can be configured in the following ways:
  45  * <ul>
  46  * <li><b>Recording options</b><br>
  47  * Specify how long a recording should last, and where and when data
  48  * should be dumped.</li>
  49  * <li><b>Settings</b><br>
  50  * Specify which events should be enabled and what kind information each
  51  * event should capture.</li>
  52  * <li><b>Configurations</b><br>
  53  * Predefined sets of settings, typically derived from a settings file,
  54  * that specify the configuration of multiple events simultaneously.</li>
  55  * </ul>
  56  * <p>
  57  * See the package {@code jdk.jfr} documentation for descriptions of the settings
  58  * syntax and the {@link ConfigurationInfo} class documentation for configuration information.
  59  *
  60  * <h3>Recording options</h3>
  61  * <p>
  62  * The following table shows the options names to use with {@link #setRecordingOptions(long, Map)}
  63  * and {@link #getRecordingOptions(long)}.
  64  *
  65  * <table class="striped">
  66  * <caption>Recording options</caption>
  67  * <thead>
  68  * <tr>
  69  * <th scope="col">Name</th>
  70  * <th scope="col">Descripion</th>
  71  * <th scope="col">Default value</th>
  72  * <th scope="col">Format</th>
  73  * <th scope="col">Example values</th>
  74  * </tr>
  75  * </thead>
  76  * <tbody>
  77  * <tr>
  78  * <th scope="row">{@code name}</th>
  79  * <td>Sets a human-readable recording name</td>
  80  * <td>String representation of the recording id</td>
  81  * <td>{@code String}</td>
  82  * <td>{@code "My Recording"}, <br>
  83  * {@code "profiling"}</td>
  84  * </tr>
  85  * <tr>
  86  * <th scope="row">{@code maxAge}</th>
  87  * <td>Specify the length of time that the data is kept in the disk repository until the
  88  * oldest data may be deleted. Only works if {@code disk=true}, otherwise
  89  * this parameter is ignored.</td>
  90  * <td>{@code "0"} (no limit)</td>
  91  * <td>{@code "0"} if no limit is imposed, otherwise a string
  92  * representation of a positive {@code Long} value followed by an empty space
  93  * and one of the following units,<br>
  94  * <br>
  95  * {@code "ns"} (nanoseconds)<br>
  96  * {@code "us"} (microseconds)<br>
  97  * {@code "ms"} (milliseconds)<br>
  98  * {@code "s"} (seconds)<br>
  99  * {@code "m"} (minutes)<br>
 100  * {@code "h"} (hours)<br>
 101  * {@code "d"} (days)<br>
 102  * </td>
 103  * <td>{@code "2 h"},<br>
 104  * {@code "24 h"},<br>
 105  * {@code "2 d"},<br>
 106  * {@code "0"}</td>
 107  * </tr>
 108  * <tr>
 109  * <th scope="row">{@code maxSize}</th>
 110  * <td>Specifies the size, measured in bytes, at which data is kept in disk
 111  * repository. Only works if
 112  * {@code disk=true}, otherwise this parameter is ignored.</td>
 113  * <td>{@code "0"} (no limit)</td>
 114  * <td>String representation of a {@code Long} value, must be positive</td>
 115  * <td>{@code "0"}, <br>
 116  * {@code "1000000000"}</td>
 117  * </tr>
 118  * <tr>
 119  * <th scope="row">{@code dumpOnExit}</th>
 120  * <td>Dumps recording data to disk on Java Virtual Machine (JVM) exit</td>
 121  * <td>{@code "false"}</td>
 122  * <td>String representation of a {@code Boolean} value, {@code "true"} or
 123  * {@code "false"}</td>
 124  * <td>{@code "true"},<br>
 125  * {@code "false"}</td>
 126  * </tr>
 127  * <tr>
 128  * <th scope="row">{@code destination}</th>
 129  * <td>Specifies the path where recording data is written when the recording stops.</td>
 130  * <td>{@code "false"}</td>
 131  * <td>See {@code Paths#getPath} for format. <br>
 132  * If this method is invoked from another process, the data is written on the
 133  * machine where the target JVM is running. If destination is a relative path, it
 134  * is relative to the working directory where the target JVM was started.}</td>
 135  * <td>{@code "c:\recording\recotding.jfr"},<br>
 136  * {@code "/recordings/recording.jfr"}, {@code "recording.jfr"}</td>
 137  * </tr>
 138  * <tr>
 139  * <th scope="row">{@code disk}</th>
 140  * <td>Stores recorded data as it is recorded</td>
 141  * <td><code>"false"</code></td>
 142  * <td>String representation of a {@code Boolean} value, {@code "true"} or
 143  * {@code "false"}</td>
 144  * <td>{@code "true"},<br>
 145  * {@code "false"}</td>
 146  * <tr>
 147  * <th scope="row">{@code duration}</th>
 148  * <td>Sets how long the recording should be running</td>
 149  * <td>{@code "0"} (no limit, continuous)</td>
 150  * <td>{@code "0"} if no limit should be imposed, otherwise a string
 151  * representation of a positive {@code Long} followed by an empty space and one
 152  * of the following units:<br>
 153  * <br>
 154  * {@code "ns"} (nanoseconds)<br>
 155  * {@code "us"} (microseconds)<br>
 156  * {@code "ms"} (milliseconds)<br>
 157  * {@code "s"} (seconds)<br>
 158  * {@code "m"} (minutes)<br>
 159  * {@code "h"} (hours)<br>
 160  * {@code "d"} (days)<br>
 161  * </td>
 162  * <td>{@code "60 s"},<br>
 163  * {@code "10 m"},<br>
 164  * {@code "4 h"},<br>
 165  * {@code "0"}</td>
 166  * </tr>
 167  * </tbody>
 168  * </table>
 169  *
 170  * @since 9
 171  */
 172 public interface FlightRecorderMXBean extends PlatformManagedObject {
 173     /**
 174      * String representation of the {@code ObjectName} for the
 175      * {@code FlightRecorderMXBean}.
 176      */
 177     public static final String MXBEAN_NAME = "jdk.management.jfr:type=FlightRecorder";
 178 
 179     /**
 180      * Creates a recording, but doesn't start it.
 181      *
 182      * @return a unique ID that can be used to start, stop, close and
 183      *         configure the recording
 184      *
 185      * @throws IllegalStateException if Flight Recorder can't be created (for
 186      *         example, if the Java Virtual Machine (JVM) lacks Flight Recorder
 187      *         support, or if the file repository can't be created or accessed)
 188      *
 189      * @throws java.lang.SecurityException if a security manager exists and the
 190      *         caller does not have {@code ManagementPermission("control")}
 191      *
 192      * @see Recording
 193      */
 194     long newRecording() throws IllegalStateException, SecurityException;
 195 
 196     /**
 197      * Creates a snapshot recording of all available recorded data.
 198      * <p>
 199      * A snapshot is a synthesized recording in a stopped state. If no data is
 200      * available, a recording with size {@code 0} is returned.
 201      * <p>
 202      * A snapshot provides stable access to data for later operations (for example,
 203      * operations to change the time interval or to reduce the data size).
 204      * <p>
 205      * The caller must close the recording when access to the data is no longer
 206      * needed.
 207      *
 208      * @return a snapshot of all available recording data, not {@code null}
 209      *
 210      * @throws java.lang.SecurityException if a security manager exists and the
 211      *         caller does not have {@code ManagementPermission("control")}
 212      *
 213      * @return a unique ID that can be used for reading recording data.
 214      *
 215      * @see Recording
 216      */
 217     public long takeSnapshot();
 218 
 219     /**
 220      * Creates a copy of an existing recording, useful for extracting parts of a
 221      * recording.
 222      * <p>
 223      * The cloned recording contains the same recording data as the
 224      * original, but it has a new ID and a name prefixed with
 225      * {@code "Clone of recording"}. If the original recording is running, then
 226      * the clone is also running.
 227      *
 228      * @param recordingId the recording ID of the recording to create a clone
 229      *        from
 230      *
 231      * @param stop if the newly created clone is stopped before
 232      *        returning.
 233      *
 234      * @return a unique ID that can be used to start, stop,
 235      *         close and configure the recording
 236      *
 237      * @throws IllegalArgumentException if a recording with the specified ID
 238      *         doesn't exist
 239      *
 240      * @throws java.lang.SecurityException if a security manager exists and the
 241      *         caller does not have {@code ManagementPermission("control")}
 242      *
 243      * @see Recording
 244      */
 245     long cloneRecording(long recordingId, boolean stop) throws IllegalArgumentException, SecurityException;
 246 
 247     /**
 248      * Starts the recording with the specified ID.
 249      * <p>
 250      * A recording that is stopped can't be restarted.
 251      *
 252      * @param recordingId ID of the recording to start
 253      *
 254      * @throws IllegalArgumentException if a recording with the specified ID
 255      *         doesn't exist
 256      *
 257      * @throws java.lang.SecurityException if a security manager exists and the
 258      *         caller does not have {@code ManagementPermission("control")}
 259      *
 260      * @see Recording
 261      */
 262     void startRecording(long recordingId) throws IllegalStateException, SecurityException;
 263 
 264     /**
 265      * Stops the running recording with the specified ID.
 266      *
 267      * @param recordingId the ID of the recording to stop
 268      *
 269      * @return {@code true} if the recording is stopped, {@code false}
 270      *         otherwise
 271      *
 272      * @throws IllegalArgumentException if a recording with the specified ID
 273      *         doesn't exist
 274      * @throws IllegalStateException if the recording is not running
 275      * @throws java.lang.SecurityException if a security manager exists and the
 276      *         caller does not have {@code ManagementPermission("control")}
 277      *
 278      * @see #newRecording()
 279      */
 280     boolean stopRecording(long recordingId) throws IllegalArgumentException, IllegalStateException, SecurityException;
 281 
 282     /**
 283      * Closes the recording with the specified ID and releases any system
 284      * resources that are associated with the recording.
 285      * <p>
 286      * If the recording is already closed, invoking this method has no effect.
 287      *
 288      * @param recordingId the ID of the recording to close
 289      *
 290      * @throws IllegalArgumentException if a recording with the specified ID
 291      *         doesn't exist
 292      * @throws IOException if an I/O error occurs
 293      * @throws java.lang.SecurityException if a security manager exists and the
 294      *         caller does not have {@code ManagementPermission("control")}
 295      *
 296      * @see #newRecording()
 297      */
 298     void closeRecording(long recordingId) throws IOException;
 299 
 300     /**
 301      * Opens a data stream for the recording with the specified ID, or {@code 0}
 302      * to get data irrespective of recording.
 303      * <table class="striped">
 304      * <caption>Recording stream options</caption>
 305      * <thead>
 306      * <tr>
 307      * <th scope="col">Name</th>
 308      * <th scope="col">Descripion</th>
 309      * <th scope="col">Default value</th>
 310      * <th scope="col">Format</th>
 311      * <th scope="col">Example values</th>
 312      * </tr>
 313      * </thead>
 314      * <tbody>
 315      * <tr>
 316      * <th scope="row">{@code startTime}</th>
 317      * <td>Specifies the point in time to start a recording stream. Due to
 318      * how data is stored, some events that start or end prior to the
 319      * start time may be included.</td>
 320      * <td>{@code Instant.MIN_VALUE.toString()}</td>
 321      * <td>ISO-8601. See {@link Instant#toString}<br>
 322      * or milliseconds since epoch</td>
 323      * <td>{@code "2015-11-03T00:00"},<br>
 324      * {@code "1446508800000"}</td>
 325      * </tr>
 326      * <tr>
 327      * <th scope="row">{@code endTime}</th>
 328      * <td>Specifies the point in time to end a recording stream. Due to how
 329      * data is stored, some events that start or end after the end time may
 330      * be included.</td>
 331      * <td>{@code Instant.MAX_VALUE.toString()}</td>
 332      * <td>ISO-8601. See {@link Instant#toString} <br>
 333      * or milliseconds since epoch</td>
 334      * <td>{@code "2015-11-03T01:00"}, <br>
 335      * {@code "1446512400000"}</td>
 336      * </tr>
 337      *
 338      * <tr>
 339      * <th scope="row">{@code blockSize}</th>
 340      * <td>Specifies the maximum number of bytes to read with a call to {@code readStream}
 341      * </td>
 342      * <td>{@code "50000"}</td>
 343      * <td>A positive {@code long} value. <br>
 344      * <br>
 345      * Setting {@code blockSize} to a very high value may result in
 346      * {@link OutOfMemoryError} or an {@link IllegalArgumentException}, if the
 347      * Java Virtual Machine (JVM) deems the value too large to handle.</td>
 348      * <td>{@code "50000"},<br>
 349      * {@code "1000000"},<br>
 350      * </tr>
 351      * </tbody>
 352      * </table>
 353      * If an option is omitted from the map the default value is used.
 354      * <p>
 355      * The recording with the specified ID must be stopped before a stream can
 356      * be opened. This restriction might be lifted in future releases.
 357      *
 358      * @param recordingId ID of the recording to open the stream for
 359      *
 360      * @param streamOptions a map that contains the options that controls the amount of data
 361      *        and how it is read, or {@code null} to get all data for the
 362      *        recording with the default block size
 363      *
 364      * @return a unique ID for the stream.
 365      *
 366      * @throws IllegalArgumentException if a recording with the iD doesn't
 367      *         exist, or if {@code options} contains invalid values
 368      *
 369      * @throws IOException if the recording is closed, an I/O error occurs, or
 370      *         no data is available for the specified recording or
 371      *         interval
 372      *
 373      * @throws java.lang.SecurityException if a security manager exists and the
 374      *         caller does not have {@code ManagementPermission("control")}
 375      */
 376     long openStream(long recordingId, Map<String, String> streamOptions) throws IOException;
 377 
 378     /**
 379      * Closes the recording stream with the specified ID and releases any system
 380      * resources that are associated with the stream.
 381      * <p>
 382      * If the stream is already closed, invoking this method has no effect.
 383      *
 384      * @param streamId the ID of the stream
 385      *
 386      * @throws IllegalArgumentException if a stream with the specified ID doesn't
 387      *         exist
 388      * @throws IOException if an I/O error occurs while trying to close the stream
 389      * @throws java.lang.SecurityException if a security manager exists and the
 390      *         caller does not have {@code ManagementPermission("control")}
 391      *
 392      * @see #openStream(long, Map)
 393      */
 394     void closeStream(long streamId) throws IOException;
 395 
 396     /**
 397      * Reads a portion of data from the stream with the specified ID, or returns
 398      * {@code null} if no more data is available.
 399      * <p>
 400      * To read all data for a recording, invoke this method repeatedly until
 401      * {@code null} is returned.
 402      *
 403      * @param streamId the ID of the stream
 404      *
 405      * @return byte array that contains recording data, or {@code null} when no more
 406      *         data is available
 407      * @throws IOException if the stream is closed, or an I/O error occurred while
 408      *         trying to read the stream
 409      * @throws IllegalArgumentException if no recording with the stream ID exists
 410      * @throws java.lang.SecurityException if a security manager exists and the
 411      *         caller does not have {@code ManagementPermission("monitor")}
 412      */
 413     byte[] readStream(long streamId) throws IOException;
 414 
 415     /**
 416      * Returns a map that contains the options for the recording with the
 417      * specified ID (for example, the destination file or time span to keep
 418      * recorded data).
 419      * <p>
 420      * See {@link FlightRecorderMXBean} for available option names.
 421      *
 422      * @param recordingId the ID of the recording to get options for
 423      *
 424      * @return a map describing the recording options, not {@code null}
 425      *
 426      * @throws IllegalArgumentException if no recording with the
 427      *         specified ID exists
 428      * @throws java.lang.SecurityException if a security manager exists and the
 429      *         caller does not have {@code ManagementPermission("monitor")}
 430      *
 431      */
 432     Map<String, String> getRecordingOptions(long recordingId) throws IllegalArgumentException;
 433 
 434     /**
 435      * Returns a {@code Map} that contains the settings for the recording with the specified ID,
 436      * (for example, the event thresholds)
 437      * <p>
 438      * If multiple recordings are running at the same time, more data could be
 439      * recorded than what is specified in the {@code Map} object.
 440      * <p>
 441      * The name in the {@code Map} is the event name and the setting name separated by
 442      * {@code "#"} (for example, {@code "jdk.VMInfo#period"}). The value
 443      * is a textual representation of the settings value (for example,
 444      * {@code "60 s"}).
 445      *
 446      * @param recordingId the ID of the recordings to get settings for
 447      *
 448      * @return a map that describes the recording settings, not {@code null}
 449      *
 450      * @throws IllegalArgumentException if no recording with the specified ID exists
 451      * @throws java.lang.SecurityException if a security manager exists and the
 452      *         caller does not have {@code ManagementPermission("monitor")}
 453      */
 454     Map<String, String> getRecordingSettings(long recordingId) throws IllegalArgumentException;
 455 
 456     /**
 457      * Sets a configuration as a string representation for the recording with the
 458      * specified ID.
 459      *
 460      * @param recordingId ID of the recording
 461      * @param contents a string representation of the configuration file to use,
 462      *        not {@code null}
 463      * @throws IllegalArgumentException if no recording with the
 464      *         specified ID exists or if the configuration could not be parsed.
 465      * @throws java.lang.SecurityException if a security manager exists and the
 466      *         caller does not have {@code ManagementPermission("control")}
 467      *
 468      * @see Configuration#getContents()
 469      */
 470     void setConfiguration(long recordingId, String contents) throws IllegalArgumentException;
 471 
 472     /**
 473      * Sets a predefined configuration for the recording with the specified ID.
 474      *
 475      * @param recordingId ID of the recording to set the configuration for
 476      * @param configurationName the name of the configuration (for example,
 477      *        {@code "profile"} or {@code "default"}), not {@code null}
 478      * @throws IllegalArgumentException if no recording with the
 479      *         specified ID exists
 480      * @throws java.lang.SecurityException if a security manager exists and the
 481      *         caller does not have {@code ManagementPermission("control")}
 482      *
 483      * @see #getConfigurations()
 484      */
 485     void setPredefinedConfiguration(long recordingId, String configurationName) throws IllegalArgumentException;
 486 
 487     /**
 488      * Sets and replaces all previous settings for the specified recording.
 489      * <p>
 490      * A setting consists of a name/value pair, where <em>name</em> specifies the
 491      * event and setting to configure, and the <em>value</em> specifies what to set
 492      * it to.
 493      * <p>
 494      * The name can be formed in the following ways:
 495      * <p>
 496      * {@code
 497      *   <event-name> + "#" + <setting-name>
 498      * }
 499      * <p>
 500      * or
 501      * <p>
 502      * {@code
 503      *   <event-id> + "#" + <setting-name>
 504      * }
 505      * <p>
 506      * For example, to set the sample interval of the CPU Load event to once every
 507      * second, use the name {@code "jdk.CPULoad#period"} and the value
 508      * {@code "1 s"}. If multiple events use the same name, for example if an event
 509      * class is loaded in multiple class loaders, and differentiation is needed
 510      * between them, then the name is {@code "56#period"}. The ID for an event is
 511      * obtained by invoking {@link jdk.jfr.EventType#getId()} method and is valid
 512      * for the Java Virtual Machine (JVM) instance that the event is registered in.
 513      * <p>
 514      * A list of available event names is retrieved by invoking
 515      * {@link jdk.jfr.FlightRecorder#getEventTypes()} and
 516      * {@link jdk.jfr.EventType#getName()}. A list of available settings for an
 517      * event type is obtained by invoking
 518      * {@link jdk.jfr.EventType#getSettingDescriptors()} and
 519      * {@link jdk.jfr.ValueDescriptor#getName()}.
 520      *
 521      * @param recordingId ID of the recording
 522      *
 523      * @param settings name value map of the settings to set, not {@code null}
 524      *
 525      * @throws IllegalArgumentException if no recording with the specified ID exists
 526      * @throws java.lang.SecurityException if a security manager exists and the
 527      *         caller does not have {@code ManagementPermission("control")}
 528      *
 529      * @see Recording#getId()
 530      */
 531     void setRecordingSettings(long recordingId, Map<String, String> settings) throws IllegalArgumentException;
 532 
 533     /**
 534      * Configures the recording options (for example, destination file and time span
 535      * to keep data).
 536      * <p>
 537      * See {@link FlightRecorderMXBean} for a description of the options and values
 538      * that can be used. Setting a value to {@code null} restores the value to the
 539      * default value.
 540      *
 541      * @param recordingId the ID of the recording to set options for
 542      *
 543      * @param options name/value map of the settings to set, not {@code null}
 544      *
 545      * @throws IllegalArgumentException if no recording with the specified ID exists
 546      * @throws java.lang.SecurityException if a security manager exists, and the
 547      *         caller does not have {@code ManagementPermission("control")} or an
 548      *         option contains a file that the caller does not have permission to
 549      *         operate on.
 550      * @see Recording#getId()
 551      */
 552     void setRecordingOptions(long recordingId, Map<String, String> options) throws IllegalArgumentException;
 553 
 554     /**
 555      * Returns the list of the available recordings, not necessarily running.
 556      * <p>
 557      * <b>MBeanServer access</b>:<br>
 558      * The mapped type of {@code RecordingInfo} is {@code CompositeData} with
 559      * attributes as specified in the {@link RecordingInfo#from
 560      * RecordingInfo.from} method.
 561      *
 562      * @return list of recordings, not {@code null}
 563      *
 564      * @throws java.lang.SecurityException if a security manager exists and the
 565      *         caller does not have {@code  ManagementPermission("monitor")}
 566      *
 567      * @see RecordingInfo
 568      * @see Recording
 569      */
 570     List<RecordingInfo> getRecordings();
 571 
 572     /**
 573      * Returns the list of predefined configurations for this Java Virtual Machine (JVM).
 574      * <p>
 575      * <b>MBeanServer access</b>:<br>
 576      * The mapped type of {@code ConfigurationInfo} is {@code CompositeData}
 577      * with attributes as specified in the {@link ConfigurationInfo#from
 578      * ConfigurationInfo.from} method.
 579      *
 580      * @return the list of predefined configurations, not {@code null}
 581      *
 582      * @throws java.lang.SecurityException if a security manager exists and the
 583      *         caller does not have {@code ManagementPermission("monitor")}
 584      *
 585      * @see ConfigurationInfo
 586      * @see Configuration
 587      */
 588     List<ConfigurationInfo> getConfigurations();
 589 
 590     /**
 591      * Returns the list of currently registered event types.
 592      * <p>
 593      * <b>MBeanServer access</b>:<br>
 594      * The mapped type of {@code EventTypeInfo} is {@code CompositeData} with
 595      * attributes as specified in the {@link EventTypeInfo#from
 596      * EventTypeInfo.from} method.
 597      *
 598      * @return the list of registered event types, not {@code null}
 599      *
 600      * @throws java.lang.SecurityException if a security manager exists and the
 601      *         caller does not have {@code ManagementPermission("monitor")}
 602      *
 603      * @see EventTypeInfo
 604      * @see EventType
 605      */
 606     List<EventTypeInfo> getEventTypes();
 607 
 608     /**
 609      * Writes recording data to the specified file.
 610      * <p>
 611      * If this method is invoked remotely from another process, the data is written
 612      * to a file named {@code outputFile} on the machine where the target Java
 613      * Virtual Machine (JVM) is running. If the file location is a relative path, it
 614      * is relative to the working directory where the target JVM was started.
 615      *
 616      * @param recordingId the ID of the recording to dump data for
 617      *
 618      * @param outputFile the system-dependent file name where data is written, not
 619      *        {@code null}
 620      *
 621      * @throws IOException if the recording can't be dumped due to an I/O error (for
 622      *         example, an invalid path)
 623      *
 624      * @throws IllegalArgumentException if a recording with the specified ID doesn't
 625      *         exist
 626      *
 627      * @throws IllegalStateException if the recording is not yet started or if it is
 628      *         already closed
 629      *
 630      * @throws SecurityException if a security manager exists and its
 631      *         {@code SecurityManager.checkWrite(java.lang.String)} method denies
 632      *         write access to the named file or the caller does not have
 633      *         {@code ManagmentPermission("control")}
 634      *
 635      * @see java.nio.file.Path#toString()
 636      * @see Recording#dump(java.nio.file.Path)
 637      */
 638     void copyTo(long recordingId, String outputFile) throws IOException, SecurityException;
 639 }