+ * The methods in this interface allow the creation of plain and layered + * sockets. Creating a tunnelled connection through a proxy, however, + * is not within the scope of the operator. + *
+ * Implementations of this interface must be thread-safe. Access to shared
+ * data must be synchronized as methods of this interface may be executed
+ * from multiple threads.
+ *
+ * @since 4.0
+ */
+public interface ClientConnectionOperator {
+
+ /**
+ * Creates a new connection that can be operated.
+ *
+ * @return a new, unopened connection for use with this operator
+ */
+ OperatedClientConnection createConnection();
+
+ /**
+ * Opens a connection to the given target host.
+ *
+ * @param conn the connection to open
+ * @param target the target host to connect to
+ * @param local the local address to route from, or
+ * null for the default
+ * @param context the context for the connection
+ * @param params the parameters for the connection
+ *
+ * @throws IOException in case of a problem
+ */
+ void openConnection(OperatedClientConnection conn,
+ HttpHost target,
+ InetAddress local,
+ HttpContext context,
+ HttpParams params)
+ throws IOException;
+
+ /**
+ * Updates a connection with a layered secure connection.
+ * The typical use of this method is to update a tunnelled plain
+ * connection (HTTP) to a secure TLS/SSL connection (HTTPS).
+ *
+ * @param conn the open connection to update
+ * @param target the target host for the updated connection.
+ * The connection must already be open or tunnelled
+ * to the host and port, but the scheme of the target
+ * will be used to create a layered connection.
+ * @param context the context for the connection
+ * @param params the parameters for the updated connection
+ *
+ * @throws IOException in case of a problem
+ */
+ void updateSecureConnection(OperatedClientConnection conn,
+ HttpHost target,
+ HttpContext context,
+ HttpParams params)
+ throws IOException;
+
+}
+