From 606c178be77d4f520d5ba7eb513a89ff20ac6e87 Mon Sep 17 00:00:00 2001 From: David Grieve Date: Tue, 23 Feb 2021 17:14:55 -0500 Subject: [PATCH] Fix javadoc and pom for publish to maven --- .gitignore | 8 + pom.xml | 149 +++++++++++++++++- .../jfr/FlightRecorderConnection.java | 18 +-- .../java/com/microsoft/jfr/JfrStream.java | 8 +- .../microsoft/jfr/JfrStreamingException.java | 6 +- .../java/com/microsoft/jfr/Recording.java | 35 ++-- .../microsoft/jfr/RecordingConfiguration.java | 5 +- .../com/microsoft/jfr/RecordingOptions.java | 27 ++-- 8 files changed, 206 insertions(+), 50 deletions(-) diff --git a/.gitignore b/.gitignore index dfcfd56..b4e7959 100644 --- a/.gitignore +++ b/.gitignore @@ -31,8 +31,15 @@ bld/ [Ll]og/ [Ll]ogs/ +# Maven build +target/ + # Visual Studio 2015/2017 cache/options directory .vs/ + +# IntelliJ Idea +.idea/ + # Uncomment if you have tasks that create the project's static files in wwwroot #wwwroot/ @@ -348,3 +355,4 @@ MigrationBackup/ # Ionide (cross platform F# VS Code tools) working folder .ionide/ + diff --git a/pom.xml b/pom.xml index 58bad1d..7ad1530 100644 --- a/pom.xml +++ b/pom.xml @@ -1,12 +1,81 @@ - + + + 4.0.0 - com.microsoft.censum + com.microsoft.jfr jfr-streaming - 1.0.0-SNAPSHOT + 1.0.0 + + + MIT License + http://opensource.org/licenses/MIT + repo + + + + + scm:git:git@github.com:Microsoft/jfr-streaming.git + scm:git:git@github.com:Microsoft/jfr-streaming.git + https://github.com/Microsoft/jfr-streaming.git + + + + + microsoft + Microsoft + + + + + GitHub + https://github.com/microsoft/jfr-streaming/issues + + + + + ossrh + https://oss.sonatype.org/content/repositories/snapshots + + + ossrh + https://oss.sonatype.org/service/local/staging/deploy/maven2/ + + + + + + release + + + release + + + + + + org.apache.maven.plugins + maven-gpg-plugin + + + org.sonatype.plugins + nexus-staging-maven-plugin + + + + + 8 8 + 8 + 8 + UTF-8 @@ -20,6 +89,19 @@ + + org.apache.maven.plugins + maven-compiler-plugin + 3.8.1 + + ${maven.compiler.source} + ${maven.compiler.testSource} + ${maven.compiler.target} + ${maven.compiler.testTarget} + true + true + + org.apache.maven.plugins maven-jar-plugin @@ -30,6 +112,67 @@ + + org.apache.maven.plugins + maven-source-plugin + 3.2.1 + + + attach-sources + + jar-no-fork + + + + + + org.apache.maven.plugins + maven-javadoc-plugin + 3.2.0 + + + 8 + false + + + + attach-javadocs + + jar + + + + + + org.apache.maven.plugins + maven-surefire-plugin + 3.0.0-M4 + + + org.apache.maven.plugins + maven-gpg-plugin + 1.6 + + + sign-artifacts + deploy + + sign + + + + + + org.sonatype.plugins + nexus-staging-maven-plugin + 1.6.8 + true + + ossrh + https://oss.sonatype.org/ + false + + diff --git a/src/main/java/com/microsoft/jfr/FlightRecorderConnection.java b/src/main/java/com/microsoft/jfr/FlightRecorderConnection.java index 320a883..5046e1f 100644 --- a/src/main/java/com/microsoft/jfr/FlightRecorderConnection.java +++ b/src/main/java/com/microsoft/jfr/FlightRecorderConnection.java @@ -29,13 +29,13 @@ import javax.management.openmbean.TabularType; * Represents a connection to a {@code jdk.management.jfr.FlightRecorderMXBean} of a JVM. * {@code FlightRecorderConnection} provides {@link #newRecording(RecordingOptions, RecordingConfiguration) API} to create * Java flight {@link Recording recordings}. More than one {@code Recording} can be created. - * + *

* To use this class, a {@code javax.management.MBeanServerConnection} is needed. * This class uses the connection to make calls to the MBean server and does not change * the state of the connection. Management of the connection is the concern of the caller * and use of a {@code FlightRecorderConnection} for an MBean server connection that is no * longer valid will result in {@code IOException} being thrown. - * + *

* The {@code MBeanServerConnection} can be a connection to any MBean server. * Typically, the connection is to the platform MBean server obtained by calling * {@code java.lang.management.ManagementFactory.getPlatformMBeanServer()}. The connection can @@ -80,11 +80,11 @@ public class FlightRecorderConnection { } /** - * Create a {@link Recording} with the given configuration. The {@code Recording} is created - * in the {@link Recording.State#NEW} state. If {@code null} is passed for the - * {@code configuration} parameter, the recording will use the default values of - * {@code jdk.management.jfr.FlightRecorderMXBean}. - * @param recordingOptions The configuration to be used for the recording. + * Create a {@link Recording} with the given options and configuration. The {@code Recording} is created + * in the {@link Recording.State#NEW} state. The recording will use the default values of + * {@code jdk.management.jfr.FlightRecorderMXBean} for a parameter passed as {@code null}. + * @param recordingOptions The options to be used for the recording, or {@code null} for defaults. + * @param recordingConfiguration The configuration to be used for the recording, or {@code null} for defaults. * @return A {@link Recording} object associated with this {@code FlightRecorderConnection}. */ public Recording newRecording( @@ -170,7 +170,7 @@ public class FlightRecorderConnection { * @param id The id of the recording. * @param outputFile the system-dependent file name where data is written, not {@code null} * @throws IOException A communication problem occurred when talking to the MBean server. - * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. See {@link JfrStreamingException}. + * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. */ /* package-scoped */ void dumpRecording(long id, String outputFile) throws IOException, JfrStreamingException { try { @@ -189,7 +189,7 @@ public class FlightRecorderConnection { * @param id The id of the recording being cloned. * @param stop Whether to stop the cloned recording. * @throws IOException A communication problem occurred when talking to the MBean server. - * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. See {@link JfrStreamingException}. + * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. */ /* package-scoped */ long cloneRecording(long id, boolean stop) throws IOException, JfrStreamingException { try { diff --git a/src/main/java/com/microsoft/jfr/JfrStream.java b/src/main/java/com/microsoft/jfr/JfrStream.java index 43ba515..84e5e99 100644 --- a/src/main/java/com/microsoft/jfr/JfrStream.java +++ b/src/main/java/com/microsoft/jfr/JfrStream.java @@ -11,7 +11,7 @@ import javax.management.ObjectName; import javax.management.ReflectionException; /** - * A JFR data stream backed by {@code FlightRecorderMXBean#readStream(long)}. + * A JFR data stream backed by {@code jdk.management.jfr.FlightRecorderMXBean#readStream(long)}. */ class JfrStream extends InputStream { @@ -20,7 +20,11 @@ class JfrStream extends InputStream { /** * Get the default value for blockSize used to configure the FlightRecorderMXBean#readStream(long) stream. - * The default is configurable by setting the {@code jfrstream.blocksize} system property. + * The default is configurable by setting the {@code jfr.stream.blocksize} system property. + * The {@code blockSize} is used to configure the maximum number of bytes to read + * from underlying stream at a time. Setting blockSize to a very high value may result + * in an exception if the Java Virtual Machine (JVM) deems the value too large to handle. + * Refer to the javadoc for {@code jdk.management.jfr.FlightRecorderMXBean#openStream}. * @return The default blockSize for reading flight recording data */ public static long getDefaultBlockSize() { return DEFAULT_BLOCKSIZE; } diff --git a/src/main/java/com/microsoft/jfr/JfrStreamingException.java b/src/main/java/com/microsoft/jfr/JfrStreamingException.java index 7fc0a28..501b573 100644 --- a/src/main/java/com/microsoft/jfr/JfrStreamingException.java +++ b/src/main/java/com/microsoft/jfr/JfrStreamingException.java @@ -24,15 +24,17 @@ import javax.management.JMException; * classes to invoke methods on MBeans. It "wraps" the actual java.lang.Exception thrown. *

javax.management.MalformedObjectNameException
*
The format of the string does not correspond to a valid ObjectName. This cause indicates - * a bug in the com.microsoft.censum.jfr package code.
+ * a bug in the com.microsoft.jfr package code. *
javax.management.openmbean.OpenDataException
*
This exception is thrown when an open type, an open data or an open MBean * metadata info instance could not be constructed because one or more validity constraints - * were not met. This cause indicates a bug in the com.microsoft.censum.jfr package code.
+ * were not met. This cause indicates a bug in the com.microsoft.jfr package code. * */ public class JfrStreamingException extends Exception { + private static final long serialVersionUID = 7394612902107510439L; + JfrStreamingException(String message, JMException cause) { super(message, cause); } diff --git a/src/main/java/com/microsoft/jfr/Recording.java b/src/main/java/com/microsoft/jfr/Recording.java index b14cd63..775d3ec 100644 --- a/src/main/java/com/microsoft/jfr/Recording.java +++ b/src/main/java/com/microsoft/jfr/Recording.java @@ -11,22 +11,20 @@ import java.util.concurrent.atomic.AtomicReference; /** * Provides a means to start, stop and dump recording data. - * To create a {@code Recording}, use one of the {@code newRecording} methods - * in {@link FlightRecorderConnection}. - * @see FlightRecorderConnection#newRecording(RecordingOptions, RecordingConfiguration) + * To create a {@code Recording}, use {@link FlightRecorderConnection#newRecording(RecordingOptions, RecordingConfiguration)}. * @see jdk.jfr.Recording */ public class Recording implements AutoCloseable { /** * A {@code Recording} may be in one of these states. Note that a {@code Recording} is - * no longer usable once it is in the {@code CLOSED} state. Valid state transitions are - * - * NEW -> [RECORDING, STOPPED, CLOSED] - * RECORDING -> [RECORDING, STOPPED, CLOSED] - * STOPPED -> [RECORDING, STOPPED, CLOSED] - * CLOSED -> [CLOSED] - * + * no longer usable once it is in the {@code CLOSED} state. Valid state transitions are: + *
    + *
  • {@code NEW -> [RECORDING, STOPPED, CLOSED]}
    • + *
  • {@code RECORDING -> [RECORDING, STOPPED, CLOSED]}
    • + *
  • {@code STOPPED -> [RECORDING, STOPPED, CLOSED]}
    • + *
  • {@code CLOSED -> [CLOSED]}
    • + *
* Calling a method on {@code Recording} that would cause an invalid transition * will raise an IllegalStateException. */ @@ -107,7 +105,7 @@ public class Recording implements AutoCloseable { * Start a recording. A recording may not be started after it is closed. * @throws IOException A communication problem occurred when talking to the MBean server. * @throws IllegalStateException This {@code Recording} is closed. - * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. See {@link JfrStreamingException}. + * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. * @return The recording id. */ public long start() throws IOException, IllegalStateException, JfrStreamingException { @@ -126,7 +124,7 @@ public class Recording implements AutoCloseable { * Stop a recording. * @throws IOException A communication problem occurred when talking to the MBean server. * @throws IllegalStateException If the {@code Recording} is closed. - * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. See {@link JfrStreamingException}. + * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. */ public void stop() throws IOException, IllegalStateException, JfrStreamingException { // state transitions: RECORDING -> STOPPED, otherwise remain in state @@ -144,7 +142,7 @@ public class Recording implements AutoCloseable { * @param outputFile the system-dependent file name where data is written, not {@code null} * @throws IOException A communication problem occurred when talking to the MBean server. * @throws IllegalStateException If the {@code Recording} has not been started, or has been closed. - * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. See {@link JfrStreamingException}. + * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. * @throws NullPointerException If the {@code outputFile} argument is null. */ public void dump(String outputFile) throws IOException, IllegalStateException, JfrStreamingException { @@ -165,7 +163,7 @@ public class Recording implements AutoCloseable { * @return The cloned recording. * @throws IOException A communication problem occurred when talking to the MBean server. * @throws IllegalStateException If the {@code Recording} has not been started, or has been closed. - * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. See {@link JfrStreamingException}. + * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. */ public Recording clone(boolean stop) throws IOException, JfrStreamingException { State currentState = state.get(); @@ -188,7 +186,7 @@ public class Recording implements AutoCloseable { * @return An {@code InputStream}, or {@code null} if no data is available in the interval. * @throws IOException A communication problem occurred when talking to the MBean server. * @throws IllegalStateException If the {@code Recording} has not been stopped. - * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. See {@link JfrStreamingException}. + * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. * @see JfrStream#getDefaultBlockSize() */ public InputStream getStream(Instant startTime, Instant endTime) @@ -201,15 +199,15 @@ public class Recording implements AutoCloseable { * The stream may contain some data outside the given range. * The {@code blockSize} is used to configure the maximum number of bytes to read * from underlying stream at a time. Setting blockSize to a very high value may result - * in an exception, if the Java Virtual Machine (JVM) deems the value too large to handle. - * Refer to the javadoc for {@code FlightRecorderMXBean#openStream}. + * in an exception if the Java Virtual Machine (JVM) deems the value too large to handle. + * Refer to the javadoc for {@code jdk.management.jfr.FlightRecorderMXBean#openStream}. * @param startTime The start time for the stream, or {@code null} to get data from the start time of the recording. * @param endTime The end time for the stream, or {@code null} to get data until the end of the recording. * @param blockSize The maximum number of bytes to read at a time. * @return An {@code InputStream}, or {@code null} if no data is available in the interval. * @throws IOException A communication problem occurred when talking to the MBean server. * @throws IllegalStateException If the {@code Recording} has not been stopped. - * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. See {@link JfrStreamingException}. + * @throws JfrStreamingException Wraps a {@code javax.management.JMException}. */ public InputStream getStream(Instant startTime, Instant endTime, long blockSize) throws IOException, IllegalStateException, JfrStreamingException { @@ -230,6 +228,7 @@ public class Recording implements AutoCloseable { return state.get(); } + /** {@inheritDoc} */ @Override public void close() throws IOException { // state transitions: any -> CLOSED diff --git a/src/main/java/com/microsoft/jfr/RecordingConfiguration.java b/src/main/java/com/microsoft/jfr/RecordingConfiguration.java index c452728..3a83abb 100644 --- a/src/main/java/com/microsoft/jfr/RecordingConfiguration.java +++ b/src/main/java/com/microsoft/jfr/RecordingConfiguration.java @@ -33,9 +33,8 @@ public class RecordingConfiguration { } /** - * Get the name of a pre-defined configuration. The return value will be {@code null} - * if a pre-defined configuration has not been set. - * @return The name of a pre-defined configuration, or {@code null}. + * Get the name of the configuration. + * @return The name of the configuration. */ public String getName() { return name; diff --git a/src/main/java/com/microsoft/jfr/RecordingOptions.java b/src/main/java/com/microsoft/jfr/RecordingOptions.java index baae8c6..d3c2992 100644 --- a/src/main/java/com/microsoft/jfr/RecordingOptions.java +++ b/src/main/java/com/microsoft/jfr/RecordingOptions.java @@ -11,14 +11,15 @@ import java.util.stream.Collectors; import java.util.stream.Stream; /** - * Configuration is used to configure a flight recording. To create a {@code Configuration}, + * Options for the recording that control maximum recording size, age and duration, + * and whether to store data to disk as it is recorded. To create {@code RecordingOptions}, * use {@link Builder}. - * - * The configuration must be set at the time the {@code Recording} is created via - * {@link FlightRecorderConnection#newRecording(RecordingOptions, RecordingConfiguration)}. A {@code Configuration} - * is immutable which prevents attempts at changing the configuration while a recording - * is in progress. - * + *

+ * The options must be set at the time the {@code Recording} is created via + * {@link FlightRecorderConnection#newRecording(RecordingOptions, RecordingConfiguration)}. + * A {@code RecordingOptions} is immutable which prevents attempts at changing the options + * while a recording is in progress. + *

* A note on the API * It is enticing to want the Builder to take a {@code java.time.Duration} instead of a String for * the {@code maxAge} or {@code duration} API, or have the {@code maxAge} API take a long, or pass @@ -37,7 +38,7 @@ import java.util.stream.Stream; */ public class RecordingOptions { - /* Default values of some configuration elements. */ + /* Default values of some options. */ private static final String EMPTY_STRING = ""; private static final String NO_LIMIT = "0"; @@ -236,9 +237,9 @@ public class RecordingOptions { } /** - * Construct a {@code Configuration} from the options that were set on this builder. + * Construct a {@code RecordingOptions} from the options that were set on this builder. * The {@code Builder} state is not reset by calling this method. - * @return A {@code Configuration}, never {@code null}. + * @return A {@code RecordingOptions}, never {@code null}. */ public RecordingOptions build() { return new RecordingOptions(this); @@ -247,8 +248,8 @@ public class RecordingOptions { } /** - * Constructor is private. Only the Builder can construct a Configuration. - * @param builder The builder that was used to parameterize the configuration + * Constructor is private. Only the Builder can construct a RecordingOptions. + * @param builder The builder that was used to parameterize the options. */ private RecordingOptions(Builder builder) { @@ -348,7 +349,7 @@ public class RecordingOptions { return recordingOptions; } - // The configuration options. The keys are names of recording options + // The recording options. The keys are names of recording options // according to FlightRecorderMXBean. The value is a valid value for // the option. Options that take on default values should be absent. private final Map recordingOptions;