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