8253474: Javadoc clean up in HttpsExchange, HttpsParameters, and HttpsServer

Reviewed-by: dfuchs, michaelm

Author: pconcannon

src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpsExchange.java

@@ -25,28 +25,27 @@
 
 package com.sun.net.httpserver;
 
-import java.io.*;
-import java.nio.*;
-import java.nio.channels.*;
-import java.net.*;
-import javax.net.ssl.*;
-import java.util.*;
+import javax.net.ssl.SSLSession;
 
 /**
- * This class encapsulates a HTTPS request received and a
- * response to be generated in one exchange and defines
- * the extensions to HttpExchange that are specific to the HTTPS protocol.
+ * This class encapsulates a HTTPS request received and a response to be
+ * generated in one exchange and defines the extensions to {@link HttpExchange}
+ * that are specific to the HTTPS protocol.
+ *
  * @since 1.6
  */
 
 public abstract class HttpsExchange extends HttpExchange {
 
-    protected HttpsExchange () {
-    }
+    /**
+     * Constructor for subclasses to call.
+     */
+    protected HttpsExchange() {}
 
     /**
-     * Get the SSLSession for this exchange.
-     * @return the SSLSession
+     * Get the {@link SSLSession} for this exchange.
+     *
+     * @return the {@code SSLSession}
      */
-    public abstract SSLSession getSSLSession ();
+    public abstract SSLSession getSSLSession();
 }

src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpsParameters.java

@@ -26,29 +26,23 @@
 package com.sun.net.httpserver;
 
 import java.net.InetSocketAddress;
-
-//BEGIN_TIGER_EXCLUDE
 import javax.net.ssl.SSLParameters;
-//END_TIGER_EXCLUDE
 
 /**
- * Represents the set of parameters for each https
- * connection negotiated with clients. One of these
- * is created and passed to
- * {@link HttpsConfigurator#configure(HttpsParameters)}
- * for every incoming https connection,
- * in order to determine the parameters to use.
- * <p>
- * The underlying SSL parameters may be established either
- * via the set/get methods of this class, or else via
- * a {@link javax.net.ssl.SSLParameters} object. SSLParameters
- * is the preferred method, because in the future,
- * additional configuration capabilities may be added to that class, and
- * it is easier to determine the set of supported parameters and their
- * default values with SSLParameters. Also, if an SSLParameters object is
- * provided via
- * {@link #setSSLParameters(SSLParameters)} then those parameter settings
- * are used, and any settings made in this object are ignored.
+ * Represents the set of parameters for each https connection negotiated with
+ * clients. One of these is created and passed to
+ * {@link HttpsConfigurator#configure(HttpsParameters)} for every incoming https
+ * connection, in order to determine the parameters to use.
+ *
+ * <p> The underlying SSL parameters may be established either via the set/get
+ * methods of this class, or else via a {@link javax.net.ssl.SSLParameters}
+ * object. {@code SSLParameters} is the preferred method, because in the future,
+ * additional configuration capabilities may be added to that class, and it is
+ * easier to determine the set of supported parameters and their default values
+ * with SSLParameters. Also, if an {@code SSLParameters} object is provided via
+ * {@link #setSSLParameters(SSLParameters)} then those parameter settings are
+ * used, and any settings made in this object are ignored.
+ *
  * @since 1.6
  */
 public abstract class HttpsParameters {
@@ -64,41 +58,39 @@ public abstract class HttpsParameters {
     protected HttpsParameters() {}
 
     /**
-     * Returns the HttpsConfigurator for this HttpsParameters.
+     * Returns the {@link HttpsConfigurator} for this {@code HttpsParameters}.
      *
-     * @return HttpsConfigurator for this instance of HttpsParameters
+     * @return {@code HttpsConfigurator} for this instance of {@code HttpsParameters}
      */
     public abstract HttpsConfigurator getHttpsConfigurator();
 
     /**
-     * Returns the address of the remote client initiating the
-     * connection.
+     * Returns the address of the remote client initiating the connection.
      *
-     * @return Address of the remote client initiating the connection
+     * @return address of the remote client initiating the connection
      */
     public abstract InetSocketAddress getClientAddress();
 
-//BEGIN_TIGER_EXCLUDE
     /**
-     * Sets the SSLParameters to use for this HttpsParameters.
-     * The parameters must be supported by the SSLContext contained
-     * by the HttpsConfigurator associated with this HttpsParameters.
+     * Sets the {@link SSLParameters} to use for this {@code HttpsParameters}.
+     * The parameters must be supported by the {@link SSLContext} contained
+     * by the {@link HttpsConfigurator} associated with this {@code HttpsParameters}.
      * If no parameters are set, then the default behavior is to use
-     * the default parameters from the associated SSLContext.
-     * @param params the SSLParameters to set. If <code>null</code>
-     * then the existing parameters (if any) remain unchanged.
-     * @throws IllegalArgumentException if any of the parameters are
-     *   invalid or unsupported.
+     * the default parameters from the associated {@link SSLContext}.
+     *
+     * @param params the {@code SSLParameters} to set. If {@code null} then the
+     *               existing parameters (if any) remain unchanged
+     * @throws IllegalArgumentException if any of the parameters are invalid or
+     * unsupported
      */
-    public abstract void setSSLParameters (SSLParameters params);
-//END_TIGER_EXCLUDE
+    public abstract void setSSLParameters(SSLParameters params);
 
     /**
-     * Returns a copy of the array of ciphersuites or null if none
+     * Returns a copy of the array of ciphersuites or {@code null} if none
      * have been set.
      *
-     * @return a copy of the array of ciphersuites or null if none
-     * have been set.
+     * @return a copy of the array of ciphersuites or {@code null} if none have
+     * been set
      */
     public String[] getCipherSuites() {
         return cipherSuites != null ? cipherSuites.clone() : null;
@@ -107,18 +99,18 @@ public String[] getCipherSuites() {
     /**
      * Sets the array of ciphersuites.
      *
-     * @param cipherSuites the array of ciphersuites (or null)
+     * @param cipherSuites the array of ciphersuites (or {@code null})
      */
     public void setCipherSuites(String[] cipherSuites) {
         this.cipherSuites = cipherSuites != null ? cipherSuites.clone() : null;
     }
 
     /**
-     * Returns a copy of the array of protocols or null if none
-     * have been set.
+     * Returns a copy of the array of protocols or {@code null} if none have been
+     * set.
      *
-     * @return a copy of the array of protocols or null if none
-     * have been set.
+     * @return a copy of the array of protocols or {@code null} if none have been
+     * set
      */
     public String[] getProtocols() {
         return protocols != null ? protocols.clone() : null;
@@ -127,7 +119,7 @@ public String[] getProtocols() {
     /**
      * Sets the array of protocols.
      *
-     * @param protocols the array of protocols (or null)
+     * @param protocols the array of protocols (or {@code null})
      */
     public void setProtocols(String[] protocols) {
         this.protocols = protocols != null ? protocols.clone() : null;
@@ -136,15 +128,15 @@ public void setProtocols(String[] protocols) {
     /**
      * Returns whether client authentication should be requested.
      *
-     * @return whether client authentication should be requested.
+     * @return whether client authentication should be requested
      */
     public boolean getWantClientAuth() {
         return wantClientAuth;
     }
 
     /**
-     * Sets whether client authentication should be requested. Calling
-     * this method clears the <code>needClientAuth</code> flag.
+     * Sets whether client authentication should be requested. Calling this
+     * method clears the {@code needClientAuth} flag.
      *
      * @param wantClientAuth whether client authentication should be requested
      */
@@ -155,15 +147,15 @@ public void setWantClientAuth(boolean wantClientAuth) {
     /**
      * Returns whether client authentication should be required.
      *
-     * @return whether client authentication should be required.
+     * @return whether client authentication should be required
      */
     public boolean getNeedClientAuth() {
         return needClientAuth;
     }
 
     /**
-     * Sets whether client authentication should be required. Calling
-     * this method clears the <code>wantClientAuth</code> flag.
+     * Sets whether client authentication should be required. Calling this method
+     * clears the {@code wantClientAuth} flag.
      *
      * @param needClientAuth whether client authentication should be required
      */

src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpsServer.java

@@ -25,80 +25,84 @@
 
 package com.sun.net.httpserver;
 
-import java.net.*;
-import java.io.*;
-import java.nio.*;
-import java.security.*;
-import java.nio.channels.*;
-import java.util.*;
-import java.util.concurrent.*;
-import javax.net.ssl.*;
-import com.sun.net.httpserver.spi.*;
+import java.io.IOException;
+import java.net.BindException;
+import java.net.InetSocketAddress;
+import com.sun.net.httpserver.spi.HttpServerProvider;
 
 /**
- * This class is an extension of {@link HttpServer} which provides
- * support for HTTPS. <p>
- * A HttpsServer must have an associated {@link HttpsConfigurator} object
+ * This class is an extension of {@link HttpServer} which provides support for
+ * HTTPS.
+ *
+ * <p>A {@code HttpsServer} must have an associated {@link HttpsConfigurator} object
  * which is used to establish the SSL configuration for the SSL connections.
- * <p>
- * All other configuration is the same as for HttpServer.
+ *
+ * <p>All other configuration is the same as for {@code HttpServer}.
+ *
  * @since 1.6
  */
 
 public abstract class HttpsServer extends HttpServer {
 
     /**
+     * Constructor for subclasses to call.
      */
-    protected HttpsServer () {
+    protected HttpsServer() {
     }
 
     /**
-     * creates a HttpsServer instance which is initially not bound to any local address/port.
-     * The HttpsServer is acquired from the currently installed {@link HttpServerProvider}
-     * The server must be bound using {@link #bind(InetSocketAddress,int)} before it can be used.
-     * The server must also have a HttpsConfigurator established with {@link #setHttpsConfigurator(HttpsConfigurator)}
-     * @throws IOException
+     * Creates a {@code HttpsServer} instance which is initially not bound to any
+     * local address/port. The {@code HttpsServer} is acquired from the currently
+     * installed {@link HttpServerProvider}. The server must be bound using
+     * {@link #bind(InetSocketAddress,int)} before it can be used. The server
+     * must also have a {@code HttpsConfigurator} established with
+     * {@link #setHttpsConfigurator(HttpsConfigurator)}.
+     *
+     * @throws IOException if an I/O error occurs
      */
-    public static HttpsServer create () throws IOException {
-        return create (null, 0);
+    public static HttpsServer create() throws IOException {
+        return create(null, 0);
     }
 
     /**
-     * Create a <code>HttpsServer</code> instance which will bind to the
-     * specified {@link java.net.InetSocketAddress} (IP address and port number)
+     * Create a {@code HttpsServer} instance which will bind to the specified
+     * {@link java.net.InetSocketAddress} (IP address and port number).
      *
      * A maximum backlog can also be specified. This is the maximum number of
-     * queued incoming connections to allow on the listening socket.
-     * Queued TCP connections exceeding this limit may be rejected by the TCP implementation.
-     * The HttpsServer is acquired from the currently installed {@link HttpServerProvider}
-     * The server must have a HttpsConfigurator established with {@link #setHttpsConfigurator(HttpsConfigurator)}
+     * queued incoming connections to allow on the listening socket. Queued TCP
+     * connections exceeding this limit may be rejected by the TCP implementation.
+     * The {@code HttpsServer} is acquired from the currently installed
+     * {@link HttpServerProvider}. The server must have a {@code HttpsConfigurator}
+     * established with {@link #setHttpsConfigurator(HttpsConfigurator)}.
      *
-     * @param addr the address to listen on, if <code>null</code> then bind() must be called
-     *  to set the address
-     * @param backlog the socket backlog. If this value is less than or equal to zero,
-     *          then a system default value is used.
+     * @param addr the address to listen on, if {@code null} then
+     *             {@link #bind(InetSocketAddress,int)} must be called to set
+     *             the address
+     * @param backlog the socket backlog. If this value is less than or equal to
+     *               zero, then a system default value is used.
      * @throws BindException if the server cannot bind to the requested address,
-     *          or if the server is already bound.
-     * @throws IOException
+     *          or if the server is already bound
+     * @throws IOException if an I/O error occurs
      */
 
-    public static HttpsServer create (
-        InetSocketAddress addr, int backlog
-    ) throws IOException {
+    public static HttpsServer create(InetSocketAddress addr, int backlog) throws IOException {
         HttpServerProvider provider = HttpServerProvider.provider();
-        return provider.createHttpsServer (addr, backlog);
+        return provider.createHttpsServer(addr, backlog);
     }
 
     /**
      * Sets this server's {@link HttpsConfigurator} object.
-     * @param config the HttpsConfigurator to set
-     * @throws NullPointerException if config is null.
+     *
+     * @param config the {@code HttpsConfigurator} to set
+     * @throws NullPointerException if config is {@code null}
      */
-    public abstract void setHttpsConfigurator (HttpsConfigurator config) ;
+    public abstract void setHttpsConfigurator(HttpsConfigurator config);
 
     /**
      * Gets this server's {@link HttpsConfigurator} object, if it has been set.
-     * @return the HttpsConfigurator for this server, or <code>null</code> if not set.
+     *
+     * @return the {@code HttpsConfigurator} for this server, or {@code null} if
+     * not set
      */
-    public abstract HttpsConfigurator getHttpsConfigurator ();
+    public abstract HttpsConfigurator getHttpsConfigurator();
 }