8273045: Fix misc javadoc bugs in the java.security and javax.net.ssl code

Reviewed-by: xuelei

Author: Bradford Wetmore

src/java.base/share/classes/java/security/AuthProvider.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2021, 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
@@ -96,7 +96,7 @@ protected AuthProvider(String name, String versionStr, String info) {
      *          from the caller, which may be {@code null}
      *
      * @throws IllegalStateException if the provider requires configuration
-     * and {@link configure} has not been called
+     * and {@link #configure} has not been called
      * @throws LoginException if the login operation fails
      * @throws SecurityException if the caller does not pass a
      *  security check for
@@ -111,7 +111,7 @@ public abstract void login(Subject subject, CallbackHandler handler)
      * Log out from this provider.
      *
      * @throws IllegalStateException if the provider requires configuration
-     * and {@link configure} has not been called
+     * and {@link #configure} has not been called
      * @throws LoginException if the logout operation fails
      * @throws SecurityException if the caller does not pass a
      *  security check for
@@ -139,7 +139,7 @@ public abstract void login(Subject subject, CallbackHandler handler)
      *          authentication information, which may be {@code null}
      *
      * @throws IllegalStateException if the provider requires configuration
-     * and {@link configure} has not been called
+     * and {@link #configure} has not been called
      * @throws SecurityException if the caller does not pass a
      *  security check for
      *  {@code SecurityPermission("authProvider.name")},

src/java.base/share/classes/javax/net/ssl/SNIHostName.java

@@ -34,6 +34,7 @@
 import java.util.Locale;
 import java.util.Objects;
 import java.util.regex.Pattern;
+import java.util.regex.PatternSyntaxException;
 
 /**
  * Instances of this class represent a server name of type
@@ -297,7 +298,7 @@ public String toString() {
      * @return a {@code SNIMatcher} object for {@code SNIHostName}s
      * @throws NullPointerException if {@code regex} is
      *         {@code null}
-     * @throws java.util.regex.PatternSyntaxException if the regular expression's
+     * @throws PatternSyntaxException if the regular expression's
      *         syntax is invalid
      */
     public static SNIMatcher createSNIMatcher(String regex) {

src/java.base/share/classes/javax/net/ssl/SNIMatcher.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2021, 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,6 +25,8 @@
 
 package javax.net.ssl;
 
+import java.util.Collection;
+
 /**
  * Instances of this class represent a matcher that performs match
  * operations on an {@link SNIServerName} instance.

src/java.base/share/classes/javax/net/ssl/SNIServerName.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2021, 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
@@ -27,6 +27,7 @@
 
 import java.util.Arrays;
 import java.util.HexFormat;
+import java.util.List;
 
 /**
  * Instances of this class represent a server name in a Server Name

src/java.base/share/classes/javax/net/ssl/SSLContextSpi.java

@@ -51,7 +51,7 @@ public SSLContextSpi() {}
      * @param tm the sources of peer authentication trust decisions
      * @param sr the source of randomness
      * @throws KeyManagementException if this operation fails
-     * @see SSLContext#init(KeyManager [], TrustManager [], SecureRandom)
+     * @see SSLContext#init(KeyManager[], TrustManager[], SecureRandom)
      */
     protected abstract void engineInit(KeyManager[] km, TrustManager[] tm,
         SecureRandom sr) throws KeyManagementException;

src/java.base/share/classes/javax/net/ssl/SSLEngine.java

@@ -312,7 +312,7 @@
  *
  *      <LI> <em>Enabled</em> cipher suites, which may be fewer than
  *      the full set of supported suites.  This group is set using the
- *      {@link #setEnabledCipherSuites(String [])} method, and
+ *      {@link #setEnabledCipherSuites(String[])} method, and
  *      queried using the {@link #getEnabledCipherSuites()} method.
  *      Initially, a default set of cipher suites will be enabled on a
  *      new engine that represents the minimum suggested
@@ -495,8 +495,8 @@ public int getPeerPort() {
      * An invocation of this method behaves in exactly the same manner
      * as the invocation:
      * <blockquote><pre>
-     * {@link #wrap(ByteBuffer [], int, int, ByteBuffer)
-     *     engine.wrap(new ByteBuffer [] { src }, 0, 1, dst);}
+     * {@link #wrap(ByteBuffer[], int, int, ByteBuffer)
+     *     engine.wrap(new ByteBuffer[] { src }, 0, 1, dst);}
      * </pre></blockquote>
      *
      * @param   src
@@ -517,7 +517,7 @@ public int getPeerPort() {
      *          is null.
      * @throws  IllegalStateException if the client/server mode
      *          has not yet been set.
-     * @see     #wrap(ByteBuffer [], int, int, ByteBuffer)
+     * @see     #wrap(ByteBuffer[], int, int, ByteBuffer)
      */
     public SSLEngineResult wrap(ByteBuffer src,
             ByteBuffer dst) throws SSLException {
@@ -531,7 +531,7 @@ public SSLEngineResult wrap(ByteBuffer src,
      * An invocation of this method behaves in exactly the same manner
      * as the invocation:
      * <blockquote><pre>
-     * {@link #wrap(ByteBuffer [], int, int, ByteBuffer)
+     * {@link #wrap(ByteBuffer[], int, int, ByteBuffer)
      *     engine.wrap(srcs, 0, srcs.length, dst);}
      * </pre></blockquote>
      *
@@ -554,7 +554,7 @@ public SSLEngineResult wrap(ByteBuffer src,
      *          is null, or if any element in {@code srcs} is null.
      * @throws  IllegalStateException if the client/server mode
      *          has not yet been set.
-     * @see     #wrap(ByteBuffer [], int, int, ByteBuffer)
+     * @see     #wrap(ByteBuffer[], int, int, ByteBuffer)
      */
     public SSLEngineResult wrap(ByteBuffer [] srcs,
             ByteBuffer dst) throws SSLException {
@@ -650,8 +650,8 @@ public abstract SSLEngineResult wrap(ByteBuffer [] srcs, int offset,
      * An invocation of this method behaves in exactly the same manner
      * as the invocation:
      * <blockquote><pre>
-     * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int)
-     *     engine.unwrap(src, new ByteBuffer [] { dst }, 0, 1);}
+     * {@link #unwrap(ByteBuffer, ByteBuffer[], int, int)
+     *     engine.unwrap(src, new ByteBuffer[] { dst }, 0, 1);}
      * </pre></blockquote>
      *
      * @param   src
@@ -672,7 +672,7 @@ public abstract SSLEngineResult wrap(ByteBuffer [] srcs, int offset,
      *          is null.
      * @throws  IllegalStateException if the client/server mode
      *          has not yet been set.
-     * @see     #unwrap(ByteBuffer, ByteBuffer [], int, int)
+     * @see     #unwrap(ByteBuffer, ByteBuffer[], int, int)
      */
     public SSLEngineResult unwrap(ByteBuffer src,
             ByteBuffer dst) throws SSLException {
@@ -686,7 +686,7 @@ public SSLEngineResult unwrap(ByteBuffer src,
      * An invocation of this method behaves in exactly the same manner
      * as the invocation:
      * <blockquote><pre>
-     * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int)
+     * {@link #unwrap(ByteBuffer, ByteBuffer[], int, int)
      *     engine.unwrap(src, dsts, 0, dsts.length);}
      * </pre></blockquote>
      *
@@ -709,7 +709,7 @@ public SSLEngineResult unwrap(ByteBuffer src,
      *          is null, or if any element in {@code dsts} is null.
      * @throws  IllegalStateException if the client/server mode
      *          has not yet been set.
-     * @see     #unwrap(ByteBuffer, ByteBuffer [], int, int)
+     * @see     #unwrap(ByteBuffer, ByteBuffer[], int, int)
      */
     public SSLEngineResult unwrap(ByteBuffer src,
             ByteBuffer [] dsts) throws SSLException {
@@ -926,7 +926,7 @@ public abstract SSLEngineResult unwrap(ByteBuffer src,
      *
      * @return  an array of cipher suite names
      * @see     #getEnabledCipherSuites()
-     * @see     #setEnabledCipherSuites(String [])
+     * @see     #setEnabledCipherSuites(String[])
      */
     public abstract String [] getSupportedCipherSuites();
 
@@ -952,7 +952,7 @@ public abstract SSLEngineResult unwrap(ByteBuffer src,
      *
      * @return  an array of cipher suite names
      * @see     #getSupportedCipherSuites()
-     * @see     #setEnabledCipherSuites(String [])
+     * @see     #setEnabledCipherSuites(String[])
      */
     public abstract String [] getEnabledCipherSuites();
 
@@ -983,7 +983,7 @@ public abstract SSLEngineResult unwrap(ByteBuffer src,
      * @see     #getSupportedCipherSuites()
      * @see     #getEnabledCipherSuites()
      */
-    public abstract void setEnabledCipherSuites(String suites []);
+    public abstract void setEnabledCipherSuites(String[] suites);
 
 
     /**
@@ -1005,7 +1005,7 @@ public abstract SSLEngineResult unwrap(ByteBuffer src,
      * by the protocol.
      *
      * @return  an array of protocols
-     * @see     #setEnabledProtocols(String [])
+     * @see     #setEnabledProtocols(String[])
      */
     public abstract String [] getEnabledProtocols();
 
@@ -1024,7 +1024,7 @@ public abstract SSLEngineResult unwrap(ByteBuffer src,
      *          when the protocols parameter is null.
      * @see     #getEnabledProtocols()
      */
-    public abstract void setEnabledProtocols(String protocols[]);
+    public abstract void setEnabledProtocols(String[] protocols);
 
 
     /**
@@ -1161,7 +1161,7 @@ public SSLSession getHandshakeSession() {
      *
      * @implNote
      * The JDK SunJSSE provider implementation returns false unless
-     * {@link setUseClientMode(boolean)} is used to change the mode to true.
+     * {@link #setUseClientMode(boolean)} is used to change the mode to true.
      *
      * @return  true if the engine should do handshaking
      *          in "client" mode

src/java.base/share/classes/javax/net/ssl/SSLEngineResult.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2021, 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,6 +25,8 @@
 
 package javax.net.ssl;
 
+import java.nio.ByteBuffer;
+
 /**
  * An encapsulation of the result state produced by
  * {@code SSLEngine} I/O calls.

src/java.base/share/classes/javax/net/ssl/SSLServerSocket.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2021, 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
@@ -23,13 +23,11 @@
  * questions.
  */
 
-
 package javax.net.ssl;
 
 import java.io.*;
 import java.net.*;
 
-
 /**
  * This class extends <code>ServerSocket</code> and
  * provides secure server sockets using protocols such as the Secure
@@ -205,7 +203,7 @@ protected SSLServerSocket(int port, int backlog, InetAddress address)
      *
      * @return an array of cipher suites enabled
      * @see #getSupportedCipherSuites()
-     * @see #setEnabledCipherSuites(String [])
+     * @see #setEnabledCipherSuites(String[])
      */
     public abstract String [] getEnabledCipherSuites();
 
@@ -261,7 +259,7 @@ protected SSLServerSocket(int port, int backlog, InetAddress address)
      *
      * @return an array of cipher suite names
      * @see #getEnabledCipherSuites()
-     * @see #setEnabledCipherSuites(String [])
+     * @see #setEnabledCipherSuites(String[])
      */
     public abstract String [] getSupportedCipherSuites();
 
@@ -271,7 +269,7 @@ protected SSLServerSocket(int port, int backlog, InetAddress address)
      *
      * @return an array of protocol names supported
      * @see #getEnabledProtocols()
-     * @see #setEnabledProtocols(String [])
+     * @see #setEnabledProtocols(String[])
      */
     public abstract String [] getSupportedProtocols();
 
@@ -287,7 +285,7 @@ protected SSLServerSocket(int port, int backlog, InetAddress address)
      *
      * @return an array of protocol names
      * @see #getSupportedProtocols()
-     * @see #setEnabledProtocols(String [])
+     * @see #setEnabledProtocols(String[])
      */
     public abstract String [] getEnabledProtocols();
 

src/java.base/share/classes/javax/net/ssl/SSLSession.java

@@ -26,6 +26,7 @@
 package javax.net.ssl;
 
 import java.security.Principal;
+import java.nio.ByteBuffer;
 
 /**
  * In SSL, sessions are used to describe an ongoing relationship between

src/java.base/share/classes/javax/net/ssl/X509ExtendedTrustManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2021, 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
@@ -26,8 +26,8 @@
 package javax.net.ssl;
 
 import java.net.Socket;
-import javax.net.ssl.X509TrustManager;
 
+import java.security.AlgorithmConstraints;
 import java.security.cert.X509Certificate;
 import java.security.cert.CertificateException;