1 /*
2 * ====================================================================
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements. See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership. The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License. You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied. See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 * ====================================================================
20 *
21 * This software consists of voluntary contributions made by many
22 * individuals on behalf of the Apache Software Foundation. For more
23 * information on the Apache Software Foundation, please see
24 * <http://www.apache.org/>.
25 *
26 */
27
28 package org.apache.http.conn;
29
30 import java.io.IOException;
31 import java.net.Socket;
32
33 import org.apache.http.HttpClientConnection;
34 import org.apache.http.HttpHost;
35 import org.apache.http.HttpInetConnection;
36 import org.apache.http.params.HttpParams;
37
38 /**
39 * A client-side connection that relies on outside logic to connect sockets to the
40 * appropriate hosts. It can be operated directly by an application, or through an
41 * {@link ClientConnectionOperator operator}.
42 *
43 * @since 4.0
44 *
45 * @deprecated (4.3) replaced by {@link HttpClientConnectionManager}.
46 */
47 @Deprecated
48 public interface OperatedClientConnection extends HttpClientConnection, HttpInetConnection {
49
50 /**
51 * Obtains the target host for this connection.
52 * If the connection is to a proxy but not tunnelled, this is
53 * the proxy. If the connection is tunnelled through a proxy,
54 * this is the target of the tunnel.
55 * <p>
56 * The return value is well-defined only while the connection is open.
57 * It may change even while the connection is open,
58 * because of an {@link #update update}.
59 * </p>
60 *
61 * @return the host to which this connection is opened
62 */
63 HttpHost getTargetHost();
64
65 /**
66 * Indicates whether this connection is secure.
67 * The return value is well-defined only while the connection is open.
68 * It may change even while the connection is open,
69 * because of an {@link #update update}.
70 *
71 * @return {@code true} if this connection is secure,
72 * {@code false} otherwise
73 */
74 boolean isSecure();
75
76 /**
77 * Obtains the socket for this connection.
78 * The return value is well-defined only while the connection is open.
79 * It may change even while the connection is open,
80 * because of an {@link #update update}.
81 *
82 * @return the socket for communicating with the
83 * {@link #getTargetHost target host}
84 */
85 Socket getSocket();
86
87 /**
88 * Signals that this connection is in the process of being open.
89 * <p>
90 * By calling this method, the connection can be re-initialized
91 * with a new Socket instance before {@link #openCompleted} is called.
92 * This enabled the connection to close that socket if
93 * {@link org.apache.http.HttpConnection#shutdown shutdown}
94 * is called before it is fully open. Closing an unconnected socket
95 * will interrupt a thread that is blocked on the connect.
96 * Otherwise, that thread will either time out on the connect,
97 * or it returns successfully and then opens this connection
98 * which was just shut down.
99 * <p>
100 * This method can be called multiple times if the connection
101 * is layered over another protocol. <b>Note:</b> This method
102 * will <i>not</i> close the previously used socket. It is
103 * the caller's responsibility to close that socket if it is
104 * no longer required.
105 * <p>
106 * The caller must invoke {@link #openCompleted} in order to complete
107 * the process.
108 *
109 * @param sock the unconnected socket which is about to
110 * be connected.
111 * @param target the target host of this connection
112 */
113 void opening(Socket sock, HttpHost target)
114 throws IOException;
115
116 /**
117 * Signals that the connection has been successfully open.
118 * An attempt to call this method on an open connection will cause
119 * an exception.
120 *
121 * @param secure {@code true} if this connection is secure, for
122 * example if an {@code SSLSocket} is used, or
123 * {@code false} if it is not secure
124 * @param params parameters for this connection. The parameters will
125 * be used when creating dependent objects, for example
126 * to determine buffer sizes.
127 */
128 void openCompleted(boolean secure, HttpParams params)
129 throws IOException;
130
131 /**
132 * Updates this connection.
133 * A connection can be updated only while it is open.
134 * Updates are used for example when a tunnel has been established,
135 * or when a TLS/SSL connection has been layered on top of a plain
136 * socket connection.
137 * <p>
138 * <b>Note:</b> Updating the connection will <i>not</i> close the
139 * previously used socket. It is the caller's responsibility to close
140 * that socket if it is no longer required.
141 * </p>
142 *
143 * @param sock the new socket for communicating with the target host,
144 * or {@code null} to continue using the old socket.
145 * If {@code null} is passed, helper objects that
146 * depend on the socket should be re-used. In that case,
147 * some changes in the parameters will not take effect.
148 * @param target the new target host of this connection
149 * @param secure {@code true} if this connection is now secure,
150 * {@code false} if it is not secure
151 * @param params new parameters for this connection
152 */
153 void update(Socket sock, HttpHost target,
154 boolean secure, HttpParams params)
155 throws IOException;
156
157 }