JDK14/Java14源码在线阅读
/*
* Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package jdk.jfr;
import java.io.Closeable;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Path;
import java.time.Duration;
import java.time.Instant;
import java.util.HashMap;
import java.util.Map;
import java.util.Objects;
import jdk.jfr.internal.PlatformRecorder;
import jdk.jfr.internal.PlatformRecording;
import jdk.jfr.internal.Type;
import jdk.jfr.internal.Utils;
import jdk.jfr.internal.WriteableUserPath;
/**
* Provides means to configure, start, stop and dump recording data to disk.
* <p>
* The following example shows how configure, start, stop and dump recording data to disk.
*
* <pre>
* <code>
* Configuration c = Configuration.getConfiguration("default");
* Recording r = new Recording(c);
* r.start();
* System.gc();
* Thread.sleep(5000);
* r.stop();
* r.dump(Files.createTempFile("my-recording", ".jfr"));
* </code>
* </pre>
*
* @since 9
*/
public final class Recording implements Closeable {
private static class RecordingSettings extends EventSettings {
private final Recording recording;
private final String identifier;
RecordingSettings(Recording r, String identifier) {
this.recording = r;
this.identifier = identifier;
}
RecordingSettings(Recording r, Class<? extends Event> eventClass) {
Utils.ensureValidEventSubclass(eventClass);
this.recording = r;
this.identifier = String.valueOf(Type.getTypeId(eventClass));
}
@Override
public EventSettings with(String name, String value) {
Objects.requireNonNull(value);
recording.setSetting(identifier + "#" + name, value);
return this;
}
@Override
public Map<String, String> toMap() {
return recording.getSettings();
}
}
private final PlatformRecording internal;
public Recording(Map<String, String> settings) {
PlatformRecorder r = FlightRecorder.getFlightRecorder().getInternal();
synchronized (r) {
this.internal = r.newRecording(settings);
this.internal.setRecording(this);
if (internal.getRecording() != this) {
throw new InternalError("Internal recording not properly setup");
}
}
}
/**
* Creates a recording without any settings.
* <p>
* A newly created recording is in the {@link RecordingState#NEW} state. To start
* the recording, invoke the {@link Recording#start()} method.
*
* @throws IllegalStateException if Flight Recorder can't be created (for
* example, if the Java Virtual Machine (JVM) lacks Flight Recorder
* support, or if the file repository can't be created or accessed)
*
* @throws SecurityException If a security manager is used and
* FlightRecorderPermission "accessFlightRecorder" is not set.
*/
public Recording() {
this(new HashMap<String, String>());
}
/**
* Creates a recording with settings from a configuration.
* <p>
* The following example shows how create a recording that uses a predefined configuration.
*
* <pre>
* <code>
* Recording r = new Recording(Configuration.getConfiguration("default"));
* </code>
* </pre>
*
* The newly created recording is in the {@link RecordingState#NEW} state. To
* start the recording, invoke the {@link Recording#start()} method.
*
* @param configuration configuration that contains the settings to be use, not
* {@code null}
*
* @throws IllegalStateException if Flight Recorder can't be created (for
* example, if the Java Virtual Machine (JVM) lacks Flight Recorder
* support, or if the file repository can't be created or accessed)
*
* @throws SecurityException if a security manager is used and
* FlightRecorderPermission "accessFlightRecorder" is not set.
*
* @see Configuration
*/
public Recording(Configuration configuration) {
this(configuration.getSettings());
}
/**
* Starts this recording.
* <p>
* It's recommended that the recording options and event settings are configured
* before calling this method. The benefits of doing so are a more consistent
* state when analyzing the recorded data, and improved performance because the
* configuration can be applied atomically.
* <p>
* After a successful invocation of this method, this recording is in the
* {@code RUNNING} state.
*
* @throws IllegalStateException if recording is already started or is in the
* {@code CLOSED} state
*/
public void start() {
internal.start();
}
/**
* Starts this recording after a delay.
* <p>
* After a successful invocation of this method, this recording is in the
* {@code DELAYED} state.
*
* @param delay the time to wait before starting this recording, not
* {@code null}
* @throws IllegalStateException if the recording is not it the {@code NEW} state
*/
public void scheduleStart(Duration delay) {
Objects.requireNonNull(delay);
internal.scheduleStart(delay);
}
/**
* Stops this recording.
* <p>
* When a recording is stopped it can't be restarted. If this
* recording has a destination, data is written to that destination and
* the recording is closed. After a recording is closed, the data is no longer
* available.
* <p>
* After a successful invocation of this method, this recording will be
* in the {@code STOPPED} state.
*
* @return {@code true} if recording is stopped, {@code false} otherwise
*
* @throws IllegalStateException if the recording is not started or is already stopped
*
* @throws SecurityException if a security manager exists and the caller
* doesn't have {@code FilePermission} to write to the destination
* path
*
* @see #setDestination(Path)
*
*/
public boolean stop() {
return internal.stop("Stopped by user");
}
/**
* Returns settings used by this recording.
* <p>
* Modifying the returned {@code Map} will not change the settings for this recording.
* <p>
* If no settings are set for this recording, an empty {@code Map} is
* returned.
*
* @return recording settings, not {@code null}
*/
public Map<String, String> getSettings() {
return new HashMap<>(internal.getSettings());
}
/**
* Returns the current size of this recording in the disk repository,
* measured in bytes.
* <p>
* The size is updated when recording buffers are flushed. If the recording is
* not written to the disk repository the returned size is always {@code 0}.
*
* @return amount of recorded data, measured in bytes, or {@code 0} if the
* recording is not written to the disk repository
*/
public long getSize() {
return internal.getSize();
}
/**
* Returns the time when this recording was stopped.
*
* @return the time, or {@code null} if this recording is not stopped
*/
public Instant getStopTime() {
return internal.getStopTime();
}
/**
* Returns the time when this recording was started.
*
* @return the the time, or {@code null} if this recording is not started
*/
public Instant getStartTime() {
return internal.getStartTime();
}
/**
* Returns the maximum size, measured in bytes, at which data is no longer kept in the disk repository.
*
* @return maximum size in bytes, or {@code 0} if no maximum size is set
*/
public long getMaxSize() {
return internal.getMaxSize();
}
/**
* Returns the length of time that the data is kept in the disk repository
* before it is removed.
*
* @return maximum length of time, or {@code null} if no maximum length of time
* has been set
*/
public Duration getMaxAge() {
return internal.getMaxAge();
}
/**
* Returns the name of this recording.
* <p>
* By default, the name is the same as the recording ID.
*
* @return the recording name, not {@code null}
*/
public String getName() {
return internal.getName();
}
/**
* Replaces all settings for this recording.
* <p>
* The following example shows how to set event settings for a recording.
*
* <pre>
* <code>
* Map{@literal <}String, String{@literal >} settings = new HashMap{@literal <}{@literal >}();
* settings.putAll(EventSettings.enabled("jdk.CPUSample").withPeriod(Duration.ofSeconds(2)).toMap());
* settings.putAll(EventSettings.enabled(MyEvent.class).withThreshold(Duration.ofSeconds(2)).withoutStackTrace().toMap());
* settings.put("jdk.ExecutionSample#period", "10 ms");
* recording.setSettings(settings);
* </code>
* </pre>
*
* The following example shows how to merge settings.
*
* <pre>
* {@code
* Map<String, String> settings = recording.getSettings();
* settings.putAll(additionalSettings);
* recording.setSettings(settings);
* }
* </pre>
*
* @param settings the settings to set, not {@code null}
*/
public void setSettings(Map<String, String> settings) {
Objects.requireNonNull(settings);
Map<String, String> sanitized = Utils.sanitizeNullFreeStringMap(settings);
internal.setSettings(sanitized);
}
/**
* Returns the recording state that this recording is currently in.
*
* @return the recording state, not {@code null}
*
* @see RecordingState
*/
public RecordingState getState() {
return internal.getState();
}
/**
* Releases all data that is associated with this recording.
* <p>
* After a successful invocation of this method, this recording is in the
* {@code CLOSED} state.
*/
@Override
public void close() {
internal.close();
}
/**
* Returns a clone of this recording, with a new recording ID and name.
*
* Clones are useful for dumping data without stopping the recording. After
* a clone is created, the amount of data to copy is constrained
* with the {@link #setMaxAge(Duration)} method and the {@link #setMaxSize(long)}method.
*
* @param stop {@code true} if the newly created copy should be stopped
* immediately, {@code false} otherwise
* @return the recording copy, not {@code null}
*/
public Recording copy(boolean stop) {
return internal.newCopy(stop);
}
/**
* Writes recording data to a file.
* <p>
* Recording must be started, but not necessarily stopped.
*
* @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 SecurityException if a security manager exists and the caller doesn't
* have {@code FilePermission} to write to the destination path
*/
public void dump(Path destination) throws IOException {
Objects.requireNonNull(destination);
internal.dump(new WriteableUserPath(destination));
}
/**
* Returns {@code true} if this recording uses the disk repository, {@code false} otherwise.
* <p>
* If no value is set, {@code true} is returned.
*
* @return {@code true} if the recording uses the disk repository, {@code false}
* otherwise
*/
public boolean isToDisk() {
return internal.isToDisk();
}
/**
* Determines how much data is kept in the disk repository.
* <p>
* To control the amount of recording data that is stored on disk, the maximum
* amount of data to retain can be specified. When the maximum limit is
* exceeded, the Java Virtual Machine (JVM) removes the oldest chunk to make
* room for a more recent chunk.
* <p>
* If neither maximum limit or the maximum age is set, the size of the
* recording may grow indefinitely.
*
* @param maxSize the amount of data to retain, {@code 0} if infinite
*
* @throws IllegalArgumentException if <code>maxSize</code> is negative
*
* @throws IllegalStateException if the recording is in {@code CLOSED} state
*/
public void setMaxSize(long maxSize) {
if (maxSize < 0) {
throw new IllegalArgumentException("Max size of recording can't be negative");
}
internal.setMaxSize(maxSize);
}
/**
* Determines how often events are made available for streaming.
*
* @param interval the interval at which events are made available for streaming.
*
* @throws IllegalArgumentException if {@code interval} is negative
*
* @throws IllegalStateException if the recording is in the {@code CLOSED} state
*
* @since 14
*/
/*package private*/ void setFlushInterval(Duration interval) {
Objects.nonNull(interval);
if (interval.isNegative()) {
throw new IllegalArgumentException("Stream interval can't be negative");
}
internal.setFlushInterval(interval);
}
/**
* Returns how often events are made available for streaming purposes.
*
* @return the flush interval, or {@code null} if no interval has been set
*
* @since 14
*/
/*package private*/ Duration getFlushInterval() {
return internal.getFlushInterval();
}
/**
* Determines how far back data is kept in the disk repository.
* <p>
* To control the amount of recording data stored on disk, the maximum length of
* time to retain the data can be specified. Data stored on disk that is older
* than the specified length of time is removed by the Java Virtual Machine (JVM).
* <p>
* If neither maximum limit or the maximum age is set, the size of the
* recording may grow indefinitely.
*
* @param maxAge the length of time that data is kept, or {@code null} if infinite
*
* @throws IllegalArgumentException if <code>maxAge</code> is negative
*
* @throws IllegalStateException if the recording is in the {@code CLOSED} state
*/
public void setMaxAge(Duration maxAge) {
if (maxAge != null && maxAge.isNegative()) {
throw new IllegalArgumentException("Max age of recording can't be negative");
}
internal.setMaxAge(maxAge);
}
/**
* Sets a location where data is written on recording stop, or
* {@code null} if data is not to be dumped.
* <p>
* If a destination is set, this recording is automatically closed
* after data is successfully copied to the destination path.
* <p>
* If a destination is <em>not</em> set, Flight Recorder retains the
* recording data until this recording is closed. Use the {@link #dump(Path)} method to
* manually write data to a file.
*
* @param destination the destination path, or {@code null} if recording should
* not be dumped at stop
*
* @throws IllegalStateException if recording is in the {@code STOPPED} or
* {@code CLOSED} state.
*
* @throws SecurityException if a security manager exists and the caller
* doesn't have {@code FilePermission} to read, write, and delete the
* {@code destination} file
*
* @throws IOException if the path is not writable
*/
public void setDestination(Path destination) throws IOException {
internal.setDestination(destination != null ? new WriteableUserPath(destination) : null);
}
/**
* Returns the destination file, where recording data is written when the
* recording stops, or {@code null} if no destination is set.
*
* @return the destination file, or {@code null} if not set.
*/
public Path getDestination() {
WriteableUserPath usp = internal.getDestination();
if (usp == null) {
return null;
} else {
return usp.getPotentiallyMaliciousOriginal();
}
}
/**
* Returns a unique ID for this recording.
*
* @return the recording ID
*/
public long getId() {
return internal.getId();
}
/**
* Sets a human-readable name (for example, {@code "My Recording"}).
*
* @param name the recording name, not {@code null}
*
* @throws IllegalStateException if the recording is in {@code CLOSED} state
*/
public void setName(String name) {
Objects.requireNonNull(name);
internal.setName(name);
}
/**
* Sets whether this recording is dumped to disk when the JVM exits.
*
* @param dumpOnExit if this recording should be dumped when the JVM exits
*/
public void setDumpOnExit(boolean dumpOnExit) {
internal.setDumpOnExit(dumpOnExit);
}
/**
* Returns whether this recording is dumped to disk when the JVM exits.
* <p>
* If dump on exit is not set, {@code false} is returned.
*
* @return {@code true} if the recording is dumped on exit, {@code false}
* otherwise.
*/
public boolean getDumpOnExit() {
return internal.getDumpOnExit();
}
/**
* Determines whether this recording is continuously flushed to the disk
* repository or data is constrained to what is available in memory buffers.
*
* @param disk {@code true} if this recording is written to disk,
* {@code false} if in-memory
*
*/
public void setToDisk(boolean disk) {
internal.setToDisk(disk);
}
/**
* Creates a data stream for a specified interval.
* <p>
* The stream may contain some data outside the specified range.
*
* @param the start start time for the stream, or {@code null} to get data from
* start time of the recording
*
* @param the end end time for the stream, or {@code null} to get data until the
* present time.
*
* @return an input stream, or {@code null} if no data is available in the
* interval.
*
* @throws IllegalArgumentException if {@code end} happens before
* {@code start}
*
* @throws IOException if a stream can't be opened
*/
public InputStream getStream(Instant start, Instant end) throws IOException {
if (start != null && end != null && end.isBefore(start)) {
throw new IllegalArgumentException("End time of requested stream must not be before start time");
}
return internal.open(start, end);
}
/**
* Returns the specified duration for this recording, or {@code null} if no
* duration is set.
* <p>
* The duration can be set only when the recording is in the
* {@link RecordingState#NEW} state.
*
* @return the desired duration of the recording, or {@code null} if no duration
* has been set.
*/
public Duration getDuration() {
return internal.getDuration();
}
/**
* Sets a duration for how long a recording runs before it stops.
* <p>
* By default, a recording has no duration ({@code null}).
*
* @param duration the duration, or {@code null} if no duration is set
*
* @throws IllegalStateException if recording is in the {@code STOPPED} or {@code CLOSED} state
*/
public void setDuration(Duration duration) {
internal.setDuration(duration);
}
/**
* Enables the event with the specified name.
* <p>
* If multiple events have the same name (for example, the same class is loaded
* in different class loaders), then all events that match the name are enabled. To
* enable a specific class, use the {@link #enable(Class)} method or a {@code String}
* representation of the event type ID.
*
* @param name the settings for the event, not {@code null}
*
* @return an event setting for further configuration, not {@code null}
*
/**代码未完, 请加载全部代码(NowJava.com).**/
关注时代Java
关注时代Java