8251496: Fix doclint warnings in jdk.net.httpserver

Reviewed-by: dfuchs, rriggs, chegar

Author: pconcannon

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2006, 2020, 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
@@ -24,9 +24,6 @@
  */
 
 package com.sun.net.httpserver;
-import java.net.*;
-import java.io.*;
-import java.util.*;
 
 /**
  * Authenticator represents an implementation of an HTTP authentication
@@ -38,10 +35,23 @@
  */
 public abstract class Authenticator {
 
+    /**
+     * Constructor for subclasses to call.
+     */
+    protected Authenticator () { }
+
     /**
      * Base class for return type from authenticate() method
      */
-    public abstract static class Result {}
+    public abstract static class Result {
+
+        /**
+         * Constructor for subclasses to call.
+         */
+        protected Result () {}
+    }
+
+
 
     /**
      * Indicates an authentication failure. The authentication
@@ -51,12 +61,20 @@ public static class Failure extends Result {
 
         private int responseCode;
 
+        /**
+         * Creates a {@code Failure} instance with given response code.
+         *
+         * @param responseCode The response code to associate with this
+         *                     {@code Failure} instance
+         */
         public Failure (int responseCode) {
             this.responseCode = responseCode;
         }
 
         /**
          * returns the response code to send to the client
+         *
+         * @return The response code associated with this {@code Failure} instance
          */
         public int getResponseCode() {
             return responseCode;
@@ -71,11 +89,19 @@ public int getResponseCode() {
     public static class Success extends Result {
         private HttpPrincipal principal;
 
+        /**
+         * Creates a {@code Success} instance with given {@code Principal}.
+         *
+         * @param p The authenticated user you wish to set as Principal
+         */
         public Success (HttpPrincipal p) {
             principal = p;
         }
         /**
          * returns the authenticated user Principal
+         *
+         * @return The {@code Principal} instance associated with the authenticated user
+         *
          */
         public HttpPrincipal getPrincipal() {
             return principal;
@@ -93,12 +119,20 @@ public static class Retry extends Result {
 
         private int responseCode;
 
+        /**
+         * Creates a {@code Retry} instance with given response code.
+         *
+         * @param responseCode The response code to associate with this
+         *                     {@code Retry} instance
+         */
         public Retry (int responseCode) {
             this.responseCode = responseCode;
         }
 
         /**
          * returns the response code to send to the client
+         *
+         * @return The response code associated with this {@code Retry} instance
          */
         public int getResponseCode() {
             return responseCode;
@@ -120,6 +154,9 @@ public int getResponseCode() {
      * headers needing to be sent back to the client are set in the
      * given HttpExchange. The response code to be returned must be provided
      * in the Retry object. Retry may occur multiple times.
+     *
+     * @param exch The HttpExchange upon which authenticate is called
+     * @return The result
      */
     public abstract Result authenticate (HttpExchange exch);
 }

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

@@ -39,6 +39,7 @@
  */
 public abstract class BasicAuthenticator extends Authenticator {
 
+    /** The HTTP Basic authentication realm. */
     protected final String realm;
     private final Charset charset;
     private final boolean isUTF8;

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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
@@ -41,6 +41,9 @@
  */
 public abstract class Filter {
 
+    /**
+     * Constructor for subclasses to call.
+     */
     protected Filter () {}
 
     /**
@@ -55,6 +58,13 @@ public static class Chain {
         private ListIterator<Filter> iter;
         private HttpHandler handler;
 
+        /**
+         * Creates a {@code Chain} instance with given filters and handler.
+         *
+         * @param filters The filters that make up the Chain
+         * @param handler The HttpHandler that will be invoked after the final
+         *                Filter has finished
+         */
         public Chain (List<Filter> filters, HttpHandler handler) {
             iter = filters.listIterator();
             this.handler = handler;

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

@@ -65,6 +65,9 @@ public class Headers implements Map<String,List<String>> {
 
         HashMap<String,List<String>> map;
 
+       /**
+        * Creates an empty instance of Headers.
+        */
         public Headers () {map = new HashMap<String,List<String>>(32);}
 
         /* Normalize the key by converting to following form.

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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
@@ -24,9 +24,8 @@
  */
 
 package com.sun.net.httpserver;
-import java.net.*;
-import java.io.*;
-import java.util.*;
+import java.util.List;
+import java.util.Map;
 
 /**
  * HttpContext represents a mapping between the root URI path of an application
@@ -42,6 +41,9 @@
  */
 public abstract class HttpContext {
 
+    /**
+     * Constructor for subclasses to call.
+     */
     protected HttpContext () {
     }
 
@@ -78,6 +80,8 @@ protected HttpContext () {
      * <p>
      * Every attribute stored in this Map will be visible to
      * every HttpExchange processed by this context
+     *
+     * @return a map containing the attributes of this context
      */
     public abstract Map<String,Object> getAttributes() ;
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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
@@ -25,12 +25,11 @@
 
 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 java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.net.InetSocketAddress;
+import java.net.URI;
 
 /**
  * This class encapsulates a HTTP request received and a
@@ -66,6 +65,9 @@
 
 public abstract class HttpExchange implements AutoCloseable {
 
+    /**
+     * Constructor for subclasses to call.
+     */
     protected HttpExchange () {
     }
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2006, 2020, 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
@@ -24,9 +24,6 @@
  */
 
 package com.sun.net.httpserver;
-import java.net.*;
-import java.io.*;
-import java.util.*;
 import java.security.Principal;
 
 /**
@@ -75,13 +72,17 @@ public String getName() {
 
     /**
      * returns the username this object was created with.
+     *
+     * @return The name of the user assoicated with this object
      */
     public String getUsername() {
         return username;
     }
 
     /**
      * returns the realm this object was created with.
+     *
+     * @return The realm associated with this object
      */
     public String getRealm() {
         return realm;

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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
@@ -25,16 +25,13 @@
 
 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.HttpServerProvider;
 
+import java.io.IOException;
+import java.net.BindException;
+import java.net.InetSocketAddress;
+import java.util.concurrent.Executor;
+
 /**
  * This class implements a simple HTTP server. A HttpServer is bound to an IP address
  * and port number and listens for incoming TCP connections from clients on this address.
@@ -98,6 +95,7 @@
 public abstract class HttpServer {
 
     /**
+     * Constructor for subclasses to call.
      */
     protected HttpServer () {
     }
@@ -106,7 +104,9 @@ protected HttpServer () {
      * creates a HttpServer instance which is initially not bound to any local address/port.
      * The HttpServer is acquired from the currently installed {@link HttpServerProvider}
      * The server must be bound using {@link #bind(InetSocketAddress,int)} before it can be used.
-     * @throws IOException
+     *
+     * @throws IOException if an I/O error occurs
+     * @return An instance of HttpServer
      */
     public static HttpServer create () throws IOException {
         return create (null, 0);
@@ -127,7 +127,8 @@ public static HttpServer create () throws IOException {
      *          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
+     * @throws IOException if an I/O error occurs
+     * @return An instance of HttpServer
      */
 
     public static HttpServer create (
@@ -215,6 +216,7 @@ public static HttpServer create (
      * @throws IllegalArgumentException if path is invalid, or if a context
      *          already exists for this path
      * @throws NullPointerException if either path, or handler are <code>null</code>
+     * @return An instance of HttpContext
      */
     public abstract HttpContext createContext (String path, HttpHandler handler) ;
 
@@ -239,6 +241,7 @@ public static HttpServer create (
      * @throws IllegalArgumentException if path is invalid, or if a context
      *          already exists for this path
      * @throws NullPointerException if path is <code>null</code>
+     * @return An instance of HttpContext
      */
     public abstract HttpContext createContext (String path) ;
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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
@@ -24,7 +24,9 @@
  */
 
 package com.sun.net.httpserver;
+
 import java.net.InetSocketAddress;
+
 //BEGIN_TIGER_EXCLUDE
 import javax.net.ssl.SSLParameters;
 //END_TIGER_EXCLUDE
@@ -56,16 +58,23 @@ public abstract class HttpsParameters {
     private boolean wantClientAuth;
     private boolean needClientAuth;
 
+    /**
+     * Constructor for subclasses to call.
+     */
     protected HttpsParameters() {}
 
     /**
      * Returns the HttpsConfigurator for this HttpsParameters.
+     *
+     * @return HttpsConfigurator for this instance of HttpsParameters
      */
     public abstract HttpsConfigurator getHttpsConfigurator();
 
     /**
      * Returns the address of the remote client initiating the
      * connection.
+     *
+     * @return Address of the remote client initiating the connection
      */
     public abstract InetSocketAddress getClientAddress();