You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/04/30 13:01:29 UTC
svn commit: r770159 [1/2] - in
/harmony/enhanced/classlib/trunk/modules/x-net/src/main/java/javax/net: ./
ssl/
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);
}