1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/conn/ManagedClientConnection.java Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,226 @@
1.4 +/*
1.5 + * ====================================================================
1.6 + * Licensed to the Apache Software Foundation (ASF) under one
1.7 + * or more contributor license agreements. See the NOTICE file
1.8 + * distributed with this work for additional information
1.9 + * regarding copyright ownership. The ASF licenses this file
1.10 + * to you under the Apache License, Version 2.0 (the
1.11 + * "License"); you may not use this file except in compliance
1.12 + * with the License. You may obtain a copy of the License at
1.13 + *
1.14 + * http://www.apache.org/licenses/LICENSE-2.0
1.15 + *
1.16 + * Unless required by applicable law or agreed to in writing,
1.17 + * software distributed under the License is distributed on an
1.18 + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
1.19 + * KIND, either express or implied. See the License for the
1.20 + * specific language governing permissions and limitations
1.21 + * under the License.
1.22 + * ====================================================================
1.23 + *
1.24 + * This software consists of voluntary contributions made by many
1.25 + * individuals on behalf of the Apache Software Foundation. For more
1.26 + * information on the Apache Software Foundation, please see
1.27 + * <http://www.apache.org/>.
1.28 + *
1.29 + */
1.30 +
1.31 +package ch.boye.httpclientandroidlib.conn;
1.32 +
1.33 +import java.io.IOException;
1.34 +import java.util.concurrent.TimeUnit;
1.35 +
1.36 +import javax.net.ssl.SSLSession;
1.37 +
1.38 +import ch.boye.httpclientandroidlib.HttpClientConnection;
1.39 +import ch.boye.httpclientandroidlib.HttpHost;
1.40 +import ch.boye.httpclientandroidlib.params.HttpParams;
1.41 +import ch.boye.httpclientandroidlib.protocol.HttpContext;
1.42 +
1.43 +import ch.boye.httpclientandroidlib.conn.routing.HttpRoute;
1.44 +
1.45 +/**
1.46 + * A client-side connection with advanced connection logic.
1.47 + * Instances are typically obtained from a connection manager.
1.48 + *
1.49 + * @since 4.0
1.50 + */
1.51 +public interface ManagedClientConnection extends
1.52 + HttpClientConnection, HttpRoutedConnection, ConnectionReleaseTrigger {
1.53 +
1.54 + /**
1.55 + * Indicates whether this connection is secure.
1.56 + * The return value is well-defined only while the connection is open.
1.57 + * It may change even while the connection is open.
1.58 + *
1.59 + * @return <code>true</code> if this connection is secure,
1.60 + * <code>false</code> otherwise
1.61 + */
1.62 + boolean isSecure();
1.63 +
1.64 + /**
1.65 + * Obtains the current route of this connection.
1.66 + *
1.67 + * @return the route established so far, or
1.68 + * <code>null</code> if not connected
1.69 + */
1.70 + HttpRoute getRoute();
1.71 +
1.72 + /**
1.73 + * Obtains the SSL session of the underlying connection, if any.
1.74 + * If this connection is open, and the underlying socket is an
1.75 + * {@link javax.net.ssl.SSLSocket SSLSocket}, the SSL session of
1.76 + * that socket is obtained. This is a potentially blocking operation.
1.77 + * <br/>
1.78 + * <b>Note:</b> Whether the underlying socket is an SSL socket
1.79 + * can not necessarily be determined via {@link #isSecure}.
1.80 + * Plain sockets may be considered secure, for example if they are
1.81 + * connected to a known host in the same network segment.
1.82 + * On the other hand, SSL sockets may be considered insecure,
1.83 + * for example depending on the chosen cipher suite.
1.84 + *
1.85 + * @return the underlying SSL session if available,
1.86 + * <code>null</code> otherwise
1.87 + */
1.88 + SSLSession getSSLSession();
1.89 +
1.90 + /**
1.91 + * Opens this connection according to the given route.
1.92 + *
1.93 + * @param route the route along which to open. It will be opened to
1.94 + * the first proxy if present, or directly to the target.
1.95 + * @param context the context for opening this connection
1.96 + * @param params the parameters for opening this connection
1.97 + *
1.98 + * @throws IOException in case of a problem
1.99 + */
1.100 + void open(HttpRoute route, HttpContext context, HttpParams params)
1.101 + throws IOException;
1.102 +
1.103 + /**
1.104 + * Indicates that a tunnel to the target has been established.
1.105 + * The route is the one previously passed to {@link #open open}.
1.106 + * Subsequently, {@link #layerProtocol layerProtocol} can be called
1.107 + * to layer the TLS/SSL protocol on top of the tunnelled connection.
1.108 + * <br/>
1.109 + * <b>Note:</b> In HttpClient 3, a call to the corresponding method
1.110 + * would automatically trigger the layering of the TLS/SSL protocol.
1.111 + * This is not the case anymore, you can establish a tunnel without
1.112 + * layering a new protocol over the connection.
1.113 + *
1.114 + * @param secure <code>true</code> if the tunnel should be considered
1.115 + * secure, <code>false</code> otherwise
1.116 + * @param params the parameters for tunnelling this connection
1.117 + *
1.118 + * @throws IOException in case of a problem
1.119 + */
1.120 + void tunnelTarget(boolean secure, HttpParams params)
1.121 + throws IOException;
1.122 +
1.123 + /**
1.124 + * Indicates that a tunnel to an intermediate proxy has been established.
1.125 + * This is used exclusively for so-called <i>proxy chains</i>, where
1.126 + * a request has to pass through multiple proxies before reaching the
1.127 + * target. In that case, all proxies but the last need to be tunnelled
1.128 + * when establishing the connection. Tunnelling of the last proxy to the
1.129 + * target is optional and would be indicated via {@link #tunnelTarget}.
1.130 + *
1.131 + * @param next the proxy to which the tunnel was established.
1.132 + * This is <i>not</i> the proxy <i>through</i> which
1.133 + * the tunnel was established, but the new end point
1.134 + * of the tunnel. The tunnel does <i>not</i> yet
1.135 + * reach to the target, use {@link #tunnelTarget}
1.136 + * to indicate an end-to-end tunnel.
1.137 + * @param secure <code>true</code> if the connection should be
1.138 + * considered secure, <code>false</code> otherwise
1.139 + * @param params the parameters for tunnelling this connection
1.140 + *
1.141 + * @throws IOException in case of a problem
1.142 + */
1.143 + void tunnelProxy(HttpHost next, boolean secure, HttpParams params)
1.144 + throws IOException;
1.145 +
1.146 + /**
1.147 + * Layers a new protocol on top of a {@link #tunnelTarget tunnelled}
1.148 + * connection. This is typically used to create a TLS/SSL connection
1.149 + * through a proxy.
1.150 + * The route is the one previously passed to {@link #open open}.
1.151 + * It is not guaranteed that the layered connection is
1.152 + * {@link #isSecure secure}.
1.153 + *
1.154 + * @param context the context for layering on top of this connection
1.155 + * @param params the parameters for layering on top of this connection
1.156 + *
1.157 + * @throws IOException in case of a problem
1.158 + */
1.159 + void layerProtocol(HttpContext context, HttpParams params)
1.160 + throws IOException;
1.161 +
1.162 + /**
1.163 + * Marks this connection as being in a reusable communication state.
1.164 + * The checkpoints for reuseable communication states (in the absence
1.165 + * of pipelining) are before sending a request and after receiving
1.166 + * the response in its entirety.
1.167 + * The connection will automatically clear the checkpoint when
1.168 + * used for communication. A call to this method indicates that
1.169 + * the next checkpoint has been reached.
1.170 + * <br/>
1.171 + * A reusable communication state is necessary but not sufficient
1.172 + * for the connection to be reused.
1.173 + * A {@link #getRoute route} mismatch, the connection being closed,
1.174 + * or other circumstances might prevent reuse.
1.175 + */
1.176 + void markReusable();
1.177 +
1.178 + /**
1.179 + * Marks this connection as not being in a reusable state.
1.180 + * This can be used immediately before releasing this connection
1.181 + * to prevent its reuse. Reasons for preventing reuse include
1.182 + * error conditions and the evaluation of a
1.183 + * {@link ch.boye.httpclientandroidlib.ConnectionReuseStrategy reuse strategy}.
1.184 + * <br/>
1.185 + * <b>Note:</b>
1.186 + * It is <i>not</i> necessary to call here before writing to
1.187 + * or reading from this connection. Communication attempts will
1.188 + * automatically unmark the state as non-reusable. It can then
1.189 + * be switched back using {@link #markReusable markReusable}.
1.190 + */
1.191 + void unmarkReusable();
1.192 +
1.193 + /**
1.194 + * Indicates whether this connection is in a reusable communication state.
1.195 + * See {@link #markReusable markReusable} and
1.196 + * {@link #unmarkReusable unmarkReusable} for details.
1.197 + *
1.198 + * @return <code>true</code> if this connection is marked as being in
1.199 + * a reusable communication state,
1.200 + * <code>false</code> otherwise
1.201 + */
1.202 + boolean isMarkedReusable();
1.203 +
1.204 + /**
1.205 + * Assigns a state object to this connection. Connection managers may make
1.206 + * use of the connection state when allocating persistent connections.
1.207 + *
1.208 + * @param state The state object
1.209 + */
1.210 + void setState(Object state);
1.211 +
1.212 + /**
1.213 + * Returns the state object associated with this connection.
1.214 + *
1.215 + * @return The state object
1.216 + */
1.217 + Object getState();
1.218 +
1.219 + /**
1.220 + * Sets the duration that this connection can remain idle before it is
1.221 + * reused. The connection should not be used again if this time elapses. The
1.222 + * idle duration must be reset after each request sent over this connection.
1.223 + * The elapsed time starts counting when the connection is released, which
1.224 + * is typically after the headers (and any response body, if present) is
1.225 + * fully consumed.
1.226 + */
1.227 + void setIdleDuration(long duration, TimeUnit unit);
1.228 +
1.229 +}
