changeset 16569:e8dab4820716

8173354: javadoc warning notice for types in Incubator Modules Reviewed-by: erikj, michaelm
author chegar
date Wed, 25 Jan 2017 14:10:03 +0000
parents 4a36e73e0e18
children c7d93950979d
files make/src/classes/build/tools/taglet/Incubating.java src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpClient.java src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpHeaders.java src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpRequest.java src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpResponse.java src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpTimeoutException.java src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/MultiMapResult.java src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/WebSocket.java src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/WebSocketHandshakeException.java src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/package-info.java src/jdk.incubator.httpclient/share/classes/module-info.java
diffstat 11 files changed, 142 insertions(+), 37 deletions(-) [+]
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/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/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpClient.java	Wed Jan 25 03:47:40 2017 -0800
+++ b/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/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpHeaders.java	Wed Jan 25 03:47:40 2017 -0800
+++ b/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/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpRequest.java	Wed Jan 25 03:47:40 2017 -0800
+++ b/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/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpResponse.java	Wed Jan 25 03:47:40 2017 -0800
+++ b/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}&lt;{@link ByteBuffer}&gt; 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}&lt;{@link ByteBuffer}&gt; 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/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpTimeoutException.java	Wed Jan 25 03:47:40 2017 -0800
+++ b/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/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/MultiMapResult.java	Wed Jan 25 03:47:40 2017 -0800
+++ b/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/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/WebSocket.java	Wed Jan 25 03:47:40 2017 -0800
+++ b/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&nbsp;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/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/WebSocketHandshakeException.java	Wed Jan 25 03:47:40 2017 -0800
+++ b/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/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/package-info.java	Wed Jan 25 03:47:40 2017 -0800
+++ b/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/src/jdk.incubator.httpclient/share/classes/module-info.java	Wed Jan 25 03:47:40 2017 -0800
+++ b/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;