michael@0: /* michael@0: * ==================================================================== michael@0: * Licensed to the Apache Software Foundation (ASF) under one michael@0: * or more contributor license agreements. See the NOTICE file michael@0: * distributed with this work for additional information michael@0: * regarding copyright ownership. The ASF licenses this file michael@0: * to you under the Apache License, Version 2.0 (the michael@0: * "License"); you may not use this file except in compliance michael@0: * with the License. You may obtain a copy of the License at michael@0: * michael@0: * http://www.apache.org/licenses/LICENSE-2.0 michael@0: * michael@0: * Unless required by applicable law or agreed to in writing, michael@0: * software distributed under the License is distributed on an michael@0: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY michael@0: * KIND, either express or implied. See the License for the michael@0: * specific language governing permissions and limitations michael@0: * under the License. michael@0: * ==================================================================== michael@0: * michael@0: * This software consists of voluntary contributions made by many michael@0: * individuals on behalf of the Apache Software Foundation. For more michael@0: * information on the Apache Software Foundation, please see michael@0: * . michael@0: * michael@0: */ michael@0: michael@0: package ch.boye.httpclientandroidlib.conn; michael@0: michael@0: import java.io.IOException; michael@0: import java.util.concurrent.TimeUnit; michael@0: michael@0: import javax.net.ssl.SSLSession; michael@0: michael@0: import ch.boye.httpclientandroidlib.HttpClientConnection; michael@0: import ch.boye.httpclientandroidlib.HttpHost; michael@0: import ch.boye.httpclientandroidlib.params.HttpParams; michael@0: import ch.boye.httpclientandroidlib.protocol.HttpContext; michael@0: michael@0: import ch.boye.httpclientandroidlib.conn.routing.HttpRoute; michael@0: michael@0: /** michael@0: * A client-side connection with advanced connection logic. michael@0: * Instances are typically obtained from a connection manager. michael@0: * michael@0: * @since 4.0 michael@0: */ michael@0: public interface ManagedClientConnection extends michael@0: HttpClientConnection, HttpRoutedConnection, ConnectionReleaseTrigger { michael@0: michael@0: /** michael@0: * Indicates whether this connection is secure. michael@0: * The return value is well-defined only while the connection is open. michael@0: * It may change even while the connection is open. michael@0: * michael@0: * @return true if this connection is secure, michael@0: * false otherwise michael@0: */ michael@0: boolean isSecure(); michael@0: michael@0: /** michael@0: * Obtains the current route of this connection. michael@0: * michael@0: * @return the route established so far, or michael@0: * null if not connected michael@0: */ michael@0: HttpRoute getRoute(); michael@0: michael@0: /** michael@0: * Obtains the SSL session of the underlying connection, if any. michael@0: * If this connection is open, and the underlying socket is an michael@0: * {@link javax.net.ssl.SSLSocket SSLSocket}, the SSL session of michael@0: * that socket is obtained. This is a potentially blocking operation. michael@0: *
michael@0: * Note: Whether the underlying socket is an SSL socket michael@0: * can not necessarily be determined via {@link #isSecure}. michael@0: * Plain sockets may be considered secure, for example if they are michael@0: * connected to a known host in the same network segment. michael@0: * On the other hand, SSL sockets may be considered insecure, michael@0: * for example depending on the chosen cipher suite. michael@0: * michael@0: * @return the underlying SSL session if available, michael@0: * null otherwise michael@0: */ michael@0: SSLSession getSSLSession(); michael@0: michael@0: /** michael@0: * Opens this connection according to the given route. michael@0: * michael@0: * @param route the route along which to open. It will be opened to michael@0: * the first proxy if present, or directly to the target. michael@0: * @param context the context for opening this connection michael@0: * @param params the parameters for opening this connection michael@0: * michael@0: * @throws IOException in case of a problem michael@0: */ michael@0: void open(HttpRoute route, HttpContext context, HttpParams params) michael@0: throws IOException; michael@0: michael@0: /** michael@0: * Indicates that a tunnel to the target has been established. michael@0: * The route is the one previously passed to {@link #open open}. michael@0: * Subsequently, {@link #layerProtocol layerProtocol} can be called michael@0: * to layer the TLS/SSL protocol on top of the tunnelled connection. michael@0: *
michael@0: * Note: In HttpClient 3, a call to the corresponding method michael@0: * would automatically trigger the layering of the TLS/SSL protocol. michael@0: * This is not the case anymore, you can establish a tunnel without michael@0: * layering a new protocol over the connection. michael@0: * michael@0: * @param secure true if the tunnel should be considered michael@0: * secure, false otherwise michael@0: * @param params the parameters for tunnelling this connection michael@0: * michael@0: * @throws IOException in case of a problem michael@0: */ michael@0: void tunnelTarget(boolean secure, HttpParams params) michael@0: throws IOException; michael@0: michael@0: /** michael@0: * Indicates that a tunnel to an intermediate proxy has been established. michael@0: * This is used exclusively for so-called proxy chains, where michael@0: * a request has to pass through multiple proxies before reaching the michael@0: * target. In that case, all proxies but the last need to be tunnelled michael@0: * when establishing the connection. Tunnelling of the last proxy to the michael@0: * target is optional and would be indicated via {@link #tunnelTarget}. michael@0: * michael@0: * @param next the proxy to which the tunnel was established. michael@0: * This is not the proxy through which michael@0: * the tunnel was established, but the new end point michael@0: * of the tunnel. The tunnel does not yet michael@0: * reach to the target, use {@link #tunnelTarget} michael@0: * to indicate an end-to-end tunnel. michael@0: * @param secure true if the connection should be michael@0: * considered secure, false otherwise michael@0: * @param params the parameters for tunnelling this connection michael@0: * michael@0: * @throws IOException in case of a problem michael@0: */ michael@0: void tunnelProxy(HttpHost next, boolean secure, HttpParams params) michael@0: throws IOException; michael@0: michael@0: /** michael@0: * Layers a new protocol on top of a {@link #tunnelTarget tunnelled} michael@0: * connection. This is typically used to create a TLS/SSL connection michael@0: * through a proxy. michael@0: * The route is the one previously passed to {@link #open open}. michael@0: * It is not guaranteed that the layered connection is michael@0: * {@link #isSecure secure}. michael@0: * michael@0: * @param context the context for layering on top of this connection michael@0: * @param params the parameters for layering on top of this connection michael@0: * michael@0: * @throws IOException in case of a problem michael@0: */ michael@0: void layerProtocol(HttpContext context, HttpParams params) michael@0: throws IOException; michael@0: michael@0: /** michael@0: * Marks this connection as being in a reusable communication state. michael@0: * The checkpoints for reuseable communication states (in the absence michael@0: * of pipelining) are before sending a request and after receiving michael@0: * the response in its entirety. michael@0: * The connection will automatically clear the checkpoint when michael@0: * used for communication. A call to this method indicates that michael@0: * the next checkpoint has been reached. michael@0: *
michael@0: * A reusable communication state is necessary but not sufficient michael@0: * for the connection to be reused. michael@0: * A {@link #getRoute route} mismatch, the connection being closed, michael@0: * or other circumstances might prevent reuse. michael@0: */ michael@0: void markReusable(); michael@0: michael@0: /** michael@0: * Marks this connection as not being in a reusable state. michael@0: * This can be used immediately before releasing this connection michael@0: * to prevent its reuse. Reasons for preventing reuse include michael@0: * error conditions and the evaluation of a michael@0: * {@link ch.boye.httpclientandroidlib.ConnectionReuseStrategy reuse strategy}. michael@0: *
michael@0: * Note: michael@0: * It is not necessary to call here before writing to michael@0: * or reading from this connection. Communication attempts will michael@0: * automatically unmark the state as non-reusable. It can then michael@0: * be switched back using {@link #markReusable markReusable}. michael@0: */ michael@0: void unmarkReusable(); michael@0: michael@0: /** michael@0: * Indicates whether this connection is in a reusable communication state. michael@0: * See {@link #markReusable markReusable} and michael@0: * {@link #unmarkReusable unmarkReusable} for details. michael@0: * michael@0: * @return true if this connection is marked as being in michael@0: * a reusable communication state, michael@0: * false otherwise michael@0: */ michael@0: boolean isMarkedReusable(); michael@0: michael@0: /** michael@0: * Assigns a state object to this connection. Connection managers may make michael@0: * use of the connection state when allocating persistent connections. michael@0: * michael@0: * @param state The state object michael@0: */ michael@0: void setState(Object state); michael@0: michael@0: /** michael@0: * Returns the state object associated with this connection. michael@0: * michael@0: * @return The state object michael@0: */ michael@0: Object getState(); michael@0: michael@0: /** michael@0: * Sets the duration that this connection can remain idle before it is michael@0: * reused. The connection should not be used again if this time elapses. The michael@0: * idle duration must be reset after each request sent over this connection. michael@0: * The elapsed time starts counting when the connection is released, which michael@0: * is typically after the headers (and any response body, if present) is michael@0: * fully consumed. michael@0: */ michael@0: void setIdleDuration(long duration, TimeUnit unit); michael@0: michael@0: }