new connection interfaces, step 3 - HTTPCLIENT-475

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

src/java/org/apache/http/conn/UnmanagedClientConnection.java

@@ -88,6 +88,37 @@ public interface UnmanagedClientConnection
     // do not require connections to store parameters.
 
 
+    /**
+     * Prepares opening this connection.
+     * Opening can be prepared only while the connection is closed.
+     * This is an optional step, you can call {@link #open open}
+     * without preparing.
+     * <br/>
+     * By calling this method, you provide the connection with
+     * the unconnected socket that will be connected in order
+     * to call {@link #open open}. This allows 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.
+     * Otherwise, that thread will either time out on the connect,
+     * or it returns successfully and then opens this connection
+     * which was just shut down.
+     * <br/>
+     * <b>Note:</b>
+     * The result of {@link #getSocket getSocket} is defined
+     * only for open connections. You MUST NOT rely on that
+     * method to return the unconnected socket after preparing.
+     *
+     * @param sock      the unconnected socket which is about to
+     *                  be connected in order to call {@link #open open}.
+     *                  <code>null</code> can be passed to undo a
+     *                  previous call.
+     */
+    void prepare(Socket sock)
+        ;
+
+
     /**
      * Opens this connection.
      * A connection can be openend only while it is closed.

src/java/org/apache/http/conn/impl/DefaultClientConnection.java

@@ -55,6 +55,9 @@ import org.apache.http.conn.UnmanagedClientConnection;
 public class DefaultClientConnection extends SocketHttpClientConnection
     implements UnmanagedClientConnection {
 
+    /** The unconnected socket while being prepared. */
+    private volatile Socket preparedSocket;
+
     /** The target host of this connection. */
     private HttpHost targetHost;
 
@@ -84,6 +87,35 @@ public class DefaultClientConnection extends SocketHttpClientConnection
     }
 
 
+    // non-javadoc, see interface UnmanagedClientConnection
+    public void prepare(Socket sock) {
+
+        assertNotOpen();
+        preparedSocket = sock;
+
+    } // prepare
+
+
+    /**
+     * Force-closes this connection.
+     * If it is not yet {@link #open open} but {@link #prepare prepared},
+     * the associated socket is closed. That will interrupt a thread that
+     * is blocked on connecting the socket.
+     *
+     * @throws IOException      in case of a problem
+     */
+    public void shutdown()
+        throws IOException {
+
+        Socket sock = preparedSocket; // copy volatile attribute
+        if (sock != null)
+            sock.close();
+
+        super.shutdown();
+
+    } // shutdown
+
+
     // non-javadoc, see interface UnmanagedClientConnection
     public void open(Socket sock, HttpHost target,
                      boolean secure, HttpParams params)
@@ -107,6 +139,8 @@ public class DefaultClientConnection extends SocketHttpClientConnection
         targetHost = target;
         connSecure = secure;
 
+        preparedSocket = null;
+
     } // open
 
 

src/java/org/apache/http/conn/impl/DefaultSocketConnectionOperator.java

@@ -104,18 +104,20 @@ public class DefaultSocketConnectionOperator
                  "' in target host.");
         }
         final SocketFactory sf = schm.getSocketFactory();
-        //@@@ create socket, register in connection, connect? (HTTPCLIENT-475)
+
-        //@@@ Requires registration method, since conn.open(...) fails if
+        Socket sock = sf.createSocket();
-        //@@@ the socket is not open. Dependent objects need the streams!
+        conn.prepare(sock);
-        final Socket sock = sf.connectSocket
+
-            (null, target.getHostName(), target.getPort(), local, 0, params);
+        sock = sf.connectSocket
+            (sock, target.getHostName(), target.getPort(), local, 0, params);
         prepareSocket(sock, context, params);
 
         //@@@ ask the factory whether the new socket is secure?
         boolean secure = (sf instanceof SecureSocketFactory);
 
         conn.open(sock, target, secure, params);
-        //@@@ error handling: close the created socket in case of exception?
+        //@@@ error handling: unprepare the connection?
+        //@@@ error handling: close the created socket?
 
     } // openConnection