Fix javadoc and pom for publish to maven

This commit is contained in:
David Grieve 2021-02-23 17:14:55 -05:00
Родитель 5810d724cc
Коммит 606c178be7
8 изменённых файлов: 206 добавлений и 50 удалений

8
.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/

149
pom.xml
Просмотреть файл

@ -1,12 +1,81 @@
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<?xml version="1.0"?>
<!--
Copyright (c) Microsoft Corporation. All rights reserved.
Licensed under the MIT License. See LICENSE in the project root for
license information.
-->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.microsoft.censum</groupId>
<groupId>com.microsoft.jfr</groupId>
<artifactId>jfr-streaming</artifactId>
<version>1.0.0-SNAPSHOT</version>
<version>1.0.0</version>
<licenses>
<license>
<name>MIT License</name>
<url>http://opensource.org/licenses/MIT</url>
<distribution>repo</distribution>
</license>
</licenses>
<scm>
<connection>scm:git:git@github.com:Microsoft/jfr-streaming.git</connection>
<developerConnection>scm:git:git@github.com:Microsoft/jfr-streaming.git</developerConnection>
<url>https://github.com/Microsoft/jfr-streaming.git</url>
</scm>
<developers>
<developer>
<id>microsoft</id>
<name>Microsoft</name>
</developer>
</developers>
<issueManagement>
<system>GitHub</system>
<url>https://github.com/microsoft/jfr-streaming/issues</url>
</issueManagement>
<distributionManagement>
<snapshotRepository>
<id>ossrh</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
</snapshotRepository>
<repository>
<id>ossrh</id>
<url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
</repository>
</distributionManagement>
<profiles>
<profile>
<id>release</id>
<activation>
<property>
<name>release</name>
</property>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.sonatype.plugins</groupId>
<artifactId>nexus-staging-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</profile>
</profiles>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
<maven.compiler.testSource>8</maven.compiler.testSource>
<maven.compiler.testTarget>8</maven.compiler.testTarget>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
@ -20,6 +89,19 @@
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>${maven.compiler.source}</source>
<testSource>${maven.compiler.testSource}</testSource>
<target>${maven.compiler.target}</target>
<testTarget>${maven.compiler.testTarget}</testTarget>
<showDeprecation>true</showDeprecation>
<showWarnings>true</showWarnings>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
@ -30,6 +112,67 @@
</archive>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>3.2.1</version>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar-no-fork</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.2.0</version>
<configuration>
<!-- address https://bugs.openjdk.java.net/browse/JDK-8212233 -->
<source>8</source>
<detectJavaApiLink>false</detectJavaApiLink>
</configuration>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.0.0-M4</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<version>1.6</version>
<executions>
<execution>
<id>sign-artifacts</id>
<phase>deploy</phase>
<goals>
<goal>sign</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.sonatype.plugins</groupId>
<artifactId>nexus-staging-maven-plugin</artifactId>
<version>1.6.8</version>
<extensions>true</extensions>
<configuration>
<serverId>ossrh</serverId>
<nexusUrl>https://oss.sonatype.org/</nexusUrl>
<autoReleaseAfterClose>false</autoReleaseAfterClose>
</configuration>
</plugin>
</plugins>
</build>

Просмотреть файл

@ -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.
*
* <p>
* 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.
*
* <p>
* 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 {

Просмотреть файл

@ -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; }

Просмотреть файл

@ -24,15 +24,17 @@ import javax.management.JMException;
* classes to invoke methods on MBeans. It "wraps" the actual java.lang.Exception thrown.</dd>
* <dt><em>javax.management.MalformedObjectNameException</em></dt>
* <dd>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.</dd>
* a bug in the com.microsoft.jfr package code.</dd>
* <dt><em>javax.management.openmbean.OpenDataException</em></dt>
* <dd>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.</dd>
* were not met. This cause indicates a bug in the com.microsoft.jfr package code.</dd>
* </dl>
*/
public class JfrStreamingException extends Exception {
private static final long serialVersionUID = 7394612902107510439L;
JfrStreamingException(String message, JMException cause) {
super(message, cause);
}

Просмотреть файл

@ -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 <a href="https://docs.oracle.com/en/java/javase/11/docs/api/jdk.jfr/jdk/jfr/Recording.html">jdk.jfr.Recording</a>
*/
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
* <code>
* NEW -> [RECORDING, STOPPED, CLOSED]
* RECORDING -> [RECORDING, STOPPED, CLOSED]
* STOPPED -> [RECORDING, STOPPED, CLOSED]
* CLOSED -> [CLOSED]
* </code>
* no longer usable once it is in the {@code CLOSED} state. Valid state transitions are:
* <ul>
* <li>{@code NEW -> [RECORDING, STOPPED, CLOSED]}</li>
* <li>{@code RECORDING -> [RECORDING, STOPPED, CLOSED]}</li>
* <li>{@code STOPPED -> [RECORDING, STOPPED, CLOSED]}</li>
* <li>{@code CLOSED -> [CLOSED]}</li>
* </ul>
* 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

Просмотреть файл

@ -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;

Просмотреть файл

@ -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.
*
* <p>
* 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.
* <p>
* <b>A note on the API</b>
* 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<String,String> recordingOptions;