Javadoc cleanups

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@766180 13f79535-47bb-0310-9956-ffa450edef68

httpclient/src/main/java/org/apache/http/conn/scheme/HostNameResolver.java

@@ -35,11 +35,19 @@
 import java.net.InetAddress;
 
 /**
+ * Hostname to IP address resolver.
  *
  * @since 4.0
  */
 public interface HostNameResolver {
 
+	/**
+	 * Resolves given hostname to its IP address
+	 * 
+	 * @param hostname the hostname.
+	 * @return IP address.
+	 * @throws IOException
+	 */
     InetAddress resolve (String hostname) throws IOException;
 
 }

httpclient/src/main/java/org/apache/http/conn/scheme/PlainSocketFactory.java

@@ -44,8 +44,13 @@
 import org.apache.http.params.HttpParams;
 
 /**
- * The default class for creating sockets.
- * 
+ * The default class for creating plain (unencrypted) sockets.
+ * <p>
+ * The following parameters can be used to customize the behavior of this 
+ * class: 
+ * <ul>
+ *  <li>{@link org.apache.http.params.CoreConnectionPNames#CONNECTION_TIMEOUT}</li>
+ * </ul>
  *
  * @since 4.0
  */
@@ -80,12 +85,10 @@ public PlainSocketFactory() {
         this(null);
     }
 
-    // non-javadoc, see interface org.apache.http.conn.SocketFactory
     public Socket createSocket() {
         return new Socket();
     }
 
-    // non-javadoc, see interface org.apache.http.conn.SocketFactory
     public Socket connectSocket(Socket sock, String host, int port, 
                                 InetAddress localAddress, int localPort,
                                 HttpParams params)
@@ -126,9 +129,7 @@ public Socket connectSocket(Socket sock, String host, int port,
             throw new ConnectTimeoutException("Connect to " + remoteAddress + " timed out");
         }
         return sock;
-
-    } // connectSocket
-
+    }
 
     /**
      * Checks whether a socket connection is secure.
@@ -152,9 +153,7 @@ public final boolean isSecure(Socket sock)
         if (sock.isClosed()) {
             throw new IllegalArgumentException("Socket is closed.");
         }
-
         return false;
-
-    } // isSecure
+    }
 
 }

httpclient/src/main/java/org/apache/http/conn/scheme/SchemeRegistry.java

@@ -41,14 +41,9 @@
 import org.apache.http.HttpHost;
 
 /**
- * A set of supported protocol {@link Scheme schemes}.
+ * A set of supported protocol {@link Scheme}s.
  * Schemes are identified by lowercase names.
  *
- *
- *
- * <!-- empty lines to avoid svn diff problems -->
- * @version   $Revision$ $Date$
- *
  * @since 4.0
  */
 @ThreadSafe
@@ -58,7 +53,6 @@ public final class SchemeRegistry {
     @GuardedBy("this")
     private final Map<String,Scheme> registeredSchemes;
 
-
     /**
      * Creates a new, empty scheme registry.
      */
@@ -67,7 +61,6 @@ public SchemeRegistry() {
         registeredSchemes = new LinkedHashMap<String,Scheme>();
     }
 
-
     /**
      * Obtains a scheme by name.
      *
@@ -87,7 +80,6 @@ public synchronized final Scheme getScheme(String name) {
         return found;
     }
 
-
     /**
      * Obtains the scheme for a host.
      * Convenience method for <code>getScheme(host.getSchemeName())</pre>
@@ -106,7 +98,6 @@ public synchronized final Scheme getScheme(HttpHost host) {
         return getScheme(host.getSchemeName());
     }
 
-
     /**
      * Obtains a scheme by name, if registered.
      *
@@ -125,7 +116,6 @@ public synchronized final Scheme get(String name) {
         return found;
     }
 
-
     /**
      * Registers a scheme.
      * The scheme can later be retrieved by its name
@@ -144,7 +134,6 @@ public synchronized final Scheme register(Scheme sch) {
         return old;
     }
 
-
     /**
      * Unregisters a scheme.
      *
@@ -163,7 +152,6 @@ public synchronized final Scheme unregister(String name) {
         return gone;
     }
 
-
     /**
      * Obtains the names of the registered schemes in their default order.
      *
@@ -187,5 +175,5 @@ public synchronized void setItems(final Map<String, Scheme> map) {
         registeredSchemes.putAll(map);
     }
 
-} // class SchemeRegistry
+}
 

httpclient/src/main/java/org/apache/http/conn/scheme/SocketFactory.java

@@ -40,13 +40,8 @@
 import org.apache.http.params.HttpParams;
 
 /**
- * A factory for creating and connecting sockets.
+ * A factory for creating, initializing and connecting sockets.
  * The factory encapsulates the logic for establishing a socket connection.
- * <br/>
- * Both {@link java.lang.Object#equals(java.lang.Object) Object.equals()}
- * and {@link java.lang.Object#hashCode() Object.hashCode()}
- * must be overridden for the correct operation of some connection managers.
- * 
  *
  * @since 4.0
  */
@@ -62,9 +57,7 @@ public interface SocketFactory {
      * @throws IOException if an I/O error occurs while creating the socket
      */
     Socket createSocket()
-        throws IOException
-        ;
-
+        throws IOException;
 
     /**
      * Connects a socket to the given host.
@@ -100,7 +93,6 @@ Socket connectSocket(
         HttpParams params
     ) throws IOException, UnknownHostException, ConnectTimeoutException;
 
-
     /**
      * Checks whether a socket provides a secure connection.
      * The socket must be {@link #connectSocket connected}
@@ -114,7 +106,7 @@ Socket connectSocket(
      * socket to a host in the same intranet ("trusted zone")
      * could be considered secure. On the other hand, a
      * TLS/SSL socket could be considered insecure based on
-     * the cypher suite chosen for the connection.
+     * the cipher suite chosen for the connection.
      *
      * @param sock      the connected socket to check
      *
@@ -131,7 +123,6 @@ Socket connectSocket(
      *  value when called with an invalid socket argument.
      */
     boolean isSecure(Socket sock)
-        throws IllegalArgumentException
-        ;
+        throws IllegalArgumentException;
 
 }

httpclient/src/main/java/org/apache/http/conn/ssl/AbstractVerifier.java

@@ -57,7 +57,6 @@
 /**
  * Abstract base class for all standard {@link X509HostnameVerifier} 
  * implementations.
- * 
  *
  * @since 4.0
  */
@@ -135,7 +134,6 @@ is presenting (e.g. edit "/etc/apache2/server.crt"
         verify(host, x509);
     }
 
-    @Deprecated
     public final boolean verify(String host, SSLSession session) {
         try {
             Certificate[] certs = session.getPeerCertificates();

httpclient/src/main/java/org/apache/http/conn/ssl/SSLSocketFactory.java

@@ -61,7 +61,7 @@
 
 /**
  * Layered socket factory for TLS/SSL connections, based on JSSE.
- *.
+ * 
  * <p>
  * SSLSocketFactory can be used to validate the identity of the HTTPS 
  * server against a list of trusted certificates and to authenticate to
@@ -70,7 +70,7 @@
  * 
  * <p>
  * SSLSocketFactory will enable server authentication when supplied with
- * a {@link KeyStore truststore} file containg one or several trusted
+ * a {@link KeyStore truststore} file containing one or several trusted
  * certificates. The client secure socket will reject the connection during
  * the SSL session handshake if the target HTTPS server attempts to
  * authenticate itself with a non-trusted certificate.
@@ -84,6 +84,15 @@
  * </p>
  * 
  * <p>
+ * The following parameters can be used to customize the behavior of this 
+ * class: 
+ * <ul>
+ *  <li>{@link org.apache.http.params.CoreConnectionPNames#CONNECTION_TIMEOUT}</li>
+ *  <li>{@link org.apache.http.params.CoreConnectionPNames#SO_TIMEOUT}</li>
+ * </ul>
+ * </p>
+ * 
+ * <p>
  * SSLSocketFactory will enable client authentication when supplied with
  * a {@link KeyStore keystore} file containg a private key/public certificate
  * pair. The client secure socket will use the private key to authenticate

httpclient/src/main/java/org/apache/http/conn/ssl/X509HostnameVerifier.java

@@ -33,34 +33,39 @@
 
 import javax.net.ssl.HostnameVerifier;
 import javax.net.ssl.SSLException;
-import javax.net.ssl.SSLSession;
 import javax.net.ssl.SSLSocket;
 import java.io.IOException;
 import java.security.cert.X509Certificate;
 
 /**
  * Interface for checking if a hostname matches the names stored inside the
- * server's X.509 certificate.  Implements javax.net.ssl.HostnameVerifier, but
- * we don't actually use that interface.  Instead we added some methods that
- * take String parameters (instead of javax.net.ssl.HostnameVerifier's
- * SSLSession).  JUnit is a lot easier this way!  :-)
- * <p/>
- * We provide the HostnameVerifier.DEFAULT, HostnameVerifier.STRICT, and
- * HostnameVerifier.ALLOW_ALL implementations.  But feel free to define
- * your own implementation!
- * <p/>
- * Inspired by Sebastian Hauer's original StrictSSLProtocolSocketFactory in the
- * HttpClient "contrib" repository.
+ * server's X.509 certificate.  This interface extends 
+ * {@link javax.net.ssl.HostnameVerifier}, but it is recommended to use 
+ * methods added by X509HostnameVerifier.
  *
- *
- * @since 4.0 (8-Dec-2006)
+ * @since 4.0
  */
 public interface X509HostnameVerifier extends HostnameVerifier {
 
-    boolean verify(String host, SSLSession session);
-
+	/**
+	 * Verifies that the host name is an acceptable match with the server's 
+	 * authentication scheme based on the given {@link SSLSocket}.
+	 *   
+	 * @param host the host.
+	 * @param ssl the SSL socket.
+	 * @throws IOException if an I/O error occurs or the verification process
+	 *   fails. 
+	 */
     void verify(String host, SSLSocket ssl) throws IOException;
 
+	/**
+	 * Verifies that the host name is an acceptable match with the server's 
+	 * authentication scheme based on the given {@link X509Certificate}.
+	 *   
+	 * @param host the host.
+	 * @param cert the certificate.
+	 * @throws SSLException if the verification process fails. 
+	 */
     void verify(String host, X509Certificate cert) throws SSLException;
 
     /**
@@ -75,10 +80,9 @@ public interface X509HostnameVerifier extends HostnameVerifier {
      * @param subjectAlts Subject-Alt fields of type 2 ("DNS"), as extracted
      *                    from the X.509 certificate.
      * @param host        The hostname to verify.
-     * @throws SSLException If verification failed.
+	 * @throws SSLException if the verification process fails. 
      */
     void verify(String host, String[] cns, String[] subjectAlts)
           throws SSLException;
 
-
 }