8253473: Javadoc clean up in HttpHandler, HttpPrincipal, HttpContext, and HttpsConfigurator

Reviewed-by: dfuchs

Author: pconcannon

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

@@ -28,89 +28,98 @@
 import java.util.Map;
 
 /**
- * HttpContext represents a mapping between the root URI path of an application
- * to a {@link HttpHandler} which is invoked to handle requests destined
- * for that path on the associated HttpServer or HttpsServer.
- * <p>
- * HttpContext instances are created by the create methods in HttpServer
- * and HttpsServer
- * <p>
- * A chain of {@link Filter} objects can be added to a HttpContext. All exchanges processed by the
- * context can be pre- and post-processed by each Filter in the chain.
+ * {@code HttpContext} represents a mapping between the root {@link java.net.URI}
+ * path of an application to a {@link HttpHandler} which is invoked to handle
+ * requests destined for that path on the associated {@link HttpServer} or
+ * {@link HttpsServer}.
+ *
+ * <p> {@code HttpContext} instances are created by the create methods in
+ * {@code HttpServer} and {@code HttpsServer}.
+ *
+ * <p> A chain of {@link Filter} objects can be added to a {@code HttpContext}.
+ * All exchanges processed by the context can be pre- and post-processed by each
+ * {@code Filter} in the chain.
+ *
  * @since 1.6
  */
 public abstract class HttpContext {
 
     /**
      * Constructor for subclasses to call.
      */
-    protected HttpContext () {
+    protected HttpContext() {
     }
 
     /**
-     * returns the handler for this context
-     * @return the HttpHandler for this context
+     * Returns the handler for this context.
+     *
+     * @return the {@code HttpHandler} for this context
      */
-    public abstract HttpHandler getHandler () ;
+    public abstract HttpHandler getHandler();
 
     /**
      * Sets the handler for this context, if not already set.
-     * @param h the handler to set for this context
-     * @throws IllegalArgumentException if this context's handler is already set.
-     * @throws NullPointerException if handler is <code>null</code>
+     *
+     * @param handler the handler to set for this context
+     * @throws IllegalArgumentException if the context for this handler is already set.
+     * @throws NullPointerException if handler is {@code null}
      */
-    public abstract void setHandler (HttpHandler h) ;
+    public abstract void setHandler(HttpHandler handler);
 
     /**
-     * returns the path this context was created with
-     * @return this context's path
+     * Returns the path this context was created with.
+     *
+     * @return the context of this path
      */
-    public abstract String getPath() ;
+    public abstract String getPath();
 
     /**
-     * returns the server this context was created with
-     * @return this context's server
+     * Returns the server this context was created with.
+     *
+     * @return the context of this server
      */
-    public abstract HttpServer getServer () ;
+    public abstract HttpServer getServer();
 
     /**
-     * returns a mutable Map, which can be used to pass
-     * configuration and other data to Filter modules
-     * and to the context's exchange handler.
-     * <p>
-     * Every attribute stored in this Map will be visible to
-     * every HttpExchange processed by this context
+     * Returns a mutable {@link Map}, which can be used to pass configuration
+     * and other data to {@link Filter} modules and to the context's exchange
+     * handler.
+     *
+     * <p> Every attribute stored in this {@code Map} will be visible to every
+     * {@code HttpExchange} processed by this context.
      *
-     * @return a map containing the attributes of this context
+     * @return a {@code Map} containing the attributes of this context
      */
     public abstract Map<String,Object> getAttributes() ;
 
     /**
-     * returns this context's list of Filters. This is the
-     * actual list used by the server when dispatching requests
-     * so modifications to this list immediately affect the
-     * the handling of exchanges.
+     * Returns this context's {@link List} of {@linkplain Filter filters}. This
+     * is the actual list used by the server when dispatching requests so
+     * modifications to this list immediately affect the the handling of exchanges.
+     *
+     * @return a {@link List} containing the filters of this context
      */
     public abstract List<Filter> getFilters();
 
     /**
-     * Sets the Authenticator for this HttpContext. Once an authenticator
-     * is establised on a context, all client requests must be
-     * authenticated, and the given object will be invoked to validate each
-     * request. Each call to this method replaces any previous value set.
-     * @param auth the authenticator to set. If <code>null</code> then any
-     *         previously set authenticator is removed,
-     *         and client authentication will no longer be required.
-     * @return the previous Authenticator, if any set, or <code>null</code>
-     *         otherwise.
+     * Sets the {@link Authenticator} for this {@code HttpContext}. Once an authenticator
+     * is establised on a context, all client requests must be authenticated,
+     * and the given object will be invoked to validate each request. Each call
+     * to this method replaces any previous value set.
+     *
+     * @param auth the {@code Authenticator} to set. If {@code null} then any previously
+     *             set {@code Authenticator} is removed, and client authentication
+     *             will no longer be required.
+     * @return the previous {@code Authenticator}, if any set, or {@code null} otherwise.
      */
-    public abstract Authenticator setAuthenticator (Authenticator auth);
+    public abstract Authenticator setAuthenticator(Authenticator auth);
 
     /**
-     * Returns the currently set Authenticator for this context
+     * Returns the currently set {@link Authenticator} for this context
      * if one exists.
-     * @return this HttpContext's Authenticator, or <code>null</code>
-     *         if none is set.
+     *
+     * @return this {@linkplain HttpContext HttpContext's} {@code Authenticator},
+     * or {@code null} if none is set
      */
-    public abstract Authenticator getAuthenticator ();
+    public abstract Authenticator getAuthenticator();
 }

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

@@ -30,16 +30,18 @@
 /**
  * A handler which is invoked to process HTTP exchanges. Each
  * HTTP exchange is handled by one of these handlers.
+ *
  * @since 1.6
  */
 public interface HttpHandler {
     /**
      * Handle the given request and generate an appropriate response.
      * See {@link HttpExchange} for a description of the steps
      * involved in handling an exchange.
+     *
      * @param exchange the exchange containing the request from the
-     *      client and used to send the response
-     * @throws NullPointerException if exchange is <code>null</code>
+     *                 client and used to send the response
+     * @throws NullPointerException if exchange is {@code null}
      */
     public abstract void handle (HttpExchange exchange) throws IOException;
 }

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

@@ -34,12 +34,14 @@ public class HttpPrincipal implements Principal {
     private String username, realm;
 
     /**
-     * creates a HttpPrincipal from the given username and realm
-     * @param username The name of the user within the realm
-     * @param realm The realm.
-     * @throws NullPointerException if either username or realm are null
+     * Creates a {@code HttpPrincipal} from the given {@code username} and
+     * {@code realm}.
+     *
+     * @param username the name of the user within the realm
+     * @param realm the realm for this user
+     * @throws NullPointerException if either username or realm are {@code null}
      */
-    public HttpPrincipal (String username, String realm) {
+    public HttpPrincipal(String username, String realm) {
         if (username == null || realm == null) {
             throw new NullPointerException();
         }
@@ -48,12 +50,16 @@ public HttpPrincipal (String username, String realm) {
     }
 
     /**
-     * Compares two HttpPrincipal. Returns <code>true</code>
-     * if <i>another</i> is an instance of HttpPrincipal, and its
-     * username and realm are equal to this object's username
-     * and realm. Returns <code>false</code> otherwise.
+     * Compare two instances of {@code HttpPrincipal}. Returns {@code true} if
+     * <i>another</i> is an instance of {@code HttpPrincipal}, and its username
+     * and realm are equal to this object's username and realm. Returns {@code false}
+     * otherwise.
+     *
+     * @param another the object to compare this instance of {@code HttpPrincipal} against
+     * @return {@code true} or {@code false} depending on whether objects are
+     * equal or not
      */
-    public boolean equals (Object another) {
+    public boolean equals(Object another) {
         if (!(another instanceof HttpPrincipal)) {
             return false;
         }
@@ -63,41 +69,47 @@ public boolean equals (Object another) {
     }
 
     /**
-     * returns the contents of this principal in the form
-     * <i>realm:username</i>
+     * Returns the contents of this principal in the form
+     * <i>realm:username</i>.
+     *
+     * @return the contents of this principal in the form realm:username
      */
     public String getName() {
         return username;
     }
 
     /**
-     * returns the username this object was created with.
+     * Returns the {@code username} this object was created with.
      *
-     * @return The name of the user assoicated with this object
+     * @return the name of the user associated with this object
      */
     public String getUsername() {
         return username;
     }
 
     /**
-     * returns the realm this object was created with.
+     * Returns the {@code realm} this object was created with.
      *
-     * @return The realm associated with this object
+     * @return the realm associated with this object
      */
     public String getRealm() {
         return realm;
     }
 
     /**
-     * returns a hashcode for this HttpPrincipal. This is calculated
-     * as <code>(getUsername()+getRealm().hashCode()</code>
+     * Returns a hashcode for this {@code HttpPrincipal}. This is calculated
+     * as {@code (getUsername()+getRealm()).hashCode()}.
+     *
+     * @return the hashcode for this object
      */
     public int hashCode() {
         return (username+realm).hashCode();
     }
 
     /**
-     * returns the same string as getName()
+     * Returns the same string as {@link #getName()}.
+     *
+     * @return the name associated with this object
      */
     public String toString() {
         return getName();

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

@@ -25,23 +25,17 @@
 
 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 javax.net.ssl.SSLContext;
+import javax.net.ssl.SSLParameters;
 
 
 /**
  * This class is used to configure the https parameters for each incoming
- * https connection on a HttpsServer. Applications need to override
+ * https connection on a {@link HttpsServer}. Applications need to override
  * the {@link #configure(HttpsParameters)} method in order to change
  * the default configuration.
- * <p>
- * The following <a id="example">example</a> shows how this may be done:
+ *
+ * <p> The following <a id="example">example</a> shows how this may be done:
  *
  * <blockquote><pre>
  * SSLContext sslContext = SSLContext.getInstance (....);
@@ -65,52 +59,54 @@
  *     }
  * });
  * </pre></blockquote>
+ *
  * @since 1.6
  */
 public class HttpsConfigurator {
 
     private SSLContext context;
 
     /**
-     * Creates an Https configuration, with the given SSLContext.
-     * @param context the SSLContext to use for this configurator
-     * @throws NullPointerException if no SSLContext supplied
+     * Creates a Https configuration, with the given {@link SSLContext}.
+     *
+     * @param context the {@code SSLContext} to use for this configurator
+     * @throws NullPointerException if no {@code SSLContext} supplied
      */
-    public HttpsConfigurator (SSLContext context) {
+    public HttpsConfigurator(SSLContext context) {
         if (context == null) {
             throw new NullPointerException ("null SSLContext");
         }
         this.context = context;
     }
 
     /**
-     * Returns the SSLContext for this HttpsConfigurator.
-     * @return the SSLContext
+     * Returns the {@link SSLContext} for this {@code HttpsConfigurator}.
+     *
+     * @return the {@code SSLContext}
      */
     public SSLContext getSSLContext() {
         return context;
     }
 
-//BEGIN_TIGER_EXCLUDE
    /**
-    * Called by the HttpsServer to configure the parameters
-    * for a https connection currently being established.
-    * The implementation of configure() must call
-    * {@link HttpsParameters#setSSLParameters(SSLParameters)}
-    * in order to set the SSL parameters for the connection.
-    * <p>
-    * The default implementation of this method uses the
-    * SSLParameters returned from <p>
-    * {@code getSSLContext().getDefaultSSLParameters()}
-    * <p>
-    * configure() may be overridden in order to modify this behavior.
-    * See, the example <a href="#example">above</a>.
-    * @param params the HttpsParameters to be configured.
+    * Called by the {@link HttpsServer} to configure the parameters for a https
+    * connection currently being established. The implementation of configure()
+    * must call {@link HttpsParameters#setSSLParameters(SSLParameters)} in order
+    * to set the SSL parameters for the connection.
+    *
+    * <p> The default implementation of this method uses the
+    * SSLParameters returned from:
+    *
+    * <p> {@code getSSLContext().getDefaultSSLParameters()}
+    *
+    * <p> configure() may be overridden in order to modify this behavior. See
+    * example <a href="#example">above</a>.
+    *
+    * @param params the {@code HttpsParameters} to be configured
     *
     * @since 1.6
     */
-    public void configure (HttpsParameters params) {
+    public void configure(HttpsParameters params) {
         params.setSSLParameters (getSSLContext().getDefaultSSLParameters());
     }
-//END_TIGER_EXCLUDE
 }