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();
 

src/jdk.httpserver/share/classes/com/sun/net/httpserver/spi/HttpServerProvider.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,14 +25,16 @@
 
 package com.sun.net.httpserver.spi;
 
+import com.sun.net.httpserver.HttpServer;
+import com.sun.net.httpserver.HttpsServer;
+
 import java.io.IOException;
-import java.net.*;
+import java.net.InetSocketAddress;
 import java.security.AccessController;
 import java.security.PrivilegedAction;
 import java.util.Iterator;
-import java.util.ServiceLoader;
 import java.util.ServiceConfigurationError;
-import com.sun.net.httpserver.*;
+import java.util.ServiceLoader;
 
 /**
  * Service provider class for HttpServer.
@@ -50,6 +52,8 @@ public abstract class HttpServerProvider {
      *
      * @param  backlog
      *         the socket backlog. A value of {@code zero} means the systems default
+     * @throws IOException if an I/O error occurs
+     * @return An instance of HttpServer
      */
     public abstract HttpServer createHttpServer(InetSocketAddress addr,
                                                 int backlog)
@@ -63,6 +67,8 @@ public abstract HttpServer createHttpServer(InetSocketAddress addr,
      *
      * @param  backlog
      *         the socket backlog. A value of {@code zero} means the systems default
+     * @throws IOException if an I/O error occurs
+     * @return An instance of HttpServer
      */
     public abstract HttpsServer createHttpsServer(InetSocketAddress addr,
                                                   int backlog)

test/jdk/com/sun/net/httpserver/AuthenticatorTest

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * 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.
+ */
+
+/*
+ * @test
+ * @bug 8251496
+ * @summary Tests for methods in Authenticator
+ * @run testng/othervm AuthenticatorTest
+ */
+
+import com.sun.net.httpserver.Authenticator;
+import com.sun.net.httpserver.BasicAuthenticator;
+import com.sun.net.httpserver.HttpPrincipal;
+import org.testng.annotations.Test;
+
+import static org.testng.Assert.assertEquals;
+
+
+public class AuthenticatorTest {
+    @Test
+    public void testFailure() {
+        var failureResult = new Authenticator.Failure(666);
+        assertEquals(failureResult.getResponseCode(), 666);
+    }
+
+    @Test
+    public void testRetry() {
+        var retryResult = new Authenticator.Retry(333);
+        assertEquals(retryResult.getResponseCode(), 333);
+    }
+
+    @Test
+    public void TestSuccess() {
+        var principal = new HttpPrincipal("test", "123");
+        var successResult = new Authenticator.Success(principal);
+        assertEquals(successResult.getPrincipal(), principal);
+        assertEquals("test", principal.getName());
+        assertEquals("123", principal.getRealm());
+    }
+}

test/jdk/com/sun/net/httpserver/CreateHttpServerTest.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * 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.
+ */
+
+/*
+ * @test
+ * @bug 8251496
+ * @summary summary
+ * @run testng/othervm CreateHttpServerTest
+ */
+
+import com.sun.net.httpserver.HttpServer;
+import org.testng.annotations.Test;
+
+import java.io.IOException;
+import java.net.InetAddress;
+import java.net.InetSocketAddress;
+
+import static org.testng.Assert.assertTrue;
+
+public class CreateHttpServerTest {
+    @Test
+    public void TestCreate() throws IOException {
+        var server = HttpServer.create();
+        assertTrue(server instanceof HttpServer);
+    }
+    @Test
+    public void TestCreateWithParameters() throws IOException {
+        var addr = new InetSocketAddress(InetAddress.getLoopbackAddress(), 0);
+        var server = HttpServer.create(addr, 123);
+        assertTrue(server instanceof HttpServer);
+    }
+}

test/jdk/com/sun/net/httpserver/HeadersTest.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * 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.
+ */
+
+/*
+ * @test
+ * @bug 8251496
+ * @summary Tests for methods in Headers class
+ * @run testng/othervm HeadersTest
+ */
+
+import com.sun.net.httpserver.Headers;
+import org.testng.annotations.Test;
+
+import static org.testng.Assert.assertTrue;
+
+public class HeadersTest {
+
+    @Test
+    public void TestDefaultConstructor() {
+        var headers = new Headers();
+        assertTrue(headers.isEmpty());
+    }
+}

test/jdk/com/sun/net/httpserver/HttpPrincipalTest.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * 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.
+ */
+
+/*
+ * @test
+ * @bug 8251496
+ * @summary Tests for methods in HttpPrincipal
+ * @run testng/othervm HttpPrincipalTest
+ */
+
+import com.sun.net.httpserver.HttpPrincipal;
+import org.testng.annotations.Test;
+
+import static org.testng.Assert.assertEquals;
+
+public class HttpPrincipalTest {
+
+    @Test
+    public void TestGetters() {
+        var principal = new HttpPrincipal("test", "123");
+        assertEquals(principal.getUsername(), "test");
+        assertEquals(principal.getRealm(), "123");
+    }
+}