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.util.concurrent.TimeUnit;
32
33 import javax.net.ssl.SSLSession;
34
35 import org.apache.http.HttpHost;
36 import org.apache.http.conn.routing.HttpRoute;
37 import org.apache.http.params.HttpParams;
38 import org.apache.http.protocol.HttpContext;
39
40 /**
41 * A client-side connection with advanced connection logic.
42 * Instances are typically obtained from a connection manager.
43 *
44 * @since 4.0
45 *
46 * @deprecated (4.3) replaced by {@link HttpClientConnectionManager}.
47 */
48 @Deprecated
49 public interface ManagedClientConnection extends
50 HttpRoutedConnection, ManagedHttpClientConnection, ConnectionReleaseTrigger {
51
52 /**
53 * Indicates whether this connection is secure.
54 * The return value is well-defined only while the connection is open.
55 * It may change even while the connection is open.
56 *
57 * @return {@code true} if this connection is secure,
58 * {@code false} otherwise
59 */
60 @Override
61 boolean isSecure();
62
63 /**
64 * Obtains the current route of this connection.
65 *
66 * @return the route established so far, or
67 * {@code null} if not connected
68 */
69 @Override
70 HttpRoute getRoute();
71
72 /**
73 * Obtains the SSL session of the underlying connection, if any.
74 * If this connection is open, and the underlying socket is an
75 * {@link javax.net.ssl.SSLSocket SSLSocket}, the SSL session of
76 * that socket is obtained. This is a potentially blocking operation.
77 * <p>
78 * <b>Note:</b> Whether the underlying socket is an SSL socket
79 * can not necessarily be determined via {@link #isSecure}.
80 * Plain sockets may be considered secure, for example if they are
81 * connected to a known host in the same network segment.
82 * On the other hand, SSL sockets may be considered insecure,
83 * for example depending on the chosen cipher suite.
84 * </p>
85 *
86 * @return the underlying SSL session if available,
87 * {@code null} otherwise
88 */
89 @Override
90 SSLSession getSSLSession();
91
92 /**
93 * Opens this connection according to the given route.
94 *
95 * @param route the route along which to open. It will be opened to
96 * the first proxy if present, or directly to the target.
97 * @param context the context for opening this connection
98 * @param params the parameters for opening this connection
99 *
100 * @throws IOException in case of a problem
101 */
102 void open(HttpRoute route, HttpContext context, HttpParams params)
103 throws IOException;
104
105 /**
106 * Indicates that a tunnel to the target has been established.
107 * The route is the one previously passed to {@link #open open}.
108 * Subsequently, {@link #layerProtocol layerProtocol} can be called
109 * to layer the TLS/SSL protocol on top of the tunnelled connection.
110 * <p>
111 * <b>Note:</b> In HttpClient 3, a call to the corresponding method
112 * would automatically trigger the layering of the TLS/SSL protocol.
113 * This is not the case anymore, you can establish a tunnel without
114 * layering a new protocol over the connection.
115 * </p>
116 *
117 * @param secure {@code true} if the tunnel should be considered
118 * secure, {@code false} otherwise
119 * @param params the parameters for tunnelling this connection
120 *
121 * @throws IOException in case of a problem
122 */
123 void tunnelTarget(boolean secure, HttpParams params)
124 throws IOException;
125
126 /**
127 * Indicates that a tunnel to an intermediate proxy has been established.
128 * This is used exclusively for so-called <i>proxy chains</i>, where
129 * a request has to pass through multiple proxies before reaching the
130 * target. In that case, all proxies but the last need to be tunnelled
131 * when establishing the connection. Tunnelling of the last proxy to the
132 * target is optional and would be indicated via {@link #tunnelTarget}.
133 *
134 * @param next the proxy to which the tunnel was established.
135 * This is <i>not</i> the proxy <i>through</i> which
136 * the tunnel was established, but the new end point
137 * of the tunnel. The tunnel does <i>not</i> yet
138 * reach to the target, use {@link #tunnelTarget}
139 * to indicate an end-to-end tunnel.
140 * @param secure {@code true} if the connection should be
141 * considered secure, {@code false} otherwise
142 * @param params the parameters for tunnelling this connection
143 *
144 * @throws IOException in case of a problem
145 */
146 void tunnelProxy(HttpHost next, boolean secure, HttpParams params)
147 throws IOException;
148
149 /**
150 * Layers a new protocol on top of a {@link #tunnelTarget tunnelled}
151 * connection. This is typically used to create a TLS/SSL connection
152 * through a proxy.
153 * The route is the one previously passed to {@link #open open}.
154 * It is not guaranteed that the layered connection is
155 * {@link #isSecure secure}.
156 *
157 * @param context the context for layering on top of this connection
158 * @param params the parameters for layering on top of this connection
159 *
160 * @throws IOException in case of a problem
161 */
162 void layerProtocol(HttpContext context, HttpParams params)
163 throws IOException;
164
165 /**
166 * Marks this connection as being in a reusable communication state.
167 * The checkpoints for reuseable communication states (in the absence
168 * of pipelining) are before sending a request and after receiving
169 * the response in its entirety.
170 * The connection will automatically clear the checkpoint when
171 * used for communication. A call to this method indicates that
172 * the next checkpoint has been reached.
173 * <p>
174 * A reusable communication state is necessary but not sufficient
175 * for the connection to be reused.
176 * A {@link #getRoute route} mismatch, the connection being closed,
177 * or other circumstances might prevent reuse.
178 * </p>
179 */
180 void markReusable();
181
182 /**
183 * Marks this connection as not being in a reusable state.
184 * This can be used immediately before releasing this connection
185 * to prevent its reuse. Reasons for preventing reuse include
186 * error conditions and the evaluation of a
187 * {@link org.apache.http.ConnectionReuseStrategy reuse strategy}.
188 * <p>
189 * <b>Note:</b>
190 * It is <i>not</i> necessary to call here before writing to
191 * or reading from this connection. Communication attempts will
192 * automatically unmark the state as non-reusable. It can then
193 * be switched back using {@link #markReusable markReusable}.
194 * </p>
195 */
196 void unmarkReusable();
197
198 /**
199 * Indicates whether this connection is in a reusable communication state.
200 * See {@link #markReusable markReusable} and
201 * {@link #unmarkReusable unmarkReusable} for details.
202 *
203 * @return {@code true} if this connection is marked as being in
204 * a reusable communication state,
205 * {@code false} otherwise
206 */
207 boolean isMarkedReusable();
208
209 /**
210 * Assigns a state object to this connection. Connection managers may make
211 * use of the connection state when allocating persistent connections.
212 *
213 * @param state The state object
214 */
215 void setState(Object state);
216
217 /**
218 * Returns the state object associated with this connection.
219 *
220 * @return The state object
221 */
222 Object getState();
223
224 /**
225 * Sets the duration that this connection can remain idle before it is
226 * reused. The connection should not be used again if this time elapses. The
227 * idle duration must be reset after each request sent over this connection.
228 * The elapsed time starts counting when the connection is released, which
229 * is typically after the headers (and any response body, if present) is
230 * fully consumed.
231 */
232 void setIdleDuration(long duration, TimeUnit unit);
233
234 }