1/*2 * ====================================================================3 * Licensed to the Apache Software Foundation (ASF) under one4 * or more contributor license agreements. See the NOTICE file5 * distributed with this work for additional information6 * regarding copyright ownership. The ASF licenses this file7 * to you under the Apache License, Version 2.0 (the8 * "License"); you may not use this file except in compliance9 * with the License. You may obtain a copy of the License at10 *11 * http://www.apache.org/licenses/LICENSE-2.012 *13 * Unless required by applicable law or agreed to in writing,14 * software distributed under the License is distributed on an15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY16 * KIND, either express or implied. See the License for the17 * specific language governing permissions and limitations18 * under the License.19 * ====================================================================20 *21 * This software consists of voluntary contributions made by many22 * individuals on behalf of the Apache Software Foundation. For more23 * information on the Apache Software Foundation, please see24 * <http://www.apache.org/>.25 *26 */2728package org.apache.http.conn;
2930import java.io.IOException;
31import java.util.concurrent.TimeUnit;
3233import javax.net.ssl.SSLSession;
3435import org.apache.http.HttpClientConnection;
36import org.apache.http.HttpHost;
37import org.apache.http.conn.routing.HttpRoute;
38import org.apache.http.params.HttpParams;
39import org.apache.http.protocol.HttpContext;
4041/**42 * A client-side connection with advanced connection logic.43 * Instances are typically obtained from a connection manager.44 *45 * @since 4.046 *47 * @deprecated (4.3) replaced by {@link HttpClientConnectionManager}.48 */49 @Deprecated
50publicinterfaceManagedClientConnectionextends51 HttpClientConnection, HttpRoutedConnection, ManagedHttpClientConnection, ConnectionReleaseTrigger {
5253/**54 * Indicates whether this connection is secure.55 * The return value is well-defined only while the connection is open.56 * It may change even while the connection is open.57 *58 * @return {@code true} if this connection is secure,59 * {@code false} otherwise60 */61 @Override
62boolean isSecure();
6364/**65 * Obtains the current route of this connection.66 *67 * @return the route established so far, or68 * {@code null} if not connected69 */70 @Override
71HttpRoute getRoute();
7273/**74 * Obtains the SSL session of the underlying connection, if any.75 * If this connection is open, and the underlying socket is an76 * {@link javax.net.ssl.SSLSocket SSLSocket}, the SSL session of77 * that socket is obtained. This is a potentially blocking operation.78 * <p>79 * <b>Note:</b> Whether the underlying socket is an SSL socket80 * can not necessarily be determined via {@link #isSecure}.81 * Plain sockets may be considered secure, for example if they are82 * connected to a known host in the same network segment.83 * On the other hand, SSL sockets may be considered insecure,84 * for example depending on the chosen cipher suite.85 * </p>86 *87 * @return the underlying SSL session if available,88 * {@code null} otherwise89 */90 @Override
91 SSLSession getSSLSession();
9293/**94 * Opens this connection according to the given route.95 *96 * @param route the route along which to open. It will be opened to97 * the first proxy if present, or directly to the target.98 * @param context the context for opening this connection99 * @param params the parameters for opening this connection100 *101 * @throws IOException in case of a problem102 */103void open(HttpRoute route, HttpContext context, HttpParams params)
104throws IOException;
105106/**107 * Indicates that a tunnel to the target has been established.108 * The route is the one previously passed to {@link #open open}.109 * Subsequently, {@link #layerProtocol layerProtocol} can be called110 * to layer the TLS/SSL protocol on top of the tunnelled connection.111 * <p>112 * <b>Note:</b> In HttpClient 3, a call to the corresponding method113 * would automatically trigger the layering of the TLS/SSL protocol.114 * This is not the case anymore, you can establish a tunnel without115 * layering a new protocol over the connection.116 * </p>117 *118 * @param secure {@code true} if the tunnel should be considered119 * secure, {@code false} otherwise120 * @param params the parameters for tunnelling this connection121 *122 * @throws IOException in case of a problem123 */124void tunnelTarget(boolean secure, HttpParams params)
125throws IOException;
126127/**128 * Indicates that a tunnel to an intermediate proxy has been established.129 * This is used exclusively for so-called <i>proxy chains</i>, where130 * a request has to pass through multiple proxies before reaching the131 * target. In that case, all proxies but the last need to be tunnelled132 * when establishing the connection. Tunnelling of the last proxy to the133 * target is optional and would be indicated via {@link #tunnelTarget}.134 *135 * @param next the proxy to which the tunnel was established.136 * This is <i>not</i> the proxy <i>through</i> which137 * the tunnel was established, but the new end point138 * of the tunnel. The tunnel does <i>not</i> yet139 * reach to the target, use {@link #tunnelTarget}140 * to indicate an end-to-end tunnel.141 * @param secure {@code true} if the connection should be142 * considered secure, {@code false} otherwise143 * @param params the parameters for tunnelling this connection144 *145 * @throws IOException in case of a problem146 */147void tunnelProxy(HttpHost next, boolean secure, HttpParams params)
148throws IOException;
149150/**151 * Layers a new protocol on top of a {@link #tunnelTarget tunnelled}152 * connection. This is typically used to create a TLS/SSL connection153 * through a proxy.154 * The route is the one previously passed to {@link #open open}.155 * It is not guaranteed that the layered connection is156 * {@link #isSecure secure}.157 *158 * @param context the context for layering on top of this connection159 * @param params the parameters for layering on top of this connection160 *161 * @throws IOException in case of a problem162 */163void layerProtocol(HttpContext context, HttpParams params)
164throws IOException;
165166/**167 * Marks this connection as being in a reusable communication state.168 * The checkpoints for reuseable communication states (in the absence169 * of pipelining) are before sending a request and after receiving170 * the response in its entirety.171 * The connection will automatically clear the checkpoint when172 * used for communication. A call to this method indicates that173 * the next checkpoint has been reached.174 * <p>175 * A reusable communication state is necessary but not sufficient176 * for the connection to be reused.177 * A {@link #getRoute route} mismatch, the connection being closed,178 * or other circumstances might prevent reuse.179 * </p>180 */181void markReusable();
182183/**184 * Marks this connection as not being in a reusable state.185 * This can be used immediately before releasing this connection186 * to prevent its reuse. Reasons for preventing reuse include187 * error conditions and the evaluation of a188 * {@link org.apache.http.ConnectionReuseStrategy reuse strategy}.189 * <p>190 * <b>Note:</b>191 * It is <i>not</i> necessary to call here before writing to192 * or reading from this connection. Communication attempts will193 * automatically unmark the state as non-reusable. It can then194 * be switched back using {@link #markReusable markReusable}.195 * </p>196 */197void unmarkReusable();
198199/**200 * Indicates whether this connection is in a reusable communication state.201 * See {@link #markReusable markReusable} and202 * {@link #unmarkReusable unmarkReusable} for details.203 *204 * @return {@code true} if this connection is marked as being in205 * a reusable communication state,206 * {@code false} otherwise207 */208boolean isMarkedReusable();
209210/**211 * Assigns a state object to this connection. Connection managers may make212 * use of the connection state when allocating persistent connections.213 *214 * @param state The state object215 */216void setState(Object state);
217218/**219 * Returns the state object associated with this connection.220 *221 * @return The state object222 */223 Object getState();
224225/**226 * Sets the duration that this connection can remain idle before it is227 * reused. The connection should not be used again if this time elapses. The228 * idle duration must be reset after each request sent over this connection.229 * The elapsed time starts counting when the connection is released, which230 * is typically after the headers (and any response body, if present) is231 * fully consumed.232 */233void setIdleDuration(long duration, TimeUnit unit);
234235 }