8173354: javadoc warning notice for types in Incubator Modules
Reviewed-by: erikj, michaelm
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/make/src/classes/build/tools/taglet/Incubating.java Wed Jan 25 14:10:03 2017 +0000
@@ -0,0 +1,71 @@
+/*
+ * Copyright (c) 2017, 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 build.tools.taglet;
+
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Set;
+import com.sun.source.doctree.DocTree;
+import jdk.javadoc.doclet.taglet.Taglet;
+import static jdk.javadoc.doclet.taglet.Taglet.Location.*;
+
+/**
+ * An inline tag to conveniently insert a standard Incubating warning. For
+ * use by members in Incubator Modules.
+ */
+public class Incubating implements Taglet {
+
+ /** Returns the set of locations in which a taglet may be used. */
+ @Override
+ public Set<Location> getAllowedLocations() {
+ return EnumSet.of(OVERVIEW, MODULE, PACKAGE, TYPE);
+ }
+
+ @Override
+ public boolean isInlineTag() {
+ return true;
+ }
+
+ @Override
+ public String getName() {
+ return "Incubating";
+ }
+
+ private static final String MESSAGE =
+ "<BR><b><a href=\"http://openjdk.java.net/jeps/11\">Incubating Feature.</a>"
+ + " Will be removed in a future release.</b>";
+
+ @Override
+ public String toString(DocTree tag) {
+ return MESSAGE;
+ }
+
+ @Override
+ public String toString(List<? extends DocTree> tags) {
+ return MESSAGE;
+ }
+}
+
--- a/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpClient.java Wed Jan 25 03:47:40 2017 -0800
+++ b/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpClient.java Wed Jan 25 14:10:03 2017 +0000
@@ -40,6 +40,7 @@
/**
* A container for configuration information common to multiple {@link
* HttpRequest}s. All requests are sent through a {@code HttpClient}.
+ * {@Incubating}
*
* <p> {@code HttpClient}s are immutable and created from a builder returned
* from {@link HttpClient#newBuilder()}. Request builders are created by calling
@@ -76,7 +77,8 @@
/**
* A builder of immutable {@link HttpClient}s. {@code HttpClient.Builder}s
- * are created by calling {@link HttpClient#newBuilder() }
+ * are created by calling {@link HttpClient#newBuilder()}.
+ * {@Incubating}
*
* <p> Each of the setter methods in this class modifies the state of the
* builder and returns <i>this</i> (ie. the same instance). The methods are
@@ -283,6 +285,7 @@
/**
* The HTTP protocol version.
+ * {@Incubating}
*
* @since 9
*/
@@ -300,10 +303,12 @@
}
/**
- * Defines automatic redirection policy. This is checked whenever a {@code 3XX}
- * response code is received. If redirection does not happen automatically
- * then the response is returned to the user, where it can be handled
- * manually.
+ * Defines automatic redirection policy.
+ * {@Incubating}
+ *
+ * <p> This is checked whenever a {@code 3XX} response code is received. If
+ * redirection does not happen automatically then the response is returned
+ * to the user, where it can be handled manually.
*
* <p> {@code Redirect} policy is set via the {@link
* HttpClient.Builder#followRedirects(HttpClient.Redirect)} method.
--- a/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpHeaders.java Wed Jan 25 03:47:40 2017 -0800
+++ b/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpHeaders.java Wed Jan 25 14:10:03 2017 +0000
@@ -32,6 +32,7 @@
/**
* A read-only view of a set of HTTP headers.
+ * {@Incubating}
*
* @since 9
*/
--- a/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpRequest.java Wed Jan 25 03:47:40 2017 -0800
+++ b/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpRequest.java Wed Jan 25 14:10:03 2017 +0000
@@ -39,10 +39,13 @@
import java.util.function.Supplier;
/**
- * Represents one HTTP request which can be sent to a server. {@code
- * HttpRequest}s are built from {@code HttpRequest} {@link HttpRequest.Builder
- * builder}s. {@code HttpRequest} builders are obtained
- * by calling {@link HttpRequest#newBuilder(java.net.URI) HttpRequest.newBuilder}.
+ * Represents one HTTP request which can be sent to a server.
+ * {@Incubating }
+ *
+ * <p> {@code HttpRequest}s are built from {@code HttpRequest}
+ * {@link HttpRequest.Builder builder}s. {@code HttpRequest} builders are
+ * obtained by calling {@link HttpRequest#newBuilder(java.net.URI)
+ * HttpRequest.newBuilder}.
* A request's {@link java.net.URI}, headers and body can be set. Request bodies
* are provided through a {@link BodyProcessor} object supplied to the
* {@link Builder#DELETE(jdk.incubator.http.HttpRequest.BodyProcessor) DELETE},
@@ -250,9 +253,11 @@
protected HttpRequest() {}
/**
- * A builder of {@link HttpRequest}s. {@code HttpRequest.Builder}s are
- * created by calling {@link HttpRequest#newBuilder(URI)} or {@link
- * HttpRequest#newBuilder()}.
+ * A builder of {@link HttpRequest}s.
+ * {@Incubating}
+ *
+ * <p> {@code HttpRequest.Builder}s are created by calling {@link
+ * HttpRequest#newBuilder(URI)} or {@link HttpRequest#newBuilder()}.
*
* <p> Each of the setter methods in this class modifies the state of the
* builder and returns <i>this</i> (ie. the same instance). The methods are
@@ -521,8 +526,10 @@
/**
* A processor which converts high level Java objects into flows of
* {@link java.nio.ByteBuffer}s suitable for sending as request bodies.
- * {@code BodyProcessor}s implement {@link Flow.Publisher} which means they act as a
- * publisher of byte buffers.
+ * {@Incubating}
+ * <p>
+ * {@code BodyProcessor}s implement {@link Flow.Publisher} which means they
+ * act as a publisher of byte buffers.
* <p>
* The HTTP client implementation subscribes to the processor in
* order to receive the flow of outgoing data buffers. The normal semantics
--- a/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpResponse.java Wed Jan 25 03:47:40 2017 -0800
+++ b/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpResponse.java Wed Jan 25 14:10:03 2017 +0000
@@ -47,12 +47,15 @@
import javax.net.ssl.SSLParameters;
/**
- * Represents a response to a {@link HttpRequest}. A {@code HttpResponse} is
- * available when the response status code and headers have been received, and
- * typically after the response body has also been received. This depends on
- * the response body handler provided when sending the request. In all cases,
- * the response body handler is invoked before the body is read. This gives
- * applications an opportunity to decide how to handle the body.
+ * Represents a response to a {@link HttpRequest}.
+ * {@Incubating}
+ *
+ * <p>A {@code HttpResponse} is available when the response status code and
+ * headers have been received, and typically after the response body has also
+ * been received. This depends on the response body handler provided when
+ * sending the request. In all cases, the response body handler is invoked
+ * before the body is read. This gives applications an opportunity to decide
+ * how to handle the body.
*
* <p> Methods are provided in this class for accessing the response headers,
* and response body.
@@ -157,12 +160,15 @@
public abstract HttpClient.Version version();
/**
- * A handler for response bodies. This is a function that takes two
- * parameters: the response status code, and the response headers,
- * and which returns a {@link BodyProcessor}. The function is always called
- * just before the response body is read. Its implementation may examine the
- * status code or headers and must decide, whether to accept the response
- * body or discard it, and if accepting it, exactly how to handle it.
+ * A handler for response bodies.
+ * {@Incubating}
+ * <p>
+ * This is a function that takes two parameters: the response status code,
+ * and the response headers, and which returns a {@link BodyProcessor}.
+ * The function is always called just before the response body is read. Its
+ * implementation may examine the status code or headers and must decide,
+ * whether to accept the response body or discard it, and if accepting it,
+ * exactly how to handle it.
* <p>
* Some pre-defined implementations which do not utilize the status code
* or headers (meaning the body is always accepted) are defined:
@@ -409,10 +415,13 @@
}
/**
- * A processor for response bodies. The object acts as a
- * {@link Flow.Subscriber}<{@link ByteBuffer}> to the HTTP client implementation
- * which publishes ByteBuffers containing the response body. The processor
- * converts the incoming buffers of data to some user-defined object type {@code T}.
+ * A processor for response bodies.
+ * {@Incubating}
+ * <p>
+ * The object acts as a {@link Flow.Subscriber}<{@link ByteBuffer}> to
+ * the HTTP client implementation which publishes ByteBuffers containing the
+ * response body. The processor converts the incoming buffers of data to
+ * some user-defined object type {@code T}.
* <p>
* The {@link #getBody()} method returns a {@link CompletionStage}{@code <T>}
* that provides the response body object. The {@code CompletionStage} must
@@ -539,12 +548,14 @@
}
/**
- * A response processor for a HTTP/2 multi response. A multi response
- * comprises a main response, and zero or more additional responses. Each
- * additional response is sent by the server in response to requests that
- * the server also generates. Additional responses are typically resources
- * that the server expects the client will need which are related to the
- * initial request.
+ * A response processor for a HTTP/2 multi response.
+ * {@Incubating}
+ * <p>
+ * A multi response comprises a main response, and zero or more additional
+ * responses. Each additional response is sent by the server in response to
+ * requests that the server also generates. Additional responses are
+ * typically resources that the server expects the client will need which
+ * are related to the initial request.
* <p>
* Note. Instead of implementing this interface, applications should consider
* first using the mechanism (built on this interface) provided by
--- a/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpTimeoutException.java Wed Jan 25 03:47:40 2017 -0800
+++ b/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpTimeoutException.java Wed Jan 25 14:10:03 2017 +0000
@@ -29,6 +29,7 @@
/**
* Thrown when a response is not received within a specified time period.
+ * {@Incubating}
*/
public class HttpTimeoutException extends IOException {
--- a/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/MultiMapResult.java Wed Jan 25 03:47:40 2017 -0800
+++ b/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/MultiMapResult.java Wed Jan 25 14:10:03 2017 +0000
@@ -32,6 +32,8 @@
/**
* A {@link java.util.Map} containing the result of a HTTP/2 request and multi-response.
+ * {@Incubating}
+ * <p>
* This is one possible implementation of the aggregate result type {@code <U>} returned
* from {@link HttpClient#sendAsync(HttpRequest,MultiProcessor) }.
* The map is indexed by {@link HttpRequest} and each value is a
--- a/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/WebSocket.java Wed Jan 25 03:47:40 2017 -0800
+++ b/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/WebSocket.java Wed Jan 25 14:10:03 2017 +0000
@@ -35,6 +35,7 @@
/**
* A WebSocket client conforming to RFC 6455.
+ * {@Incubating}
*
* <p> A {@code WebSocket} provides full-duplex communication over a TCP
* connection.
@@ -105,6 +106,7 @@
/**
* A builder for creating {@code WebSocket} instances.
+ * {@Incubating}
*
* <p> To build a {@code WebSocket}, {@linkplain HttpClient#newWebSocketBuilder(
* URI, Listener) create} a builder, configure it as required by
@@ -219,6 +221,7 @@
/**
* A listener for events and messages on a {@code WebSocket}.
+ * {@Incubating}
*
* <p> Each method of {@code Listener} corresponds to a type of event or a
* type of message. The {@code WebSocket} argument of the method is the
@@ -570,6 +573,7 @@
/**
* A marker used by {@link WebSocket.Listener} in cases where a partial
* message may be received.
+ * {@Incubating}
*
* @see Listener#onText(WebSocket, CharSequence, MessagePart)
* @see Listener#onBinary(WebSocket, ByteBuffer, MessagePart)
--- a/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/WebSocketHandshakeException.java Wed Jan 25 03:47:40 2017 -0800
+++ b/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/WebSocketHandshakeException.java Wed Jan 25 14:10:03 2017 +0000
@@ -29,6 +29,7 @@
/**
* An exception used to signal the opening handshake failed.
+ * {@Incubating}
*
* @since 9
*/
--- a/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/package-info.java Wed Jan 25 03:47:40 2017 -0800
+++ b/jdk/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/package-info.java Wed Jan 25 14:10:03 2017 +0000
@@ -25,8 +25,9 @@
/**
* <h2>High level HTTP and WebSocket API</h2>
+ * {@Incubating}
*
- * This provides a high-level client interfaces to HTTP (versions 1.1 and 2) and
+ * <p> Provides high-level client interfaces to HTTP (versions 1.1 and 2) and
* WebSocket. The main types defined are:
*
* <ul>
--- a/jdk/src/jdk.incubator.httpclient/share/classes/module-info.java Wed Jan 25 03:47:40 2017 -0800
+++ b/jdk/src/jdk.incubator.httpclient/share/classes/module-info.java Wed Jan 25 14:10:03 2017 +0000
@@ -25,6 +25,7 @@
/**
* Defines the high-level HTTP and WebSocket API.
+ * {@Incubating}
*/
module jdk.incubator.httpclient {
requires java.base;