Simplified OperatedClientConnection interface

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

module-client/src/main/java/org/apache/http/conn/OperatedClientConnection.java

@@ -41,9 +41,8 @@ import org.apache.http.params.HttpParams;
 
 
 /**
- * A client-side connection that needs to be operated.
+ * A client-side connection that relies on outside logic to connect sockets to the 
- * It relies on outside logic to connect sockets to the appropriate hosts.
+ * appropriate hosts. It can be operated directly by an application, or through an
- * It can be operated directly by an application, or through an
  * {@link ClientConnectionOperator operator}.
  *
  *
@@ -103,15 +102,12 @@ public interface OperatedClientConnection
 
 
     /**
-     * Announces opening of this connection.
+     * Signals that this connection is in the process of being open.
-     * Opening can be announced only while the connection is closed.
-     * This is an optional step, you can call {@link #open open}
-     * without an announcement.
      * <br/>
-     * By calling this method, you provide the connection with
+     * By calling this method, you can provide the connection with
-     * the unconnected socket that will be connected in order
+     * the unconnected socket that will be connected before
-     * to call {@link #open open}. This allows the connection to
+     * {@link #openCompleted} is called. This allows 
-     * close that socket if
+     * the connection to close that socket if
      * {@link org.apache.http.HttpConnection#shutdown shutdown}
      * is called before it is open. Closing the unconnected socket
      * will interrupt a thread that is blocked on the connect.
@@ -119,36 +115,32 @@ public interface OperatedClientConnection
      * or it returns successfully and then opens this connection
      * which was just shut down.
      * <br/>
-     * <b>Note:</b>
+     * You also must call {@link #openCompleted} in order to complete
-     * The result of {@link #getSocket getSocket} is defined
+     * the process
-     * only for open connections. You MUST NOT rely on that
-     * method to return the unconnected socket after announcing.
      *
      * @param sock      the unconnected socket which is about to
-     *                  be connected in order to call {@link #open open}.
+     *                  be connected.
-     *                  <code>null</code> can be passed to undo a
-     *                  previous call.
-     */
-    void announce(Socket sock)
-        ;
-
-
-    /**
-     * Opens this connection.
-     * A connection can be openend only while it is closed.
-     * To modify a connection while it is open, use {@link #update update}.
-     *
-     * @param sock      the open socket for communicating with the target host
      * @param target    the target host of this connection
      * @param secure    <code>true</code> if this connection is secure, for
      *                  example if an <code>SSLSocket</code> is used, or
      *                  <code>false</code> if it is not secure
+     */
+    void opening(Socket sock, HttpHost target, boolean secure)
+        throws IOException
+        ;
+
+
+    /**
+     * Signals that the connection has been successfully open.
+     * An attempt to call this method on an open connection will cause
+     * an exception.
+     *
+     * @param sock      the open socket for communicating with the target host
      * @param params    parameters for this connection. The parameters will
      *                  be used when creating dependent objects, for example
      *                  to determine buffer sizes.
      */
-    void open(Socket sock, HttpHost target,
+    void openCompleted(HttpParams params)
-              boolean secure, HttpParams params)
         throws IOException
         ;
 

module-client/src/main/java/org/apache/http/impl/conn/DefaultClientConnection.java

@@ -71,8 +71,8 @@ public class DefaultClientConnection extends SocketHttpClientConnection
     
     private static final Log LOG = LogFactory.getLog(DefaultClientConnection.class);
     
-    /** The unconnected socket between announce and open. */
+    /** The unconnected socket */
-    private volatile Socket announcedSocket;
+    private volatile Socket socket;
 
     /** The target host of this connection. */
     private HttpHost targetHost;
@@ -96,21 +96,28 @@ public class DefaultClientConnection extends SocketHttpClientConnection
     }
 
 
-    // non-javadoc, see interface OperatedClientConnection
     @Override
     public final Socket getSocket() {
-        return super.getSocket(); // base class attribute
+        return this.socket;
     }
 
 
-    // non-javadoc, see interface OperatedClientConnection
+    public void opening(Socket sock, HttpHost target, boolean secure) {
-    public void announce(Socket sock) {
-
         assertNotOpen();
-        announcedSocket = sock;
+        this.socket = sock;
-
+        this.targetHost = target;
-    } // prepare
+        this.connSecure = secure;
+    }
 
+    
+    public void openCompleted(HttpParams params) throws IOException {
+        assertNotOpen();
+        if (params == null) {
+            throw new IllegalArgumentException
+                ("Parameters must not be null.");
+        }
+        bind(this.socket, params);
+    }
 
     /**
      * Force-closes this connection.
@@ -124,12 +131,11 @@ public class DefaultClientConnection extends SocketHttpClientConnection
     public void shutdown() throws IOException {
         LOG.debug("Connection shut down");
         
-        Socket sock = announcedSocket; // copy volatile attribute
+        super.shutdown();
+        Socket sock = this.socket; // copy volatile attribute
         if (sock != null)
             sock.close();
 
-        super.shutdown();
-
     } // shutdown
 
     
@@ -183,35 +189,6 @@ public class DefaultClientConnection extends SocketHttpClientConnection
     }
 
 
-    // non-javadoc, see interface OperatedClientConnection
-    public void open(Socket sock, HttpHost target,
-                     boolean secure, HttpParams params)
-        throws IOException {
-
-        assertNotOpen();
-        if (sock == null) {
-            throw new IllegalArgumentException
-                ("Socket must not be null.");
-        }
-        if (target == null) {
-            throw new IllegalArgumentException
-                ("Target host must not be null.");
-        }
-        if (params == null) {
-            throw new IllegalArgumentException
-                ("Parameters must not be null.");
-        }
-
-        bind(sock, params);
-        
-        targetHost = target;
-        connSecure = secure;
-
-        announcedSocket = null;
-
-    } // open
-
-
     // non-javadoc, see interface OperatedClientConnection
     public void update(Socket sock, HttpHost target,
                        boolean secure, HttpParams params)
@@ -227,8 +204,10 @@ public class DefaultClientConnection extends SocketHttpClientConnection
                 ("Parameters must not be null.");
         }
 
-        if (sock != null)
+        if (sock != null) {
+            this.socket = sock;
             bind(sock, params);
+        }
         targetHost = target;
         connSecure = secure;
 

module-client/src/main/java/org/apache/http/impl/conn/DefaultClientConnectionOperator.java

@@ -128,7 +128,7 @@ public class DefaultClientConnectionOperator
         final SocketFactory sf = schm.getSocketFactory();
 
         Socket sock = sf.createSocket();
-        conn.announce(sock);
+        conn.opening(sock, target, sf.isSecure(sock));
 
         try {
             sock = sf.connectSocket(sock, target.getHostName(),
@@ -138,13 +138,7 @@ public class DefaultClientConnectionOperator
             throw new HttpHostConnectException(target, ex);
         }
         prepareSocket(sock, context, params);
-
+        conn.openCompleted(params);
-        final boolean secure = sf.isSecure(sock);
-
-        conn.open(sock, target, secure, params);
-        //@@@ error handling: unannounce at connection?
-        //@@@ error handling: close the created socket?
-
     } // openConnection