harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770159 [1/2] - in /harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net: ./ ssl/
Date Thu, 30 Apr 2009 11:01:29 GMT
Author: tellison
Date: Thu Apr 30 11:01:28 2009
New Revision: 770159

URL: http://svn.apache.org/viewvc?rev=770159&view=rev
Log:
Apply patch for HARMONY-6190 (Javadocs for javax.net.*)

Modified:
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ServerSocketFactory.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/SocketFactory.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/CertPathTrustManagerParameters.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HandshakeCompletedEvent.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HandshakeCompletedListener.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HostnameVerifier.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HttpsURLConnection.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManager.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManagerFactory.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManagerFactorySpi.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyStoreBuilderParameters.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/ManagerFactoryParameters.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLContext.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLContextSpi.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLEngine.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLEngineResult.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLException.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLHandshakeException.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLKeyException.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLPeerUnverifiedException.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLPermission.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLProtocolException.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocket.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocketFactory.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSession.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingEvent.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingListener.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionContext.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocket.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocketFactory.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManager.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactory.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactorySpi.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509ExtendedKeyManager.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509KeyManager.java
    harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509TrustManager.java

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ServerSocketFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ServerSocketFactory.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ServerSocketFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ServerSocketFactory.java Thu Apr 30 11:01:28 2009
@@ -22,9 +22,19 @@
 import java.net.ServerSocket;
 import java.net.SocketException;
 
+/**
+ * This abstract class defines methods to create server sockets. It can be
+ * subclassed to create specific server socket types.
+ */
 public abstract class ServerSocketFactory {
     private static ServerSocketFactory defaultFactory;
 
+    /**
+     * Gets the default server socket factory of the system which can be used to
+     * create new server sockets without creating a subclass of this factory.
+     *
+     * @return the system default server socket factory.
+     */
     public static synchronized ServerSocketFactory getDefault() {
         if (defaultFactory == null) {
             defaultFactory = new DefaultServerSocketFactory();
@@ -32,19 +42,67 @@
         return defaultFactory;
     }
 
+    /**
+     * Creates a new {@code ServerSocketFactory} instance.
+     */
     protected ServerSocketFactory() {
         super();
     }
 
+    /**
+     * Creates a new server socket which is not bound to any local address. This
+     * method has to be overridden by a subclass otherwise a {@code
+     * SocketException} is thrown.
+     *
+     * @return the created unbound server socket.
+     * @throws IOException
+     *             if an error occurs while creating a new server socket.
+     */
     public ServerSocket createServerSocket() throws IOException {
         // follow RI's behavior
         throw new SocketException("Unbound server sockets not implemented");
     }
 
+    /**
+     * Creates a new server socket which is bound to the given port.
+     *
+     * @param port
+     *            the port on which the created socket has to listen.
+     * @return the created bound server socket.
+     * @throws IOException
+     *             if an error occurs while creating a new server socket.
+     */
     public abstract ServerSocket createServerSocket(int port) throws IOException;
 
+    /**
+     * Creates a new server socket which is bound to the given port and
+     * configures its maximum of queued connections.
+     *
+     * @param port
+     *            the port on which the created socket has to listen.
+     * @param backlog
+     *            the maximum of queued connections.
+     * @return the created bound server socket.
+     * @throws IOException
+     *             if an error occurs while creating a new server socket.
+     */
     public abstract ServerSocket createServerSocket(int port, int backlog) throws IOException;
 
+    /**
+     * Creates a new server socket which is bound to the given address on the
+     * specified port and configures its maximum of queued connections.
+     *
+     * @param port
+     *            the port on which the created socket has to listen.
+     * @param backlog
+     *            the maximum of queued connections.
+     * @param iAddress
+     *            the address of the network interface which is used by the
+     *            created socket.
+     * @return the created bound server socket.
+     * @throws IOException
+     *             if an error occurs while creating a new server socket.
+     */
     public abstract ServerSocket createServerSocket(int port, int backlog, InetAddress iAddress)
             throws IOException;
 

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/SocketFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/SocketFactory.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/SocketFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/SocketFactory.java Thu Apr 30 11:01:28 2009
@@ -27,6 +27,12 @@
 
     private static SocketFactory defaultFactory;
 
+    /**
+     * Gets the default socket factory of the system which can be used to create
+     * new sockets without creating a subclass of this factory.
+     *
+     * @return the system default socket factory.
+     */
     public static synchronized SocketFactory getDefault() {
         if (defaultFactory == null) {
             defaultFactory = new DefaultSocketFactory();
@@ -34,23 +40,110 @@
         return defaultFactory;
     }
 
+    /**
+     * Creates a new {@code SocketFactory} instance.
+     */
     protected SocketFactory() {
         super();
     }
 
+    /**
+     * Creates a new socket which is not connected to any remote host. This
+     * method has to be overridden by a subclass otherwise a {@code
+     * SocketException} is thrown.
+     *
+     * @return the created unconnected socket.
+     * @throws IOException
+     *             if an error occurs while creating a new socket.
+     */
     public Socket createSocket() throws IOException {
         // follow RI's behavior
         throw new SocketException("Unconnected sockets not implemented");
     }
 
+    /**
+     * Creates a new socket which is connected to the remote host specified by
+     * the parameters {@code host} and {@code port}. The socket is bound to any
+     * available local address and port.
+     *
+     * @param host
+     *            the remote host address the socket has to be connected to.
+     * @param port
+     *            the port number of the remote host at which the socket is
+     *            connected.
+     * @return the created connected socket.
+     * @throws IOException
+     *             if an error occurs while creating a new socket.
+     * @throws UnknownHostException
+     *             if the specified host is unknown or the IP address could not
+     *             be resolved.
+     */
     public abstract Socket createSocket(String host, int port) throws IOException,
             UnknownHostException;
 
+    /**
+     * Creates a new socket which is connected to the remote host specified by
+     * the parameters {@code host} and {@code port}. The socket is bound to the
+     * local network interface specified by the InetAddress {@code localHost} on
+     * port {@code localPort}.
+     *
+     * @param host
+     *            the remote host address the socket has to be connected to.
+     * @param port
+     *            the port number of the remote host at which the socket is
+     *            connected.
+     * @param localHost
+     *            the local host address the socket is bound to.
+     * @param localPort
+     *            the port number of the local host at which the socket is
+     *            bound.
+     * @return the created connected socket.
+     * @throws IOException
+     *             if an error occurs while creating a new socket.
+     * @throws UnknownHostException
+     *             if the specified host is unknown or the IP address could not
+     *             be resolved.
+     */
     public abstract Socket createSocket(String host, int port, InetAddress localHost, int localPort)
             throws IOException, UnknownHostException;
 
+    /**
+     * Creates a new socket which is connected to the remote host specified by
+     * the InetAddress {@code host}. The socket is bound to any available local
+     * address and port.
+     *
+     * @param host
+     *            the host address the socket has to be connected to.
+     * @param port
+     *            the port number of the remote host at which the socket is
+     *            connected.
+     * @return the created connected socket.
+     * @throws IOException
+     *             if an error occurs while creating a new socket.
+     */
     public abstract Socket createSocket(InetAddress host, int port) throws IOException;
 
+
+    /**
+     * Creates a new socket which is connected to the remote host specified by
+     * the InetAddress {@code address}. The socket is bound to the local network
+     * interface specified by the InetAddress {@code localHost} on port {@code
+     * localPort}.
+     *
+     * @param address
+     *            the remote host address the socket has to be connected to.
+     * @param port
+     *            the port number of the remote host at which the socket is
+     *            connected.
+     * @param localAddress
+     *            the local host address the socket is bound to.
+     * @param localPort
+     *            the port number of the local host at which the socket is
+     *            bound.
+     * @return the created connected socket.
+     * @throws IOException
+     *             if an error occurs while creating a new socket.
+     */
     public abstract Socket createSocket(InetAddress address, int port, InetAddress localAddress,
             int localPort) throws IOException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/CertPathTrustManagerParameters.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/CertPathTrustManagerParameters.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/CertPathTrustManagerParameters.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/CertPathTrustManagerParameters.java Thu Apr 30 11:01:28 2009
@@ -20,8 +20,9 @@
 import java.security.cert.CertPathParameters;
 
 /**
- * Container for {@link CertPathParameters}.
- * 
+ * Certification path parameters to provide to certification path
+ * based {@link TrustManager}.
+ *
  * @since 1.5
  */
 public class CertPathTrustManagerParameters implements ManagerFactoryParameters {
@@ -29,20 +30,20 @@
     private final CertPathParameters param;
 
     /**
-     * Constructs an instance by cloning the parameters passed.
+     * Creates a new {@code CertPathTrustManagerParameters} with the specified
+     * certification path parameters.
      * 
-     * @param parameters the parameters to wrap
-     * 
-     * @throws NullPointerException if {@code parameters} is {@code null}
+     * @param parameters
+     *            the certification path parameters.
      */
     public CertPathTrustManagerParameters(CertPathParameters parameters) {
         param = (CertPathParameters) parameters.clone();
     }
 
     /**
-     * The parameters contained within.
+     * Returns a copy of the certification path parameters.
      * 
-     * @return a cloned instance of the parameters
+     * @return a copy of the certification path parameters.
      */
     public CertPathParameters getParameters() {
         return (CertPathParameters) param.clone();

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HandshakeCompletedEvent.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HandshakeCompletedEvent.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HandshakeCompletedEvent.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HandshakeCompletedEvent.java Thu Apr 30 11:01:28 2009
@@ -23,49 +23,117 @@
 import javax.security.cert.X509Certificate;
 import java.util.EventObject;
 
+/**
+ * The event object encapsulating the information about a completed SSL
+ * handshake on a SSL connection.
+ */
 public class HandshakeCompletedEvent extends EventObject implements Serializable {
 
     /**
-     * The 5.0 spec. doesn't declare this serialVersionUID field In order to be compatible it is
-     * explicitly declared here
+     * The 5.0 spec. doesn't declare this serialVersionUID field In order to be
+     * compatible it is explicitly declared here
      */
     private static final long serialVersionUID = 7914963744257769778L;
 
     private transient SSLSession session;
 
+    /**
+     * Creates a new {@code HandshakeCompletedEvent} with the specified SSL
+     * socket and SSL session.
+     *
+     * @param sock
+     *            the SSL socket.
+     * @param s
+     *            the SSL session.
+     */
     public HandshakeCompletedEvent(SSLSocket sock, SSLSession s) {
         super(sock);
         session = s;
     }
 
+    /**
+     * Returns the SSL session associated with this event.
+     *
+     * @return the SSL session associated with this event.
+     */
     public SSLSession getSession() {
         return session;
     }
 
+    /**
+     * Returns the name of the cipher suite negotiated during this handshake.
+     *
+     * @return the name of the cipher suite negotiated during this handshake.
+     */
     public String getCipherSuite() {
         return session.getCipherSuite();
     }
 
+    /**
+     * Returns the list of local certificates used during the handshake. These
+     * certificates were sent to the peer.
+     *
+     * @return Returns the list of certificates used during the handshake with
+     *         the local identity certificate followed by CAs, or {@code null}
+     *         if no certificates were used during the handshake.
+     */
     public Certificate[] getLocalCertificates() {
         return session.getLocalCertificates();
     }
 
+    /**
+     * Return the list of certificates identifying the peer during the
+     * handshake.
+     *
+     * @return the list of certificates identifying the peer with the peer's
+     *         identity certificate followed by CAs.
+     * @throws SSLPeerUnverifiedException
+     *             if the identity of the peer has not been verified.
+     */
     public Certificate[] getPeerCertificates() throws SSLPeerUnverifiedException {
         return session.getPeerCertificates();
     }
 
+    /**
+     * Returns the list of certificates identifying the peer. The peer's
+     * identity certificate is followed by the validated certificate authority
+     * certificates.
+     * <p>
+     * <b>Replaced by:</b> {@link #getPeerCertificates()}
+     *
+     * @return the list of certificates identifying the peer
+     * @throws SSLPeerUnverifiedException
+     *             if the identity of the peer has not been verified.
+     */
     public X509Certificate[] getPeerCertificateChain() throws SSLPeerUnverifiedException {
         return session.getPeerCertificateChain();
     }
 
+    /**
+     * Returns the {@code Principal} identifying the peer.
+     *
+     * @return the {@code Principal} identifying the peer.
+     * @throws SSLPeerUnverifiedException
+     *             if the identity of the peer has not been verified.
+     */
     public Principal getPeerPrincipal() throws SSLPeerUnverifiedException {
         return session.getPeerPrincipal();
     }
 
+    /**
+     * Returns the {@code Principal} used to identify during the handshake.
+     *
+     * @return the {@code Principal} used to identify during the handshake.
+     */
     public Principal getLocalPrincipal() {
         return session.getLocalPrincipal();
     }
 
+    /**
+     * Returns the SSL socket that produced this event.
+     *
+     * @return the SSL socket that produced this event.
+     */
     public SSLSocket getSocket() {
         return (SSLSocket) this.source;
     }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HandshakeCompletedListener.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HandshakeCompletedListener.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HandshakeCompletedListener.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HandshakeCompletedListener.java Thu Apr 30 11:01:28 2009
@@ -19,6 +19,16 @@
 
 import java.util.EventListener;
 
+/**
+ * The listener to be implemented to receive event notifications on completion
+ * of SSL handshake on an SSL connection.
+ */
 public interface HandshakeCompletedListener extends EventListener {
+    /**
+     * The callback method that is invoked when a SSL handshake is completed.
+     *
+     * @param event
+     *            the information on the completed SSL handshake event.
+     */
     void handshakeCompleted(HandshakeCompletedEvent event);
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HostnameVerifier.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HostnameVerifier.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HostnameVerifier.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HostnameVerifier.java Thu Apr 30 11:01:28 2009
@@ -17,6 +17,24 @@
 
 package javax.net.ssl;
 
+/**
+ * The interface to be used to provide hostname verification functionality.
+ * <p>
+ * This is an extended verification option that implementers can provide. It is to be used
+ * during a handshake if the URL's hostname does not match the peer's
+ * identification hostname.
+ */
 public interface HostnameVerifier {
+    /**
+     * Verifies that the specified hostname is allowed within the specified SSL
+     * session.
+     *
+     * @param hostname
+     *            the hostname.
+     * @param session
+     *            the SSL session of the connection.
+     * @return {@code true} if the specified hostname is allowed, otherwise
+     *         {@code false}.
+     */
     boolean verify(String hostname, SSLSession session);
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HttpsURLConnection.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HttpsURLConnection.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HttpsURLConnection.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/HttpsURLConnection.java Thu Apr 30 11:01:28 2009
@@ -23,6 +23,10 @@
 import java.security.cert.Certificate;
 import java.security.cert.X509Certificate;
 
+/**
+ * This abstract subclass of {@code HttpURLConnection} defines methods for
+ * managing HTTPS connections according to the description given by RFC 2818.
+ */
 public abstract class HttpsURLConnection extends HttpURLConnection {
 
     private static HostnameVerifier defaultHostnameVerifier = new DefaultHostnameVerifier();
@@ -30,6 +34,14 @@
     private static SSLSocketFactory defaultSSLSocketFactory = (SSLSocketFactory) SSLSocketFactory
             .getDefault();
 
+    /**
+     * Sets the default hostname verifier to be used by new instances.
+     *
+     * @param v
+     *            the new default hostname verifier
+     * @throws IllegalArgumentException
+     *             if the specified verifier is {@code null}.
+     */
     public static void setDefaultHostnameVerifier(HostnameVerifier v) {
         if (v == null) {
             throw new IllegalArgumentException("HostnameVerifier is null");
@@ -37,10 +49,23 @@
         defaultHostnameVerifier = v;
     }
 
+    /**
+     * Returns the default hostname verifier.
+     *
+     * @return the default hostname verifier.
+     */
     public static HostnameVerifier getDefaultHostnameVerifier() {
         return defaultHostnameVerifier;
     }
 
+    /**
+     * Sets the default SSL socket factory to be used by new instances.
+     *
+     * @param sf
+     *            the new default SSL socket factory.
+     * @throws IllegalArgumentException
+     *             if the specified socket factory is {@code null}.
+     */
     public static void setDefaultSSLSocketFactory(SSLSocketFactory sf) {
         if (sf == null) {
             throw new IllegalArgumentException("SSLSocketFactory is null");
@@ -48,26 +73,80 @@
         defaultSSLSocketFactory = sf;
     }
 
+    /**
+     * Returns the default SSL socket factory for new instances.
+     *
+     * @return the default SSL socket factory for new instances.
+     */
     public static SSLSocketFactory getDefaultSSLSocketFactory() {
         return defaultSSLSocketFactory;
     }
 
+    /**
+     * The host name verifier used by this connection. It is initialized from
+     * the default hostname verifier
+     * {@link #setDefaultHostnameVerifier(HostnameVerifier)} or
+     * {@link #getDefaultHostnameVerifier()}.
+     */
     protected HostnameVerifier hostnameVerifier;
 
     private SSLSocketFactory sslSocketFactory;
 
+    /**
+     * Creates a new {@code HttpsURLConnection} with the specified {@code URL}.
+     *
+     * @param url
+     *            the {@code URL} to connect to.
+     */
     protected HttpsURLConnection(URL url) {
         super(url);
         hostnameVerifier = defaultHostnameVerifier;
         sslSocketFactory = defaultSSLSocketFactory;
     }
 
+    /**
+     * Returns the name of the cipher suite negotiated during the SSL handshake.
+     *
+     * @return the name of the cipher suite negotiated during the SSL handshake.
+     * @throws IllegalStateException
+     *             if no connection has been established yet.
+     */
     public abstract String getCipherSuite();
 
+    /**
+     * Returns the list of local certificates used during the handshake. These
+     * certificates were sent to the peer.
+     *
+     * @return Returns the list of certificates used during the handshake with
+     *         the local identity certificate followed by CAs, or {@code null}
+     *         if no certificates were used during the handshake.
+     * @throws IllegalStateException
+     *             if no connection has been established yet.
+     */
     public abstract Certificate[] getLocalCertificates();
 
+    /**
+     * Return the list of certificates identifying the peer during the
+     * handshake.
+     *
+     * @return the list of certificates identifying the peer with the peer's
+     *         identity certificate followed by CAs.
+     * @throws SSLPeerUnverifiedException
+     *             if the identity of the peer has not been verified..
+     * @throws IllegalStateException
+     *             if no connection has been established yet.
+     */
     public abstract Certificate[] getServerCertificates() throws SSLPeerUnverifiedException;
 
+    /**
+     * Returns the {@code Principal} identifying the peer.
+     *
+     * @return the {@code Principal} identifying the peer.
+     * @throws SSLPeerUnverifiedException
+     *             if the identity of the peer has not been verified.
+     * @throws IllegalStateException
+     *             if no connection has been established yet.
+     */
     public Principal getPeerPrincipal() throws SSLPeerUnverifiedException {
         Certificate[] certs = getServerCertificates();
         if (certs == null || certs.length == 0 || (!(certs[0] instanceof X509Certificate))) {
@@ -76,6 +155,14 @@
         return ((X509Certificate) certs[0]).getSubjectX500Principal();
     }
 
+    /**
+     * Returns the {@code Principal} used to identify the local host during the handshake.
+     *
+     * @return the {@code Principal} used to identify the local host during the handshake, or
+     *         {@code null} if none was used.
+     * @throws IllegalStateException
+     *             if no connection has been established yet.
+     */
     public Principal getLocalPrincipal() {
         Certificate[] certs = getLocalCertificates();
         if (certs == null || certs.length == 0 || (!(certs[0] instanceof X509Certificate))) {
@@ -84,6 +171,14 @@
         return ((X509Certificate) certs[0]).getSubjectX500Principal();
     }
 
+    /**
+     * Sets the hostname verifier for this instance.
+     *
+     * @param v
+     *            the hostname verifier for this instance.
+     * @throws IllegalArgumentException
+     *             if the specified verifier is {@code null}.
+     */
     public void setHostnameVerifier(HostnameVerifier v) {
         if (v == null) {
             throw new IllegalArgumentException("HostnameVerifier is null");
@@ -91,10 +186,23 @@
         hostnameVerifier = v;
     }
 
+    /**
+     * Returns the hostname verifier used by this instance.
+     *
+     * @return the hostname verifier used by this instance.
+     */
     public HostnameVerifier getHostnameVerifier() {
         return hostnameVerifier;
     }
 
+    /**
+     * Sets the SSL socket factory for this instance.
+     *
+     * @param sf
+     *            the SSL socket factory to be used by this instance.
+     * @throws IllegalArgumentException
+     *             if the specified socket factory is {@code null}.
+     */
     public void setSSLSocketFactory(SSLSocketFactory sf) {
         if (sf == null) {
             throw new IllegalArgumentException("SSLSocketFactory is null");
@@ -102,6 +210,11 @@
         sslSocketFactory = sf;
     }
 
+    /**
+     * Returns the SSL socket factory used by this instance.
+     *
+     * @return the SSL socket factory used by this instance.
+     */
     public SSLSocketFactory getSSLSocketFactory() {
         return sslSocketFactory;
     }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManager.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManager.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManager.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManager.java Thu Apr 30 11:01:28 2009
@@ -17,5 +17,11 @@
 
 package javax.net.ssl;
 
+/**
+ * This is the interface to implement in order to mark a class as a JSSE key
+ * managers so that key managers can be easily grouped. The key managers are
+ * responsible for handling the keys used to authenticate the local side to its
+ * peer,
+ */
 public interface KeyManager {
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManagerFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManagerFactory.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManagerFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManagerFactory.java Thu Apr 30 11:01:28 2009
@@ -30,6 +30,9 @@
 
 import org.apache.harmony.security.fortress.Engine;
 
+/**
+ * The public API for {@code KeyManagerFactory} implementations.
+ */
 public class KeyManagerFactory {
     // Store KeyManagerFactory service name
     private static final String SERVICE = "KeyManagerFactory";
@@ -40,6 +43,14 @@
     // Store default property name
     private static final String PROPERTY_NAME = "ssl.KeyManagerFactory.algorithm";
 
+    /**
+     * Returns the default key manager factory algorithm name.
+     * <p>
+     * The default algorithm name is specified by the security property:
+     * {@code 'ssl.KeyManagerFactory.algorithm'}.
+     *
+     * @return the default algorithm name.
+     */
     public static final String getDefaultAlgorithm() {
         return AccessController.doPrivileged(new PrivilegedAction<String>() {
             public String run() {
@@ -49,9 +60,17 @@
     }
 
     /**
-     * 
-     * @throws NullPointerException if algorithm is null (instead of NoSuchAlgorithmException as in
-     *             1.4 release)
+     * Creates a new {@code KeyManagerFactory} instance for the specified key
+     * management algorithm.
+     *
+     * @param algorithm
+     *            the name of the requested key management algorithm.
+     * @return a key manager factory for the requested algorithm.
+     * @throws NoSuchAlgorithmException
+     *             if no installed provider can provide the requested algorithm.
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null} (instead of
+     *             NoSuchAlgorithmException as in 1.4 release)
      */
     public static final KeyManagerFactory getInstance(String algorithm)
             throws NoSuchAlgorithmException {
@@ -66,8 +85,23 @@
     }
 
     /**
-     * @throws NullPointerException if algorithm is null (instead of NoSuchAlgorithmException as in
-     *             1.4 release)
+     * Creates a new {@code KeyManagerFactory} instance for the specified key
+     * management algorithm from the specified provider.
+     *
+     * @param algorithm
+     *            the name of the requested key management algorithm name.
+     * @param provider
+     *            the name of the provider that provides the requested
+     *            algorithm.
+     * @return a key manager factory for the requested algorithm.
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider cannot provide the requested
+     *             algorithm.
+     * @throws NoSuchProviderException
+     *             if the specified provider does not exist.
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null} (instead of
+     *             NoSuchAlgorithmException as in 1.4 release)
      */
     public static final KeyManagerFactory getInstance(String algorithm, String provider)
             throws NoSuchAlgorithmException, NoSuchProviderException {
@@ -82,8 +116,20 @@
     }
 
     /**
-     * @throws NullPointerException if algorithm is null (instead of NoSuchAlgorithmException as in
-     *             1.4 release)
+     * Creates a new {@code KeyManagerFactory} instance for the specified key
+     * management algorithm from the specified provider.
+     *
+     * @param algorithm
+     *            the name of the requested key management algorithm name.
+     * @param provider
+     *            the provider that provides the requested algorithm.
+     * @return a key manager factory for the requested algorithm.
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider cannot provide the requested
+     *             algorithm.
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null} (instead of
+     *             NoSuchAlgorithmException as in 1.4 release)
      */
     public static final KeyManagerFactory getInstance(String algorithm, Provider provider)
             throws NoSuchAlgorithmException {
@@ -108,6 +154,16 @@
     // Store used algorithm
     private final String algorithm;
 
+    /**
+     * Creates a new {@code KeyManagerFactory}.
+     *
+     * @param factorySpi
+     *            the implementation delegate.
+     * @param provider
+     *            the provider.
+     * @param algorithm
+     *            the key management algorithm name.
+     */
     protected KeyManagerFactory(KeyManagerFactorySpi factorySpi, Provider provider, String algorithm) {
         super();
         this.provider = provider;
@@ -115,23 +171,62 @@
         this.spiImpl = factorySpi;
     }
 
+    /**
+     * Returns the name of the key management algorithm.
+     *
+     * @return the name of the key management algorithm.
+     */
     public final String getAlgorithm() {
         return algorithm;
     }
 
+    /**
+     * Returns the provider for this {@code KeyManagerFactory} instance.
+     *
+     * @return the provider for this {@code KeyManagerFactory} instance.
+     */
     public final Provider getProvider() {
         return provider;
     }
 
+    /**
+     * Initializes this instance with the specified key store and password.
+     *
+     * @param ks
+     *            the key store or {@code null} to use the default key store.
+     * @param password
+     *            the password for the specified key store or {@code null} if no
+     *            key store is provided.
+     * @throws KeyStoreException
+     *             if initializing this key manager factory fails.
+     * @throws NoSuchAlgorithmException
+     *             if a required algorithm is not available.
+     * @throws UnrecoverableKeyException
+     *             if a key cannot be recovered.
+     */
     public final void init(KeyStore ks, char[] password) throws KeyStoreException,
             NoSuchAlgorithmException, UnrecoverableKeyException {
         spiImpl.engineInit(ks, password);
     }
 
+    /**
+     * Initializes this instance with the specified factory parameters.
+     *
+     * @param spec
+     *            the factory parameters.
+     * @throws InvalidAlgorithmParameterException
+     *             if an error occurs.
+     */
     public final void init(ManagerFactoryParameters spec) throws InvalidAlgorithmParameterException {
         spiImpl.engineInit(spec);
     }
 
+    /**
+     * Returns a list of key managers, one instance for each type of key in the
+     * key store.
+     *
+     * @return a list of key managers.
+     */
     public final KeyManager[] getKeyManagers() {
         return spiImpl.engineGetKeyManagers();
     }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManagerFactorySpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManagerFactorySpi.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManagerFactorySpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyManagerFactorySpi.java Thu Apr 30 11:01:28 2009
@@ -23,17 +23,52 @@
 import java.security.NoSuchAlgorithmException;
 import java.security.UnrecoverableKeyException;
 
+/**
+ * The <i>Service Provider Interface</i> (SPI) for the
+ * {@code KeyManagerFactory} class.
+ */
 public abstract class KeyManagerFactorySpi {
     
+    /**
+     * Creates a new {@code KeyManagerFactorySpi} instance.
+     */
     public KeyManagerFactorySpi() {
         super();
     }
 
+    /**
+     * Initializes this instance with the specified key store and password.
+     *
+     * @param ks
+     *            the key store or {@code null} to use the default key store.
+     * @param password
+     *            the key store password.
+     * @throws KeyStoreException
+     *             if initializing this instance fails.
+     * @throws NoSuchAlgorithmException
+     *             if a required algorithm is not available.
+     * @throws UnrecoverableKeyException
+     *             if a key cannot be recovered.
+     */
     protected abstract void engineInit(KeyStore ks, char[] password) throws KeyStoreException,
             NoSuchAlgorithmException, UnrecoverableKeyException;
 
+    /**
+     * Initializes this instance with the specified factory parameters.
+     *
+     * @param spec
+     *            the factory parameters.
+     * @throws InvalidAlgorithmParameterException
+     *             if an error occurs.
+     */
     protected abstract void engineInit(ManagerFactoryParameters spec)
             throws InvalidAlgorithmParameterException;
 
+    /**
+     * Returns a list of key managers, one instance for each type of key in the
+     * key store.
+     *
+     * @return a list of key managers.
+     */
     protected abstract KeyManager[] engineGetKeyManagers();
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyStoreBuilderParameters.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyStoreBuilderParameters.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyStoreBuilderParameters.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/KeyStoreBuilderParameters.java Thu Apr 30 11:01:28 2009
@@ -23,10 +23,10 @@
 import java.security.KeyStore;
 
 /**
- * A parameters object for {@link X509KeyManager}
- * 
+ * The parameters for {@code KeyManager}s. The parameters are a list of
+ * {@code KeyStore.Builder}s.
+ *
  * @since 1.5
- * @see X509KeyManager
  * @see KeyStore.Builder
  */
 public class KeyStoreBuilderParameters implements ManagerFactoryParameters {
@@ -34,9 +34,11 @@
     private final List<KeyStore.Builder> ksbuilders;
 
     /**
-     * Constructs an instance for the builder passed.
+     * Creates a new {@code KeyStoreBuilderParameters} with the specified key
+     * store builder.
      * 
-     * @param builder a builder
+     * @param builder
+     *            the key store builder.
      */
     public KeyStoreBuilderParameters(KeyStore.Builder builder) {
         super();
@@ -44,11 +46,13 @@
     }
 
     /**
-     * Constructs an instance for the builder list passed.
+     * Creates a new {@code KeyStoreBuilderParameters} with the specified list
+     * of {@code KeyStore.Builder}s.
      * 
-     * @param parameters the builder list
-     * @throws NullPointerException if {@code parameters} is {@code null}
-     * @throws IllegalArgumentException if {@code parameters} is empty
+     * @param parameters
+     *            the list of key store builders
+     * @throws IllegalArgumentException
+     *             if the specified list is empty.
      */
     @SuppressWarnings("unchecked")
     public KeyStoreBuilderParameters(List parameters) {
@@ -63,9 +67,10 @@
     }
 
     /**
-     * The list of builder parameters.
+     * Returns the unmodifiable list of {@code KeyStore.Builder}s associated
+     * with this parameters instance.
      * 
-     * @return an unmodifiable list of parameters
+     * @return the unmodifiable list of {@code KeyStore.Builder}s.
      */
     @SuppressWarnings("unchecked")
     public List getParameters() {

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/ManagerFactoryParameters.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/ManagerFactoryParameters.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/ManagerFactoryParameters.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/ManagerFactoryParameters.java Thu Apr 30 11:01:28 2009
@@ -18,8 +18,9 @@
 package javax.net.ssl;
 
 /**
- * Common interface for passing parameters to manager factory objects.
- * 
+ * The marker interface for key manager factory parameters. Its purpose is to
+ * group key manager factory parameters objects.
+ *
  * @since 1.4
  */
 public interface ManagerFactoryParameters {

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLContext.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLContext.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLContext.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLContext.java Thu Apr 30 11:01:28 2009
@@ -26,6 +26,11 @@
 
 import org.apache.harmony.security.fortress.Engine;
 
+
+/**
+ * The public API for secure socket protocol implementations. It acts as factory
+ * for {@code SSLSocketFactory}'s and {@code SSLEngine}s.
+ */
 public class SSLContext {
     // StoreSSLContext service name
     private static final String SERVICE = "SSLContext";
@@ -34,9 +39,16 @@
     private static Engine engine = new Engine(SERVICE);
 
     /**
-     * 
-     * @throws NullPointerException if protocol is null (instead of NoSuchAlgorithmException as in
-     *             1.4 release)
+     * Creates a new {@code SSLContext} instance for the specified protocol.
+     *
+     * @param protocol
+     *            the requested protocol to create a context for.
+     * @return the created {@code SSLContext} instance.
+     * @throws NoSuchAlgorithmException
+     *             if no installed provider can provide the requested protocol
+     * @throws NullPointerException
+     *             if {@code protocol} is {@code null} (instead of
+     *             NoSuchAlgorithmException as in 1.4 release)
      */
     public static SSLContext getInstance(String protocol) throws NoSuchAlgorithmException {
         if (protocol == null) {
@@ -49,9 +61,22 @@
     }
 
     /**
-     * 
-     * @throws NullPointerException if protocol is null (instead of NoSuchAlgorithmException as in
-     *             1.4 release)
+     * Creates a new {@code SSLContext} instance for the specified protocol from
+     * the specified provider.
+     *
+     * @param protocol
+     *            the requested protocol to create a context for.
+     * @param provider
+     *            the name of the provider that provides the requested protocol.
+     * @return an {@code SSLContext} for the requested protocol.
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider cannot provider the requested
+     *             protocol.
+     * @throws NoSuchProviderException
+     *             if the specified provider does not exits.
+     * @throws NullPointerException
+     *             if {@code protocol} is {@code null} (instead of
+     *             NoSuchAlgorithmException as in 1.4 release)
      */
     public static SSLContext getInstance(String protocol, String provider)
             throws NoSuchAlgorithmException, NoSuchProviderException {
@@ -69,8 +94,20 @@
     }
 
     /**
-     * @throws NullPointerException if protocol is null (instead of NoSuchAlgorithmException as in
-     *             1.4 release)
+     * Creates a new {@code SSLContext} instance for the specified protocol from
+     * the specified provider.
+     *
+     * @param protocol
+     *            the requested protocol to create a context for
+     * @param provider
+     *            the provider that provides the requested protocol.
+     * @return an {@code SSLContext} for the requested protocol.
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider cannot provide the requested
+     *             protocol.
+     * @throws NullPointerException
+     *             if {@code protocol} is {@code null} (instead of
+     *             NoSuchAlgorithmException as in 1.4 release)
      */
     public static SSLContext getInstance(String protocol, Provider provider)
             throws NoSuchAlgorithmException {
@@ -92,45 +129,124 @@
 
     private final String protocol;
 
+    /**
+     * Creates a new {@code SSLContext}.
+     *
+     * @param contextSpi
+     *            the implementation delegate.
+     * @param provider
+     *            the provider.
+     * @param protocol
+     *            the protocol name.
+     */
     protected SSLContext(SSLContextSpi contextSpi, Provider provider, String protocol) {
         this.provider = provider;
         this.protocol = protocol;
         this.spiImpl = contextSpi;
     }
 
+    /**
+     * Returns the name of the secure socket protocol of this instance.
+     *
+     * @return the name of the secure socket protocol of this instance.
+     */
     public final String getProtocol() {
         return protocol;
     }
 
+    /**
+     * Returns the provider of this {@code SSLContext} instance.
+     *
+     * @return the provider of this {@code SSLContext} instance.
+     */
     public final Provider getProvider() {
         return provider;
     }
 
+    /**
+     * Initializes this {@code SSLContext} instance. All of the arguments are
+     * optional, and the security providers will be searched for the required
+     * implementations of the needed algorithms.
+     *
+     * @param km
+     *            the key sources or {@code null}.
+     * @param tm
+     *            the trust decision sources or {@code null}.
+     * @param sr
+     *            the randomness source or {@code null.}
+     * @throws KeyManagementException
+     *             if initializing this instance fails.
+     */
     public final void init(KeyManager[] km, TrustManager[] tm, SecureRandom sr)
             throws KeyManagementException {
         spiImpl.engineInit(km, tm, sr);
     }
 
+    /**
+     * Returns a socket factory for this instance.
+     *
+     * @return a socket factory for this instance.
+     */
     public final SSLSocketFactory getSocketFactory() {
         return spiImpl.engineGetSocketFactory();
     }
 
+    /**
+     * Returns a server socket factory for this instance.
+     *
+     * @return a server socket factory for this instance.
+     */
     public final SSLServerSocketFactory getServerSocketFactory() {
         return spiImpl.engineGetServerSocketFactory();
     }
 
+    /**
+     * Creates an {@code SSLEngine} instance from this context.
+     *
+     * @return an {@code SSLEngine} instance from this context.
+     * @throws UnsupportedOperationException
+     *             if the provider does not support the operation.
+     */
     public final SSLEngine createSSLEngine() {
         return spiImpl.engineCreateSSLEngine();
     }
 
+    /**
+     * Creates an {@code SSLEngine} instance from this context with the
+     * specified hostname and port.
+     *
+     * @param peerHost
+     *            the name of the host
+     * @param peerPort
+     *            the port
+     * @return an {@code SSLEngine} instance from this context.
+     * @throws UnsupportedOperationException
+     *             if the provider does not support the operation.
+     */
     public final SSLEngine createSSLEngine(String peerHost, int peerPort) {
         return spiImpl.engineCreateSSLEngine(peerHost, peerPort);
     }
 
+    /**
+     * Returns the SSL session context that encapsulates the set of SSL sessions
+     * that can be used for handshake of server-side SSL sockets.
+     *
+     * @return the SSL server session context for this context or {@code null}
+     *         if the underlying provider does not provide an implementation of
+     *         the {@code SSLSessionContext} interface.
+     */
     public final SSLSessionContext getServerSessionContext() {
         return spiImpl.engineGetServerSessionContext();
     }
 
+    /**
+     * Returns the SSL session context that encapsulates the set of SSL sessions
+     * that can be used for handshake of client-side SSL sockets.
+     *
+     * @return the SSL client session context for this context or {@code null}
+     *         if the underlying provider does not provide an implementation of
+     *         the {@code SSLSessionContext} interface.
+     */
     public final SSLSessionContext getClientSessionContext() {
         return spiImpl.engineGetClientSessionContext();
     }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLContextSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLContextSpi.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLContextSpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLContextSpi.java Thu Apr 30 11:01:28 2009
@@ -20,24 +20,90 @@
 import java.security.KeyManagementException;
 import java.security.SecureRandom;
 
+/**
+ * The <i>Service Provider Interface</i> (SPI) for the {@code SSLContext} class.
+ */
 public abstract class SSLContextSpi {
+
+    /**
+     * Creates a new {@code SSLContextSpi} instance.
+     */
     public SSLContextSpi() {
         super();
     }
 
+    /**
+     * Initializes this {@code SSLContext} instance. All of the arguments are
+     * optional, and the security providers will be searched for the required
+     * implementations of the needed algorithms.
+     *
+     * @param km
+     *            the key sources or {@code null}.
+     * @param tm
+     *            the trust decision sources or {@code null}.
+     * @param sr
+     *            the randomness source or {@code null.}
+     * @throws KeyManagementException
+     *             if initializing this instance fails.
+     */
     protected abstract void engineInit(KeyManager[] km, TrustManager[] tm, SecureRandom sr)
             throws KeyManagementException;
 
+    /**
+     * Returns a socket factory for this instance.
+     *
+     * @return a socket factory for this instance.
+     */
     protected abstract SSLSocketFactory engineGetSocketFactory();
 
+    /**
+     * Returns a server socket factory for this instance.
+     *
+     * @return a server socket factory for this instance.
+     */
     protected abstract SSLServerSocketFactory engineGetServerSocketFactory();
 
+    /**
+     * Creates an {@code SSLEngine} instance from this context with the
+     * specified hostname and port.
+     *
+     * @param host
+     *            the name of the host
+     * @param port
+     *            the port
+     * @return an {@code SSLEngine} instance from this context.
+     * @throws UnsupportedOperationException
+     *             if the provider does not support the operation.
+     */
     protected abstract SSLEngine engineCreateSSLEngine(String host, int port);
 
+    /**
+     * Creates an {@code SSLEngine} instance from this context.
+     *
+     * @return an {@code SSLEngine} instance from this context.
+     * @throws UnsupportedOperationException
+     *             if the provider does not support the operation.
+     */
     protected abstract SSLEngine engineCreateSSLEngine();
 
+    /**
+     * Returns the SSL session context that encapsulates the set of SSL sessions
+     * that can be used for the server side of the SSL handshake.
+     *
+     * @return the SSL server session context for this context or {@code null}
+     *         if the underlying provider does not provide an implementation of
+     *         the {@code SSLSessionContext} interface.
+     */
     protected abstract SSLSessionContext engineGetServerSessionContext();
 
+    /**
+     * Returns the SSL session context that encapsulates the set of SSL sessions
+     * that can be used for the client side of the SSL handshake.
+     *
+     * @return the SSL client session context for this context or {@code null}
+     *         if the underlying provider does not provide an implementation of
+     *         the {@code SSLSessionContext} interface.
+     */
     protected abstract SSLSessionContext engineGetClientSessionContext();
 
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLEngine.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLEngine.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLEngine.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLEngine.java Thu Apr 30 11:01:28 2009
@@ -20,8 +20,10 @@
 import java.nio.ByteBuffer;
 
 /**
- * An engine for securing communication via SSL, TLS and other protocols.
- * 
+ * The abstract implementation of secure communications using SSL, TLS, or other
+ * protocols. It includes the setup, handshake, and encrypt/decrypt
+ * functionality needed to create a secure connection.
+ *
  * @since 1.5
  */
 public abstract class SSLEngine {
@@ -29,7 +31,7 @@
     private final int peerPort;
 
     /**
-     * Constructs an instance without any peer host information.
+     * Creates a new {@code SSLEngine} instance.
      */
     protected SSLEngine() {
         super();
@@ -38,10 +40,13 @@
     }
 
     /**
-     * Constructs an instance with the given peer host and port.
-     * 
-     * @param host name of the peer host
-     * @param port value of the port of the peer host
+     * Creates a new {@code SSLEngine} instance with the specified host and
+     * port.
+     *
+     * @param host
+     *            the name of the host.
+     * @param port
+     *            the port of the host.
      */
     protected SSLEngine(String host, int port) {
         super();
@@ -49,78 +54,355 @@
         this.peerPort = port;
     }
 
+    /**
+     * Returns the name of the peer host.
+     *
+     * @return the name of the peer host, or {@code null} if none is available.
+     */
     public String getPeerHost() {
         return peerHost;
     }
 
+    /**
+     * Returns the port number of the peer host.
+     *
+     * @return the port number of the peer host, or {@code -1} is none is
+     *         available.
+     */
     public int getPeerPort() {
         return peerPort;
     }
 
+    /**
+     * Initiates a handshake on this engine.
+     * <p>
+     * Calling this method is not needed for the initial handshake: it will be
+     * called by {@code wrap} or {@code unwrap} if the initial handshake has not
+     * been started yet.
+     *
+     * @throws SSLException
+     *             if starting the handshake fails.
+     * @throws IllegalStateException
+     *             if the engine does not have all the needed settings (e.g.
+     *             client/server mode not set).
+     */
     public abstract void beginHandshake() throws SSLException;
 
+    /**
+     * Notifies this engine instance that no more inbound network data will be
+     * sent to this engine.
+     *
+     * @throws SSLException
+     *             if this engine did not receive a needed protocol specific
+     *             close notification message from the peer.
+     */
     public abstract void closeInbound() throws SSLException;
 
+    /**
+     * Notifies this engine instance that no more outbound application data will
+     * be sent to this engine.
+     */
     public abstract void closeOutbound();
 
+    /**
+     * Returns a delegate task for this engine instance. Some engine operations
+     * may require the results of blocking or long running operations, and the
+     * {@code SSLEngineResult} instances returned by this engine may indicate
+     * that a delegated task result is needed. In this case the
+     * {@link Runnable#run() run} method of the returned {@code Runnable}
+     * delegated task must be called.
+     *
+     * @return a delegate task, or {@code null} if none are available.
+     */
     public abstract Runnable getDelegatedTask();
 
+    /**
+     * Returns the SSL cipher suite names that are enabled in this engine
+     * instance.
+     *
+     * @return the SSL cipher suite names that are enabled in this engine
+     *         instance.
+     */
     public abstract String[] getEnabledCipherSuites();
 
+    /**
+     * Returns the protocol version names that are enabled in this engine
+     * instance.
+     *
+     * @return the protocol version names that are enabled in this engine
+     *         instance.
+     */
     public abstract String[] getEnabledProtocols();
 
+    /**
+     * Returns whether new SSL sessions may be established by this engine.
+     *
+     * @return {@code true} if new session may be established, {@code false} if
+     *         existing sessions must be reused.
+     */
     public abstract boolean getEnableSessionCreation();
 
+    /**
+     * Returns the status of the handshake of this engine instance.
+     *
+     * @return the status of the handshake of this engine instance.
+     */
     public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus();
 
+    /**
+     * Returns whether this engine instance will require client authentication.
+     *
+     * @return {@code true} if this engine will require client authentication,
+     *         {@code false} if no client authentication is needed.
+     */
     public abstract boolean getNeedClientAuth();
 
+    /**
+     * Returns the SSL session for this engine instance.
+     *
+     * @return the SSL session for this engine instance.
+     */
     public abstract SSLSession getSession();
 
+    /**
+     * Returns the SSL cipher suite names that are supported by this engine.
+     * These cipher suites can be enabled using
+     * {@link #setEnabledCipherSuites(String[])}.
+     *
+     * @return the SSL cipher suite names that are supported by this engine.
+     */
     public abstract String[] getSupportedCipherSuites();
 
+    /**
+     * Returns the protocol names that are supported by this engine. These
+     * protocols can be enables using {@link #setEnabledProtocols(String[])}.
+     *
+     * @return the protocol names that are supported by this engine.
+     */
     public abstract String[] getSupportedProtocols();
 
+    /**
+     * Returns whether this engine is set to act in client mode when
+     * handshaking.
+     *
+     * @return {@code true} if the engine is set to do handshaking in client
+     *         mode.
+     */
     public abstract boolean getUseClientMode();
 
+    /**
+     * Returns whether this engine will request client authentication.
+     *
+     * @return {@code true} if client authentication will be requested,
+     *         {@code false} otherwise.
+     */
     public abstract boolean getWantClientAuth();
 
+    /**
+     * Returns whether no more inbound data will be accepted by this engine.
+     *
+     * @return {@code true} if no more inbound data will be accepted by this
+     *         engine, {@code false} otherwise.
+     */
     public abstract boolean isInboundDone();
 
+    /**
+     * Returns whether no more outbound data will be produced by this engine.
+     *
+     * @return {@code true} if no more outbound data will be producted by this
+     *         engine, {@code otherwise} false.
+     */
     public abstract boolean isOutboundDone();
 
+    /**
+     * Sets the SSL cipher suite names that should be enabled in this engine
+     * instance. Only cipher suites listed by {@code getSupportedCipherSuites()}
+     * are allowed.
+     *
+     * @param suites
+     *            the SSL cipher suite names to be enabled.
+     * @throws IllegalArgumentException
+     *             if one of the specified cipher suites is not supported, or if
+     *             {@code suites} is {@code null}.
+     */
     public abstract void setEnabledCipherSuites(String[] suites);
 
+    /**
+     * Sets the protocol version names that should be enabled in this engine
+     * instance. Only protocols listed by {@code getSupportedProtocols()} are
+     * allowed.
+     *
+     * @param protocols
+     *            the protocol version names to be enabled.
+     * @throws IllegalArgumentException
+     *             if one of the protocol version names is not supported, or if
+     *             {@code protocols} is {@code null}.
+     */
     public abstract void setEnabledProtocols(String[] protocols);
 
+    /**
+     * Sets whether new SSL sessions may be established by this engine instance.
+     *
+     * @param flag
+     *            {@code true} if new SSL sessions may be established,
+     *            {@code false} if existing SSL sessions must be reused.
+     */
     public abstract void setEnableSessionCreation(boolean flag);
 
+    /**
+     * Sets whether this engine must require client authentication. The client
+     * authentication is one of:
+     * <ul>
+     * <li>authentication required</li>
+     * <li>authentication requested</li>
+     * <li>no authentication needed</li>
+     * </ul>
+     * This method overrides the setting of {@link #setWantClientAuth(boolean)}.
+     *
+     * @param need
+     *            {@code true} if client authentication is required,
+     *            {@code false} if no authentication is needed.
+     */
     public abstract void setNeedClientAuth(boolean need);
 
+    /**
+     * Sets whether this engine should act in client (or server) mode when
+     * handshaking.
+     *
+     * @param mode
+     *            {@code true} if this engine should act in client mode,
+     *            {@code false} if not.
+     * @throws IllegalArgumentException
+     *             if this method is called after starting the initial
+     *             handshake.
+     */
     public abstract void setUseClientMode(boolean mode);
 
+    /**
+     * Sets whether this engine should request client authentication. The client
+     * authentication is one of the following:
+     * <ul>
+     * <li>authentication required</li>
+     * <li>authentication requested</li>
+     * <li>no authentication needed</li>
+     * </ul>
+     * This method overrides the setting of {@link #setNeedClientAuth(boolean)}.
+     *
+     * @param want
+     *            {@code true} if client authentication should be requested,
+     *            {@code false} if no authentication is needed.
+     */
     public abstract void setWantClientAuth(boolean want);
 
+    /**
+     * Decodes the incoming network data buffer into application data buffers.
+     * If a handshake has not been started yet, it will automatically be
+     * started.
+     *
+     * @param src
+     *            the buffer with incoming network data
+     * @param dsts
+     *            the array of destination buffers for incoming application
+     *            data.
+     * @param offset
+     *            the offset in the array of destination buffers to which data
+     *            is to be transferred.
+     * @param length
+     *            the maximum number of destination buffers to be used.
+     * @return the result object of this operation.
+     * @throws SSLException
+     *             if a problem occurred while processing the data.
+     * @throws IndexOutOfBoundsException
+     *             if {@code length} is greater than
+     *             {@code dsts.length - offset}.
+     * @throws java.nio.ReadOnlyBufferException
+     *             if one of the destination buffers is read-only.
+     * @throws IllegalArgumentException
+     *             if {@code src}, {@code dsts}, or one of the entries in
+     *             {@code dsts} is {@code null}.
+     * @throws IllegalStateException
+     *             if the engine does not have all the needed settings (e.g.
+     *             client/server mode not set).
+     */
     public abstract SSLEngineResult unwrap(ByteBuffer src, ByteBuffer[] dsts, int offset, int length)
             throws SSLException;
 
+    /**
+     * Encodes the outgoing application data buffers into the network data
+     * buffer. If a handshake has not been started yet, it will automatically be
+     * started.
+     *
+     * @param srcs
+     *            the array of source buffers of outgoing application data.
+     * @param offset
+     *            the offset in the array of source buffers from which data is
+     *            to be retrieved.
+     * @param length
+     *            the maximum number of source buffers to be used.
+     * @param dst
+     *            the destination buffer for network data.
+     * @return the result object of this operation.
+     * @throws SSLException
+     *             if a problem occurred while processing the data.
+     * @throws IndexOutOfBoundsException
+     *             if {@code length} is greater than
+     *             {@code srcs.length - offset}.
+     * @throws java.nio.ReadOnlyBufferException
+     *             if the destination buffer is readonly.
+     * @throws IllegalArgumentException
+     *             if {@code srcs}, {@code dst}, or one the entries in
+     *             {@code srcs} is {@code null}.
+     * @throws IllegalStateException
+     *             if the engine does not have all the needed settings (e.g.
+     *             client/server mode not set).
+     */
     public abstract SSLEngineResult wrap(ByteBuffer[] srcs, int offset, int length, ByteBuffer dst)
             throws SSLException;
 
     /**
-     * implementation behavior follows RI: jdk 1.5 does not throw IllegalArgumentException when
-     * parameters are null and does not throw ReadOnlyBufferException if dst is read only byte
-     * buffer
+     * Decodes the incoming network data buffer into the application data
+     * buffer. If a handshake has not been started yet, it will automatically be
+     * started.
      * 
+     * @param src
+     *            the buffer with incoming network data
+     * @param dst
+     *            the destination buffer for incoming application data.
+     * @return the result object of this operation.
+     * @throws SSLException
+     *             if a problem occurred while processing the data.
+     * @throws java.nio.ReadOnlyBufferException
+     *             if one of the destination buffers is read-only.
+     * @throws IllegalArgumentException
+     *             if {@code src} or {@code dst} is {@code null}.
+     * @throws IllegalStateException
+     *             if the engine does not have all the needed settings (e.g.
+     *             client/server mode not set).
      */
     public SSLEngineResult unwrap(ByteBuffer src, ByteBuffer dst) throws SSLException {
         return unwrap(src, new ByteBuffer[] { dst }, 0, 1);
     }
 
     /**
-     * implementation behavior follows RI: jdk 1.5 does not throw IllegalArgumentException when src
-     * is null or if dsts contains null elements It does not throw ReadOnlyBufferException when dsts
-     * contains read only elements
+     * Decodes the incoming network data buffer into the application data
+     * buffers. If a handshake has not been started yet, it will automatically
+     * be started.
+     *
+     * @param src
+     *            the buffer with incoming network data
+     * @param dsts
+     *            the array of destination buffers for incoming application
+     *            data.
+     * @return the result object of this operation.
+     * @throws SSLException
+     *             if a problem occurred while processing the data.
+     * @throws java.nio.ReadOnlyBufferException
+     *             if one of the destination buffers is read-only.
+     * @throws IllegalArgumentException
+     *             if {@code src} or {@code dsts} is {@code null}.
+     * @throws IllegalStateException
+     *             if the engine does not have all the needed settings (e.g.
+     *             client/server mode not set).
      */
     public SSLEngineResult unwrap(ByteBuffer src, ByteBuffer[] dsts) throws SSLException {
         if (dsts == null) {
@@ -130,10 +412,24 @@
     }
 
     /**
-     * implementation behavior follows RI: jdk 1.5 does not throw IllegalArgumentException when dst
-     * is null or if srcs contains null elements It does not throw ReadOnlyBufferException for read
-     * only dst
+     * Encodes the outgoing application data buffers into the network data
+     * buffer. If a handshake has not been started yet, it will automatically be
+     * started.
      * 
+     * @param srcs
+     *            the array of source buffers of outgoing application data.
+     * @param dst
+     *            the destination buffer for network data.
+     * @return the result object of this operation.
+     * @throws SSLException
+     *             if a problem occurred while processing the data.
+     * @throws java.nio.ReadOnlyBufferException
+     *             if the destination buffer is readonly.
+     * @throws IllegalArgumentException
+     *             if {@code srcs} or {@code dst} is {@code null}.
+     * @throws IllegalStateException
+     *             if the engine does not have all the needed settings (e.g.
+     *             client/server mode not set).
      */
     public SSLEngineResult wrap(ByteBuffer[] srcs, ByteBuffer dst) throws SSLException {
         if (srcs == null) {
@@ -143,10 +439,24 @@
     }
 
     /**
-     * implementation behavior follows RI: jdk 1.5 does not throw IllegalArgumentException when
-     * parameters are null and does not throw ReadOnlyBufferException if dst is read only byte
-     * buffer
+     * Encodes the outgoing application data buffer into the network data
+     * buffer. If a handshake has not been started yet, it will automatically be
+     * started.
      * 
+     * @param src
+     *            the source buffers of outgoing application data.
+     * @param dst
+     *            the destination buffer for network data.
+     * @return the result object of this operation.
+     * @throws SSLException
+     *             if a problem occurred while processing the data.
+     * @throws java.nio.ReadOnlyBufferException
+     *             if the destination buffer is readonly.
+     * @throws IllegalArgumentException
+     *             if {@code src} or {@code dst} is {@code null}.
+     * @throws IllegalStateException
+     *             if the engine does not have all the needed settings (e.g.
+     *             client/server mode not set).
      */
     public SSLEngineResult wrap(ByteBuffer src, ByteBuffer dst) throws SSLException {
         return wrap(new ByteBuffer[] { src }, 0, 1, dst);

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLEngineResult.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLEngineResult.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLEngineResult.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLEngineResult.java Thu Apr 30 11:01:28 2009
@@ -17,14 +17,65 @@
 
 package javax.net.ssl;
 
+/**
+ * The result object describing the state of the {@code SSLEngine} produced
+ * by the {@code wrap()} and {@code unwrap()} operations.
+ */
 public class SSLEngineResult {
 
+    /**
+     * The {@code enum} describing the state of the current handshake.
+     */
     public enum HandshakeStatus {
-        NOT_HANDSHAKING, FINISHED, NEED_TASK, NEED_WRAP, NEED_UNWRAP
-    }
-
+        /**
+         * No handshake in progress.
+         */
+        NOT_HANDSHAKING,
+        /**
+         * The handshake is finished.
+         */
+        FINISHED,
+        /**
+         * The results of one (or more) delegated tasks are needed to continue
+         * the handshake.
+         */
+        NEED_TASK,
+        /**
+         * The engine must send data to the remote side to continue the
+         * handshake.
+         */
+        NEED_WRAP,
+        /**
+         * The engine needs to receive data from the remote side to continue the
+         * handshake.
+         */
+        NEED_UNWRAP
+    }
+
+    /**
+     * The {@code enum} describing the result of the {@code SSLEngine}
+     * operation.
+     */
     public static enum Status {
-        BUFFER_OVERFLOW, BUFFER_UNDERFLOW, CLOSED, OK
+        /**
+         * The size of the destination buffer is too small to hold the result of
+         * the current operation.
+         */
+        BUFFER_OVERFLOW,
+        /**
+         * There were not enough bytes available in the source buffer to
+         * complete the current operation.
+         */
+        BUFFER_UNDERFLOW,
+        /**
+         * The operation closed this side of the communication or was already
+         * closed.
+         */
+        CLOSED,
+        /**
+         * The operation completed successfully.
+         */
+        OK
     }
 
     // Store Status object
@@ -39,6 +90,23 @@
     // Store bytesProduced
     private final int bytesProduced;
 
+    /**
+     * Creates a new {@code SSLEngineResult} instance with the specified state
+     * values.
+     *
+     * @param status
+     *            the return value of the {@code SSLEngine} operation.
+     * @param handshakeStatus
+     *            the status of the current handshake
+     * @param bytesConsumed
+     *            the number of bytes retrieved from the source buffer(s).
+     * @param bytesProduced
+     *            the number of bytes transferred to the destination buffer(s).
+     * @throws IllegalArgumentException
+     *             if {@code status} or {@code handshakeStatus} is {@code null},
+     *             or if {@code bytesConsumed} or {@code bytesProduces} are
+     *             negative.
+     */
     public SSLEngineResult(SSLEngineResult.Status status,
             SSLEngineResult.HandshakeStatus handshakeStatus, int bytesConsumed, int bytesProduced) {
         if (status == null) {
@@ -59,18 +127,38 @@
         this.bytesProduced = bytesProduced;
     }
 
+    /**
+     * Returns the return value of the {@code SSLEngine} operation.
+     *
+     * @return the return value of the {@code SSLEngine} operation.
+     */
     public final Status getStatus() {
         return status;
     }
 
+    /**
+     * Returns the status of the current handshake.
+     *
+     * @return the status of the current handshake.
+     */
     public final HandshakeStatus getHandshakeStatus() {
         return handshakeStatus;
     }
 
+    /**
+     * Returns the number of bytes retrieved from the source buffer(s).
+     *
+     * @return the number of bytes retrieved from the source buffer(s).
+     */
     public final int bytesConsumed() {
         return bytesConsumed;
     }
 
+    /**
+     * Returns the number of bytes transferred to the destination buffer(s).
+     *
+     * @return the number of bytes transferred to the destination buffer(s).
+     */
     public final int bytesProduced() {
         return bytesProduced;
     }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLException.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLException.java Thu Apr 30 11:01:28 2009
@@ -19,18 +19,41 @@
 
 import java.io.IOException;
 
+/**
+ * The base class for all SSL related exceptions.
+ */
 public class SSLException extends IOException {
     private static final long serialVersionUID = 4511006460650708967L;
 
+    /**
+     * Creates a new {@code SSLException} with the specified reason.
+     *
+     * @param reason
+     *            the reason for the exception.
+     */
     public SSLException(String reason) {
         super(reason);
     }
 
+    /**
+     * Creates a new {@code SSLException} with the specified message and cause.
+     *
+     * @param message
+     *            the detail message for the exception.
+     * @param cause
+     *            the cause.
+     */
     public SSLException(String message, Throwable cause) {
         super(message);
         super.initCause(cause);
     }
 
+    /**
+     * Creates a new {@code SSLException} with the specified cause.
+     *
+     * @param cause
+     *            the cause
+     */
     public SSLException(Throwable cause) {
         super(cause == null ? null : cause.toString());
         super.initCause(cause);

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLHandshakeException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLHandshakeException.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLHandshakeException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLHandshakeException.java Thu Apr 30 11:01:28 2009
@@ -17,10 +17,20 @@
 
 package javax.net.ssl;
 
+/**
+ * The exception that is thrown when a handshake could not be completed
+ * successfully.
+ */
 public class SSLHandshakeException extends SSLException {
 
     private static final long serialVersionUID = -5045881315018326890L;
 
+    /**
+     * Creates a new {@code SSLHandshakeException} with the specified message.
+     *
+     * @param reason
+     *            the detail message for the exception.
+     */
     public SSLHandshakeException(String reason) {
         super(reason);
     }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLKeyException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLKeyException.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLKeyException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLKeyException.java Thu Apr 30 11:01:28 2009
@@ -17,10 +17,19 @@
 
 package javax.net.ssl;
 
+/**
+ * The exception that is thrown when an invalid SSL key is encountered.
+ */
 public class SSLKeyException extends SSLException {
 
     private static final long serialVersionUID = -8071664081941937874L;
 
+    /**
+     * Creates a new {@code SSLKeyException} with the specified message.
+     *
+     * @param reason
+     *            the detail message for the exception.
+     */
     public SSLKeyException(String reason) {
         super(reason);
     }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLPeerUnverifiedException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLPeerUnverifiedException.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLPeerUnverifiedException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLPeerUnverifiedException.java Thu Apr 30 11:01:28 2009
@@ -17,10 +17,21 @@
 
 package javax.net.ssl;
 
+/**
+ * The exception that is thrown when the identity of a peer has not beed
+ * verified.
+ */
 public class SSLPeerUnverifiedException extends SSLException {
 
     private static final long serialVersionUID = -8919512675000600547L;
 
+    /**
+     * Creates a new {@code SSLPeerUnverifiedException} with the specified
+     * message.
+     *
+     * @param reason
+     *            the detail message for the exception.
+     */
     public SSLPeerUnverifiedException(String reason) {
         super(reason);
     }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLPermission.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLPermission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLPermission.java Thu Apr 30 11:01:28 2009
@@ -19,14 +19,39 @@
 
 import java.security.BasicPermission;
 
+/**
+ * The class representing a network permission.
+ * <p>
+ * The following permissions are defined, allowing the specified action:
+ * <dl>
+ * <dt> {@code "setHostnameVerifier"} </dt>
+ * <dd> setting a callback object for additional verification of a hostname mismatch.</dd>
+ * <dt> {@code "getSSLSessionContext"} </dt>
+ * <dd> getting the {@code SSLSessionContext} of an {@code SSLSession}.</dd>
+ * </dl>
+ */
 public final class SSLPermission extends BasicPermission {
 
     private static final long serialVersionUID = -3456898025505876775L;
 
+    /**
+     * Creates a new {@code SSLPermission} with the specified name.
+     *
+     * @param name
+     *            the permission name.
+     */
     public SSLPermission(String name) {
         super(name);
     }
 
+    /**
+     * Creates a new {@code SSLPermission} with the specified name.
+     *
+     * @param name
+     *            the permission name.
+     * @param actions
+     *            is ignored and should be {@code null}.
+     */
     public SSLPermission(String name, String actions) {
         super(name, actions);
     }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLProtocolException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLProtocolException.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLProtocolException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLProtocolException.java Thu Apr 30 11:01:28 2009
@@ -17,10 +17,20 @@
 
 package javax.net.ssl;
 
+/**
+ * The exception that is thrown when an error in the operation of the SSL
+ * protocol is encountered.
+ */
 public class SSLProtocolException extends SSLException {
 
     private static final long serialVersionUID = 5445067063799134928L;
 
+    /**
+     * Creates a new {@code SSLProtocolException} with the specified message.
+     *
+     * @param reason
+     *            the detail message for the exception.
+     */
     public SSLProtocolException(String reason) {
         super(reason);
     }



Mime
View raw message