harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770159 [2/2] - in /harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net: ./ ssl/
Date Thu, 30 Apr 2009 11:01:29 GMT
Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocket.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocket.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocket.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocket.java Thu Apr 30 11:01:28 2009
@@ -21,49 +21,212 @@
 import java.net.InetAddress;
 import java.net.ServerSocket;
 
+/**
+ * The extension of {@code ServerSocket} which provides secure server sockets
+ * based on protocols like SSL, TLS, or others.
+ */
 public abstract class SSLServerSocket extends ServerSocket {
 
+    /**
+     * Only to be used by subclasses.
+     * <p>
+     * Creates a TCP server socket with the default authentication context.
+     *
+     * @throws IOException
+     *             if creating the socket fails.
+     */
     protected SSLServerSocket() throws IOException {
         super();
     }
 
+    /**
+     * Only to be used by subclasses.
+     * <p>
+     * Creates a TCP server socket on the specified port with the default
+     * authentication context. The connection's default backlog size is 50
+     * connections.
+     * @param port
+     *            the port to listen on.
+     * @throws IOException
+     *             if creating the socket fails.
+     */
     protected SSLServerSocket(int port) throws IOException {
         super(port);
     }
 
+    /**
+     * Only to be used by subclasses.
+     * <p>
+     * Creates a TCP server socket on the specified port using the specified
+     * backlog and the default authentication context.
+     *
+     * @param port
+     *            the port to listen on.
+     * @param backlog
+     *            the number of pending connections to queue.
+     * @throws IOException
+     *             if creating the socket fails.
+     */
     protected SSLServerSocket(int port, int backlog) throws IOException {
         super(port, backlog);
     }
 
+    /**
+     * Only to be used by subclasses.
+     * <p>
+     * Creates a TCP server socket on the specified port, using the specified
+     * backlog, listening on the specified interface, and using the default
+     * authentication context.
+     *
+     * @param port
+     *            the port the listen on.
+     * @param backlog
+     *            the number of pending connections to queue.
+     * @param address
+     *            the address of the interface to accept connections on.
+     * @throws IOException
+     *             if creating the socket fails.
+     */
     protected SSLServerSocket(int port, int backlog, InetAddress address) throws IOException {
         super(port, backlog, address);
     }
 
+    /**
+     * Returns the names of the enabled cipher suites to be used for new
+     * connections.
+     *
+     * @return the names of the enabled cipher suites to be used for new
+     *         connections.
+     */
     public abstract String[] getEnabledCipherSuites();
 
+    /**
+     * Sets the names of the cipher suites to be enabled for new connections.
+     * Only cipher suites returned by {@link #getSupportedCipherSuites()} are
+     * allowed.
+     *
+     * @param suites
+     *            the names of the to be enabled cipher suites.
+     * @throws IllegalArgumentException
+     *             if one of the cipher suite names is not supported.
+     */
     public abstract void setEnabledCipherSuites(String[] suites);
 
+    /**
+     * Returns the names of the supported cipher suites.
+     *
+     * @return the names of the supported cipher suites.
+     */
     public abstract String[] getSupportedCipherSuites();
 
+    /**
+     * Returns the names of the supported protocols.
+     *
+     * @return the names of the supported protocols.
+     */
     public abstract String[] getSupportedProtocols();
 
+    /**
+     * Returns the names of the enabled protocols to be used for new
+     * connections.
+     *
+     * @return the names of the enabled protocols to be used for new
+     *         connections.
+     */
     public abstract String[] getEnabledProtocols();
 
+    /**
+     * Sets the names of the protocols to be enabled for new connections. Only
+     * protocols returned by {@link #getSupportedProtocols()} are allowed.
+     *
+     * @param protocols
+     *            the names of the to be enabled protocols.
+     * @throws IllegalArgumentException
+     *             if one of the protocols is not supported.
+     */
     public abstract void setEnabledProtocols(String[] protocols);
 
+    /**
+     * Sets whether server-mode connections will be configured to require 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 #setWantClientAuth(boolean)}.
+     *
+     * @param need
+     *            {@code true} if client authentication is required,
+     *            {@code false} if no authentication is needed.
+     */
     public abstract void setNeedClientAuth(boolean need);
 
+    /**
+     * Returns whether server-mode connections will be configured to require
+     * client authentication.
+     *
+     * @return {@code true} if client authentication is required, {@code false}
+     *         if no client authentication is needed.
+     */
     public abstract boolean getNeedClientAuth();
 
+    /**
+     * Sets whether server-mode connections will be configured to 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);
 
+    /**
+     * Returns whether server-mode connections will be configured to request
+     * client authentication.
+     *
+     * @return {@code true} is client authentication will be requested,
+     *         {@code false} if no client authentication is needed.
+     */
     public abstract boolean getWantClientAuth();
 
+    /**
+     * Sets whether new connections should act in client mode when handshaking.
+     *
+     * @param mode
+     *            {@code true} if new connections should act in client mode,
+     *            {@code false} if not.
+     */
     public abstract void setUseClientMode(boolean mode);
 
+    /**
+     * Returns whether new connection will act in client mode when handshaking.
+     *
+     * @return {@code true} if new connections will act in client mode when
+     *         handshaking, {@code false} if not.
+     */
     public abstract boolean getUseClientMode();
 
+    /**
+     * Sets whether new SSL sessions may be established for new connections.
+     *
+     * @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);
 
+    /**
+     * Returns whether new SSL sessions may be established for new connections.
+     *
+     * @return {@code true} if new SSL sessions may be established,
+     *         {@code false} if existing SSL sessions must be reused.
+     */
     public abstract boolean getEnableSessionCreation();
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocketFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocketFactory.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocketFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLServerSocketFactory.java Thu Apr 30 11:01:28 2009
@@ -23,6 +23,9 @@
 
 import javax.net.ServerSocketFactory;
 
+/**
+ * The factory for SSL server sockets.
+ */
 public abstract class SSLServerSocketFactory extends ServerSocketFactory {
     // TODO EXPORT CONTROL
 
@@ -31,6 +34,13 @@
 
     private static String defaultName;
 
+    /**
+     * Returns the default {@code SSLServerSocketFactory} instance. The default
+     * implementation is defined by the security property
+     * "ssl.ServerSocketFactory.provider".
+     *
+     * @return the default {@code SSLServerSocketFactory} instance.
+     */
     public static synchronized ServerSocketFactory getDefault() {
         if (defaultServerSocketFactory != null) {
             return defaultServerSocketFactory;
@@ -69,11 +79,25 @@
         return defaultServerSocketFactory;
     }
 
+    /**
+     * Creates a new {@code SSLServerSocketFactory} instance.
+     */
     protected SSLServerSocketFactory() {
         super();
     }
 
+    /**
+     * Returns the names of the cipher suites that are enabled by default.
+     *
+     * @return the names of the cipher suites that are enabled by default
+     */
     public abstract String[] getDefaultCipherSuites();
 
+    /**
+     * Returns the list of supported cipher suites that could be enabled for an
+     * SSL connection created by this factory.
+     *
+     * @return the list of supported cipher suites
+     */
     public abstract String[] getSupportedCipherSuites();
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSession.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSession.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSession.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSession.java Thu Apr 30 11:01:28 2009
@@ -21,47 +21,211 @@
 import java.security.cert.Certificate;
 import javax.security.cert.X509Certificate;
 
+/**
+ * The interface representing an SSL session.
+ */
 public interface SSLSession {
 
+    /**
+     * Returns the maximum size that an application buffer can be for this
+     * session.
+     *
+     * @return the maximum application buffer size.
+     */
     public int getApplicationBufferSize();
 
+    /**
+     * Returns the name of the cipher suite used in this session.
+     *
+     * @return the name of the cipher suite used in this session.
+     */
     public String getCipherSuite();
 
+    /**
+     * Returns the time this session was created, in milliseconds since midnight
+     * January 1st 1970 UTC.
+     *
+     * @return the time the session was created.
+     */
     public long getCreationTime();
 
+    /**
+     * Returns this sessions identifier.
+     *
+     * @return this sessions identifier.
+     */
     public byte[] getId();
 
+    /**
+     * Returns the time this session was last accessed, in milliseconds since
+     * midnight January 1st 1970 UTC.
+     *
+     * @return the time this session was last accessed.
+     */
     public long getLastAccessedTime();
 
+    /**
+     * Returns the list of certificates that were used to identify the local
+     * side to the peer during the handshake.
+     *
+     * @return the list of certificates, ordered from local certificate to
+     *         CA's certificates.
+     */
     public Certificate[] getLocalCertificates();
 
+    /**
+     * Returns the principal used to identify the local side to the peer during
+     * the handshake.
+     *
+     * @return the principal used to identify the local side.
+     */
     public Principal getLocalPrincipal();
 
+    /**
+     * Returns the maximum size that a network buffer can be for this session.
+     *
+     * @return the maximum network buffer size.
+     */
     public int getPacketBufferSize();
 
+    /**
+     * Returns the list of certificates the peer used to identify itself during
+     * the handshake.
+     * <p>
+     * Note: this method exists for compatility reasons, use
+     * {@link #getPeerCertificates()} instead.
+     *
+     * @return the list of certificates, ordered from the identity certificate to
+     *         the CA's certificates
+     * @throws SSLPeerUnverifiedException
+     *             if the identity of the peer is not verified.
+     */
     public X509Certificate[] getPeerCertificateChain() throws SSLPeerUnverifiedException;
 
+    /**
+     * Returns the list of certificates the peer used to identify itself during
+     * the handshake.
+     *
+     * @return the list of certificates, ordered from the identity certificate to
+     *         the CA's certificates.
+     * @throws SSLPeerUnverifiedException
+     *             if the identity of the peer is not verified.
+     */
     public Certificate[] getPeerCertificates() throws SSLPeerUnverifiedException;
 
+    /**
+     * Returns the host name of the peer of this session. The host name is not
+     * authenticated.
+     *
+     * @return the host name of the peer of this session, or {@code null} if no
+     *         host name is available.
+     */
     public String getPeerHost();
 
+    /**
+     * Returns the port number of the peer of this session. The port number is
+     * not authenticated.
+     *
+     * @return the port number of the peer, of {@code -1} is no port number is
+     *         available.
+     */
     public int getPeerPort();
 
+    /**
+     * Returns the principal identifying the peer during the handshake.
+     *
+     * @return the principal identifying the peer.
+     * @throws SSLPeerUnverifiedException
+     *             if the identity of the peer has not been verified.
+     */
     public Principal getPeerPrincipal() throws SSLPeerUnverifiedException;
 
+    /**
+     * Returns the protocol name that is used for all connections in this
+     * session.
+     *
+     * @return the protocol name that is used for all connections in this
+     *         session.
+     */
     public String getProtocol();
 
+    /**
+     * Returns the context of this session. If a context is available and a
+     * security manager is installed, the
+     * {@code SSLPermission("getSSLSessionContext"} is checked with the security
+     * manager.
+     *
+     * @return the context of this session or {@code null} if no context is
+     *         available.
+     */
     public SSLSessionContext getSessionContext();
 
+    /**
+     * Returns the object bound to the specified name in this session's
+     * application layer data.
+     *
+     * @param name
+     *            the name of the bound value.
+     * @return the value bound to the specified name, or {@code null} if the
+     *         specified name does not exist or is not accessible in the current
+     *         access control context.
+     * @throws IllegalArgumentException
+     *             if {@code name} is {@code null}.
+     */
     public Object getValue(String name);
 
+    /**
+     * Returns the list of the object names bound to this session's application
+     * layer data..
+     * <p>
+     * Depending on the current access control context, the list of object names
+     * may be different.
+     *
+     * @return the list of the object names bound to this session's application
+     *         layer data.
+     */
     public String[] getValueNames();
 
+    /**
+     * Invalidates this session.
+     * <p>
+     * No new connections can be created, but any existing connection remains
+     * valid until it is closed.
+     */
     public void invalidate();
 
+    /**
+     * Returns whether this session is valid.
+     *
+     * @return {@code true} if this session is valid, otherwise {@code false}.
+     */
     public boolean isValid();
 
+    /**
+     * Binds the specified object under the specified name in this session's
+     * application layer data.
+     * <p>
+     * For bindings (new or existing) implementing the
+     * {@code SSLSessionBindingListener} interface the object will be notified.
+     *
+     * @param name
+     *            the name to bind the object to.
+     * @param value
+     *            the object to bind.
+     * @throws IllegalArgumentException
+     *             if either {@code name} or {@code value} is {@code null}.
+     */
     public void putValue(String name, Object value);
 
+    /**
+     * Removes the binding for the specified name in this session's application
+     * layer data. If the existing binding implements the
+     * {@code SSLSessionBindingListener} interface the object will be notified.
+     *
+     * @param name
+     *            the binding to remove.
+     * @throws IllegalArgumentException
+     *             if {@code name} is {@code null}.
+     */
     public void removeValue(String name);
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingEvent.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingEvent.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingEvent.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingEvent.java Thu Apr 30 11:01:28 2009
@@ -20,6 +20,11 @@
 import java.io.Serializable;
 import java.util.EventObject;
 
+/**
+ * The event sent to an {@code SSLSessionBindingListener} when the listener
+ * object is bound ({@link SSLSession#putValue(String, Object)}) or unbound
+ * ({@link SSLSession#removeValue(String)}) to an {@code SSLSession}.
+ */
 public class SSLSessionBindingEvent extends EventObject implements Serializable {
 
     /**
@@ -33,15 +38,36 @@
      */
     private final String name;
 
+    /**
+     * Creates a new {@code SSLSessionBindingEvent} for the specified session
+     * indicating a binding event for the specified name.
+     *
+     * @param session
+     *            the session for which the event occurs.
+     * @param name
+     *            the name of the object being (un)bound.
+     */
     public SSLSessionBindingEvent(SSLSession session, String name) {
         super(session);
         this.name = name;
     }
 
+    /**
+     * Returns the name of the binding being added or removed.
+     *
+     * @return the name of the binding.
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * Returns the session to which the binding is added or from which it is
+     * removed.
+     *
+     * @return the session to which the binding is added or from which it is
+     *         removed.
+     */
     public SSLSession getSession() {
         return (SSLSession) this.source;
     }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingListener.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingListener.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingListener.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionBindingListener.java Thu Apr 30 11:01:28 2009
@@ -19,10 +19,26 @@
 
 import java.util.EventListener;
 
+/**
+ * The interface to be implemented by any object that requires notification when
+ * data objects are bound to (or unbound from) an {@code SSLSession}.
+ */
 public interface SSLSessionBindingListener extends EventListener {
 
+    /**
+     * Notifies this listener when a value is bound to an {@code SSLSession}.
+     *
+     * @param event
+     *            the event data.
+     */
     public void valueBound(SSLSessionBindingEvent event);
 
+    /**
+     * Notifies this listener when a value is unbound from an {@code SSLSession}.
+     *
+     * @param event
+     *            the event data.
+     */
     public void valueUnbound(SSLSessionBindingEvent event);
 
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionContext.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionContext.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionContext.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSessionContext.java Thu Apr 30 11:01:28 2009
@@ -19,17 +19,64 @@
 
 import java.util.Enumeration;
 
+/**
+ * A collection of {@code SSLSession}s.
+ */
 public interface SSLSessionContext {
+    /**
+     * Returns an iterable of all session identifiers in this session context.
+     *
+     * @return an iterable of all session identifiers in this session context.
+     */
     @SuppressWarnings("unchecked")
     public Enumeration getIds();
 
+    /**
+     * Returns the session for the specified session identifier.
+     *
+     * @param sessionId
+     *            the session identifier of the session to look up.
+     * @return the session for the specified session identifier, or {@code null}
+     *         if the specified session identifier does not refer to a session
+     *         in this context.
+     */
     public SSLSession getSession(byte[] sessionId);
 
+    /**
+     * Returns the size of the session cache for this session context.
+     *
+     * @return the size of the session cache for this session context, or
+     *         {@code zero} if unlimited.
+     */
     public int getSessionCacheSize();
 
+    /**
+     * Returns the timeout for sessions in this session context. Sessions
+     * exceeding the timeout are invalidated.
+     *
+     * @return the timeout in seconds, or {@code zero} if unlimited.
+     */
     public int getSessionTimeout();
 
+    /**
+     * Sets the size of the session cache for this session context.
+     *
+     * @param size
+     *            the size of the session cache, or {@code zero} for unlimited
+     *            cache size.
+     * @throws IllegalArgumentException
+     *             if {@code size} is negative.
+     */
     public void setSessionCacheSize(int size) throws IllegalArgumentException;
 
+    /**
+     * Sets the timeout for sessions in this context. Sessions exceeding the
+     * timeout are invalidated.
+     *
+     * @param seconds
+     *            the timeout in seconds, or {@code zero} if unlimited.
+     * @throws IllegalArgumentException
+     *             if {@code seconds} is negative.
+     */
     public void setSessionTimeout(int seconds) throws IllegalArgumentException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocket.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocket.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocket.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocket.java Thu Apr 30 11:01:28 2009
@@ -22,64 +22,278 @@
 import java.net.Socket;
 import java.net.UnknownHostException;
 
+/**
+ * The extension of {@code Socket} providing secure protocols like SSL (Secure
+ * Socket Layer") or TLS (Transport Layer Security).
+ */
 public abstract class SSLSocket extends Socket {
 
+    /**
+     * Only to be used by subclasses.
+     * <p>
+     * Creates a TCP socket.
+     */
     protected SSLSocket() {
         super();
     }
 
+    /**
+     * Only to be used by subclasses.
+     * <p>
+     * Creates a TCP socket connection to the specified host at the specified
+     * port.
+     *
+     * @param host
+     *            the host name to connect to.
+     * @param port
+     *            the port number to connect to.
+     * @throws IOException
+     *             if creating the socket fails.
+     * @throws UnknownHostException
+     *             if the specified host is not known.
+     */
     protected SSLSocket(String host, int port) throws IOException, UnknownHostException {
         super(host, port);
     }
 
+    /**
+     * Only to be used by subclasses.
+     * <p>
+     * Creates a TCP socket connection to the specified address at the specified
+     * port.
+     *
+     * @param address
+     *            the address to connect to.
+     * @param port
+     *            the port number to connect to.
+     * @throws IOException
+     *             if creating the socket fails.
+     */
     protected SSLSocket(InetAddress address, int port) throws IOException {
         super(address, port);
     }
 
+    /**
+     * Only to be used by subclasses.
+     * <p>
+     * Creates a TCP socket connection to the specified host at the specified
+     * port with the client side bound to the specified address and port.
+     *
+     * @param host
+     *            the host name to connect to.
+     * @param port
+     *            the port number to connect to.
+     * @param clientAddress
+     *            the client address to bind to
+     * @param clientPort
+     *            the client port number to bind to.
+     * @throws IOException
+     *             if creating the socket fails.
+     * @throws UnknownHostException
+     *             if the specified host is not known.
+     */
     protected SSLSocket(String host, int port, InetAddress clientAddress, int clientPort)
             throws IOException, UnknownHostException {
         super(host, port, clientAddress, clientPort);
     }
 
+    /**
+     * Only to be used by subclasses.
+     * <p>
+     * Creates a TCP socket connection to the specified address at the specified
+     * port with the client side bound to the specified address and port.
+     *
+     * @param address
+     *            the address to connect to.
+     * @param port
+     *            the port number to connect to.
+     * @param clientAddress
+     *            the client address to bind to.
+     * @param clientPort
+     *            the client port number to bind to.
+     * @throws IOException
+     *             if creating the socket fails.
+     */
     protected SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort)
             throws IOException {
         super(address, port, clientAddress, clientPort);
     }
 
+    /**
+     * Returns the names of the supported cipher suites.
+     *
+     * @return the names of the supported cipher suites.
+     */
     public abstract String[] getSupportedCipherSuites();
 
+    /**
+     * Returns the names of the enabled cipher suites.
+     *
+     * @return the names of the enabled cipher suites.
+     */
     public abstract String[] getEnabledCipherSuites();
 
+    /**
+     * Sets the names of the cipher suites to be enabled.
+     * Only cipher suites returned by {@link #getSupportedCipherSuites()} are
+     * allowed.
+     *
+     * @param suites
+     *            the names of the to be enabled cipher suites.
+     * @throws IllegalArgumentException
+     *             if one of the cipher suite names is not supported.
+     */
     public abstract void setEnabledCipherSuites(String[] suites);
 
+    /**
+     * Returns the names of the supported protocols.
+     *
+     * @return the names of the supported protocols.
+     */
     public abstract String[] getSupportedProtocols();
 
+    /**
+     * Returns the names of the enabled protocols.
+     *
+     * @return the names of the enabled protocols.
+     */
     public abstract String[] getEnabledProtocols();
 
+    /**
+     * Sets the names of the protocols to be enabled. Only
+     * protocols returned by {@link #getSupportedProtocols()} are allowed.
+     *
+     * @param protocols
+     *            the names of the to be enabled protocols.
+     * @throws IllegalArgumentException
+     *             if one of the protocols is not supported.
+     */
     public abstract void setEnabledProtocols(String[] protocols);
 
+    /**
+     * Returns the {@code SSLSession} for this connection. If necessary, a
+     * handshake will be initiated, in which case this method will block until the handshake
+     * has been established. If the handshake fails, an invalid session object
+     * will be returned.
+     *
+     * @return the session object.
+     */
     public abstract SSLSession getSession();
 
+    /**
+     * Registers the specified listener to receive notification on completion of a
+     * handshake on this connection.
+     *
+     * @param listener
+     *            the listener to register.
+     * @throws IllegalArgumentException
+     *             if {@code listener} is {@code null}.
+     */
     public abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener);
 
+    /**
+     * Removes the specified handshake completion listener.
+     *
+     * @param listener
+     *            the listener to remove.
+     * @throws IllegalArgumentException
+     *             if the specified listener is not registered or {@code null}.
+     */
     public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener);
 
+    /**
+     * Starts a new SSL handshake on this connection.
+     *
+     * @throws IOException
+     *             if an error occurs.
+     */
     public abstract void startHandshake() throws IOException;
 
+    /**
+     * Sets whether this connection should act in client mode when handshaking.
+     *
+     * @param mode
+     *            {@code true} if this connection should act in client mode,
+     *            {@code false} if not.
+     */
     public abstract void setUseClientMode(boolean mode);
 
+    /**
+     * Returns whether this connection will act in client mode when handshaking.
+     *
+     * @return {@code true} if this connections will act in client mode when
+     *         handshaking, {@code false} if not.
+     */
     public abstract boolean getUseClientMode();
 
+    /**
+     * Sets whether this connection should require client authentication. This
+     * is only useful for sockets in server mode. 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 #setWantClientAuth(boolean)}.
+     *
+     * @param need
+     *            {@code true} if client authentication is required,
+     *            {@code false} if no authentication is needed.
+     */
     public abstract void setNeedClientAuth(boolean need);
 
+    /**
+     * Returns whether this connection requires client authentication.
+     * This is only useful for sockets in server mode.
+     *
+     * @return {@code true} if client authentication is required, {@code false}
+     *         if no client authentication is needed.
+     */
     public abstract boolean getNeedClientAuth();
 
+    /**
+     * Sets whether this connections should request client authentication. This
+     * is only useful for sockets in server mode. 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 #setNeedClientAuth(boolean)}.
+     *
+     * @param want
+     *            {@code true} if client authentication should be requested,
+     *            {@code false} if not authentication is needed.
+     */
     public abstract void setWantClientAuth(boolean want);
 
+    /**
+     * Returns whether this connections will request client authentication.
+     *
+     * @return {@code true} is client authentication will be requested,
+     *         {@code false} if no client authentication is needed.
+     */
     public abstract boolean getWantClientAuth();
 
+    /**
+     * Sets whether new SSL sessions may be created by this socket or if
+     * existing sessions must be reused.
+     *
+     * @param flag
+     *            {@code true} if new sessions may be created, otherwise
+     *            {@code false}.
+     */
     public abstract void setEnableSessionCreation(boolean flag);
 
+    /**
+     * Returns whether new SSL sessions may be created by this socket or if
+     * existing sessions must be reused.
+     *
+     * @return {@code true} if new sessions may be created, otherwise
+     *         {@code false}.
+     */
     public abstract boolean getEnableSessionCreation();
 
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocketFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocketFactory.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocketFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/SSLSocketFactory.java Thu Apr 30 11:01:28 2009
@@ -25,6 +25,9 @@
 
 import javax.net.SocketFactory;
 
+/**
+ * The abstract factory implementation to create {@code SSLSocket}s.
+ */
 public abstract class SSLSocketFactory extends SocketFactory {
     // FIXME EXPORT CONTROL
 
@@ -33,6 +36,12 @@
 
     private static String defaultName;
 
+    /**
+     * Returns the default {@code SSLSocketFactory} instance. The default is
+     * defined by the security property {@code 'ssl.SocketFactory.provider'}.
+     *
+     * @return the default ssl socket factory instance.
+     */
     public static synchronized SocketFactory getDefault() {
         if (defaultSocketFactory != null) {
             return defaultSocketFactory;
@@ -71,14 +80,48 @@
         return defaultSocketFactory;
     }
 
+    /**
+     * Creates a new {@code SSLSocketFactory}.
+     */
     public SSLSocketFactory() {
         super();
     }
 
+    /**
+     * Returns the names of the cipher suites that are enabled by default.
+     *
+     * @return the names of the cipher suites that are enabled by default.
+     */
     public abstract String[] getDefaultCipherSuites();
 
+    /**
+     * Returns the names of the cipher suites that are supported and could be
+     * enabled for an SSL connection.
+     *
+     * @return the names of the cipher suites that are supported.
+     */
     public abstract String[] getSupportedCipherSuites();
 
+    /**
+     * Creates an {@code SSLSocket} over the specified socket that is connected
+     * to the specified host at the specified port.
+     *
+     * @param s
+     *            the socket.
+     * @param host
+     *            the host.
+     * @param port
+     *            the port number.
+     * @param autoClose
+     *            {@code true} if socket {@code s} should be closed when the
+     *            created socket is closed, {@code false} if the socket
+     *            {@code s} should be left open.
+     * @return the creates ssl socket.
+     * @throws IOException
+     *             if creating the socket fails.
+     * @throws java.net.UnknownHostException
+     *             if the host is unknown.
+     */
     public abstract Socket createSocket(Socket s, String host, int port, boolean autoClose)
             throws IOException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManager.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManager.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManager.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManager.java Thu Apr 30 11:01:28 2009
@@ -17,5 +17,12 @@
 
 package javax.net.ssl;
 
+/**
+ * The marker interface for JSSE trust managers. The purpose is to group trust
+ * managers. The responsibility a trust manager is to handle the trust data used to
+ * make trust decisions for deciding whether credentials of a peer should be
+ * accepted,
+ * @see TrustManagerFactory
+ */
 public interface TrustManager {
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactory.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactory.java Thu Apr 30 11:01:28 2009
@@ -29,6 +29,10 @@
 
 import org.apache.harmony.security.fortress.Engine;
 
+/**
+ * The factory for {@code TrustManager}s based on {@code KeyStore} or provider
+ * specific implementation.
+ */
 public class TrustManagerFactory {
     // Store TrustManager service name
     private static final String SERVICE = "TrustManagerFactory";
@@ -39,6 +43,13 @@
     // Store default property name
     private static final String PROPERTYNAME = "ssl.TrustManagerFactory.algorithm";
 
+    /**
+     * Returns the default algorithm name for the {@code TrustManagerFactory}. The
+     * default algorithm name is specified by the security property
+     * {@code 'ssl.TrustManagerFactory.algorithm'}.
+     *
+     * @return the default algorithm name.
+     */
     public static final String getDefaultAlgorithm() {
         return AccessController.doPrivileged(new PrivilegedAction<String>() {
             public String run() {
@@ -48,8 +59,17 @@
     }
 
     /**
-     * @throws NullPointerException if algorithm is null (instead of NoSuchAlgorithmException as in
-     *             1.4 release)
+     * Creates a new {@code TrustManagerFactory} instance for the specified
+     * trust management algorithm.
+     *
+     * @param algorithm
+     *            the name of the requested trust management algorithm.
+     * @return a trust 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 TrustManagerFactory getInstance(String algorithm)
             throws NoSuchAlgorithmException {
@@ -64,8 +84,23 @@
     }
 
     /**
-     * @throws NullPointerException if algorithm is null (instead of NoSuchAlgorithmException as in
-     *             1.4 release)
+     * Creates a new {@code TrustManagerFactory} instance for the specified
+     * trust management algorithm from the specified provider.
+     *
+     * @param algorithm
+     *            the name of the requested trust management algorithm name.
+     * @param provider
+     *            the name of the provider that provides the requested
+     *            algorithm.
+     * @return a trust 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 TrustManagerFactory getInstance(String algorithm, String provider)
             throws NoSuchAlgorithmException, NoSuchProviderException {
@@ -80,8 +115,20 @@
     }
 
     /**
-     * @throws NullPointerException if algorithm is null (instead of NoSuchAlgorithmException as in
-     *             1.4 release)
+     * Creates a new {@code TrustManagerFactory} instance for the specified
+     * trust 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 TrustManagerFactory getInstance(String algorithm, Provider provider)
             throws NoSuchAlgorithmException {
@@ -106,6 +153,16 @@
     // Store used algorithm
     private final String algorithm;
 
+    /**
+     * Creates a new {@code TrustManagerFactory} instance.
+     *
+     * @param factorySpi
+     *            the implementation delegate.
+     * @param provider
+     *            the provider
+     * @param algorithm
+     *            the algorithm name.
+     */
     protected TrustManagerFactory(TrustManagerFactorySpi factorySpi, Provider provider,
             String algorithm) {
         this.provider = provider;
@@ -113,22 +170,58 @@
         this.spiImpl = factorySpi;
     }
 
+    /**
+     * Returns the name of this {@code TrustManagerFactory} algorithm
+     * implementation.
+     *
+     * @return the name of this {@code TrustManagerFactory} algorithm
+     *         implementation.
+     */
     public final String getAlgorithm() {
         return algorithm;
     }
 
+    /**
+     * Returns the provider for this {@code TrustManagerFactory} instance.
+     *
+     * @return the provider for this {@code TrustManagerFactory} instance.
+     */
     public final Provider getProvider() {
         return provider;
     }
 
+    /**
+     * Initializes this factory instance with the specified keystore as source
+     * of certificate authorities and trust material.
+     *
+     * @param ks
+     *            the keystore or {@code null}.
+     * @throws KeyStoreException
+     *             if the initialization fails.
+     */
     public final void init(KeyStore ks) throws KeyStoreException {
         spiImpl.engineInit(ks);
     }
 
+    /**
+     * Initializes this factory instance with the specified provider-specific
+     * parameters for a source of trust material.
+     *
+     * @param spec
+     *            the provider-specific parameters.
+     * @throws InvalidAlgorithmParameterException
+     *             if the initialization fails.
+     */
     public final void init(ManagerFactoryParameters spec) throws InvalidAlgorithmParameterException {
         spiImpl.engineInit(spec);
     }
 
+    /**
+     * Returns the list of {@code TrustManager}s with one entry for each type
+     * of trust material.
+     *
+     * @return the list of {@code TrustManager}s
+     */
     public final TrustManager[] getTrustManagers() {
         return spiImpl.engineGetTrustManagers();
     }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactorySpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactorySpi.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactorySpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/TrustManagerFactorySpi.java Thu Apr 30 11:01:28 2009
@@ -21,16 +21,47 @@
 import java.security.KeyStore;
 import java.security.KeyStoreException;
 
+/**
+ * The <i>Service Provider Interface</i> (SPI) for the
+ * {@code TrustManagerFactory} class.
+ */
 public abstract class TrustManagerFactorySpi {
 
+    /**
+     * Creates a new {@code TrustManagerFactorySpi} instance.
+     */
     public TrustManagerFactorySpi() {
         super();
     }
 
+    /**
+     * Initializes this factory instance with the specified keystore as source
+     * of certificate authorities and trust material.
+     *
+     * @param ks
+     *            the keystore or {@code null}.
+     * @throws KeyStoreException
+     *             if the initialization fails.
+     */
     protected abstract void engineInit(KeyStore ks) throws KeyStoreException;
 
+    /**
+     * Initializes this factory instance with the specified provider-specific
+     * parameters for a source of trust material.
+     *
+     * @param spec
+     *            the provider-specific parameters.
+     * @throws InvalidAlgorithmParameterException
+     *             if the initialization fails.
+     */
     protected abstract void engineInit(ManagerFactoryParameters spec)
             throws InvalidAlgorithmParameterException;
 
+    /**
+     * Returns the list of {@code TrustManager}s with one entry for each type
+     * of trust material.
+     *
+     * @return the list of {@code TrustManager}s
+     */
     protected abstract TrustManager[] engineGetTrustManagers();
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509ExtendedKeyManager.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509ExtendedKeyManager.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509ExtendedKeyManager.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509ExtendedKeyManager.java Thu Apr 30 11:01:28 2009
@@ -19,17 +19,57 @@
 
 import java.security.Principal;
 
+/**
+ * The abstract extension for the {@code X509KeyManager} interface.
+ */
 public abstract class X509ExtendedKeyManager implements X509KeyManager {
 
+    /**
+     * To be used by subclasses only.
+     * <p>
+     * Creates a new {@code X509ExtendedKeyManager} instance.
+     */
     protected X509ExtendedKeyManager() {
         super();
     }
 
-    public String chooseEngineClientAlias(String[] keyType, Principal[] issuers, SSLEngine engine) {
+    /**
+     * Chooses a alias for the client side of an SSL connection to authenticate
+     * it with the specified public key type and certificate issuers.
+     *
+     * @param keyType
+     *            the list of public key algorithm names.
+     * @param issuers
+     *            the list of certificate issuers, or {@code null} if any issuer
+     *            will do.
+     * @param engine
+     *            the {@code SSLEngine} for the connection, or {@code null} if
+     *            no engine is predefined.
+     * @return the alias name of a matching key or {@code null} if there are no
+     *         matches.
+     */
+    public String chooseEngineClientAlias(String[] keyType,
+            Principal[] issuers, SSLEngine engine) {
         return null;
     }
 
-    public String chooseEngineServerAlias(String keyType, Principal[] issuers, SSLEngine engine) {
+    /**
+     * Chooses a alias for the server side of an SSL connection to authenticate
+     * it with the specified public key type and certificate issuers.
+     *
+     * @param keyType
+     *            the list of public key algorithm names.
+     * @param issuers
+     *            the list of certificate issuers, or {@code null} if any issuer
+     *            will do.
+     * @param engine
+     *            the {@code SSLEngine} for the connection, or {@code null} if
+     *            no engine is predefined.
+     * @return the alias name of a matching key or {@code null} if there are no
+     *         matches.
+     */
+    public String chooseEngineServerAlias(String keyType, Principal[] issuers,
+            SSLEngine engine) {
         return null;
     }
 

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509KeyManager.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509KeyManager.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509KeyManager.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509KeyManager.java Thu Apr 30 11:01:28 2009
@@ -22,17 +22,92 @@
 import java.security.PrivateKey;
 import java.security.cert.X509Certificate;
 
+/**
+ * A Key Manager for X509 certificate-based key pairs.
+ */
 public interface X509KeyManager extends KeyManager {
 
-    public String chooseClientAlias(String[] keyType, Principal[] issuers, Socket socket);
-
-    public String chooseServerAlias(String keyType, Principal[] issuers, Socket socket);
-
+    /**
+     * Chooses an alias for the client side of an SSL connection to authenticate
+     * it with the specified public key type and certificate issuers.
+     *
+     * @param keyType
+     *            the list of public key algorithm names.
+     * @param issuers
+     *            the list of certificate issuers, or {@code null} if any issuer
+     *            will do.
+     * @param socket
+     *            the socket for the connection, or {@code null} if
+     *            the alias selected does not depend on a specific socket.
+     * @return the alias name of a matching key or {@code null} if there are no
+     *         matches.
+     */
+    public String chooseClientAlias(String[] keyType, Principal[] issuers,
+            Socket socket);
+
+    /**
+     * Chooses an alias for the server side of an SSL connection to authenticate
+     * it with the specified public key type and certificate issuers.
+     *
+     * @param keyType
+     *            the list of public key algorithm type names.
+     * @param issuers
+     *            the list of certificate issuers, or {@code null} if any issuer
+     *            will do.
+     * @param socket
+     *            the socket for the connection, or {@code null} if
+     *            the alias selected does not depend on a specific socket.
+     * @return the alias name of a matching key or {@code null} if there are no
+     *         matches.
+     */
+    public String chooseServerAlias(String keyType, Principal[] issuers,
+            Socket socket);
+
+    /**
+     * Returns the certificate chain for the specified alias.
+     *
+     * @param alias
+     *            the alias to get the certificate chain for.
+     * @return the certificate chain for the specified alias, or {@code null} if
+     *         the alias cannot be found.
+     */
     public X509Certificate[] getCertificateChain(String alias);
 
+    /**
+     * Returns the client aliases for the specified public key type and list of
+     * certificate issuers.
+     *
+     * @param keyType
+     *            the public key algorithm type name.
+     * @param issuers
+     *            the list of certificate issuers, or {@code null} if any issuer
+     *            will do.
+     * @return the client aliases for the specified public key type, or
+     *         {@code null} if there are no matching aliases.
+     */
     public String[] getClientAliases(String keyType, Principal[] issuers);
 
+    /**
+     * Returns the server aliases for the specified public key type and list of
+     * certificate issuers.
+     *
+     * @param keyType
+     *            the public key algorithm type name.
+     * @param issuers
+     *            the list of certificate issuers, or {@code null} if any issuer
+     *            will do.
+     * @return the client aliases for the specified public key type, or
+     *         {@code null} if there are no matching aliases.
+     */
     public String[] getServerAliases(String keyType, Principal[] issuers);
 
+    /**
+     * Returns the private key for the specified alias.
+     *
+     * @param alias
+     *            the alias to get the private key for.
+     * @return the private key for the specified alias, or {@code null} if the
+     *         alias cannot be found.
+     */
     public PrivateKey getPrivateKey(String alias);
 }

Modified: harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509TrustManager.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509TrustManager.java?rev=770159&r1=770158&r2=770159&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509TrustManager.java (original)
+++ harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net/ssl/X509TrustManager.java Thu Apr 30 11:01:28 2009
@@ -20,13 +20,57 @@
 import java.security.cert.CertificateException;
 import java.security.cert.X509Certificate;
 
+/**
+ * The trust manager for X509 certificates to be used to perform authentication
+ * for secure sockets.
+ */
 public interface X509TrustManager extends TrustManager {
 
+    /**
+     * Checks whether the specified certificate chain (partial or complete) can
+     * be validated and is trusted for client authentication for the specified
+     * authentication type.
+     *
+     * @param chain
+     *            the certificate chain to validate.
+     * @param authType
+     *            the authentication type used.
+     * @throws CertificateException
+     *             if the certificate chain can't be validated or isn't trusted.
+     * @throws IllegalArgumentException
+     *             if the specified certificate chain is empty or {@code null},
+     *             or if the specified authentication type is {@code null} or an
+     *             empty string.
+     */
     public void checkClientTrusted(X509Certificate[] chain, String authType)
             throws CertificateException;
 
+
+    /**
+     * Checks whether the specified certificate chain (partial or complete) can
+     * be validated and is trusted for server authentication for the specified
+     * key exchange algorithm.
+     *
+     * @param chain
+     *            the certificate chain to validate.
+     * @param authType
+     *            the key exchange algorithm name.
+     * @throws CertificateException
+     *             if the certificate chain can't be validated or isn't trusted.
+     * @throws IllegalArgumentException
+     *             if the specified certificate chain is empty or {@code null},
+     *             or if the specified authentication type is {@code null} or an
+     *             empty string.
+     */
     public void checkServerTrusted(X509Certificate[] chain, String authType)
             throws CertificateException;
 
+    /**
+     * Returns the list of certificate issuer authorities which are trusted for
+     * authentication of peers.
+     *
+     * @return the list of certificate issuer authorities which are trusted for
+     *         authentication of peers.
+     */
     public X509Certificate[] getAcceptedIssuers();
 }



Mime
View raw message