View Javadoc

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  package org.apache.http.conn;
28  
29  import java.io.IOException;
30  import java.util.concurrent.TimeUnit;
31  
32  import org.apache.http.HttpClientConnection;
33  import org.apache.http.conn.routing.HttpRoute;
34  import org.apache.http.protocol.HttpContext;
35  
36  /**
37   * Represents a manager of persistent client connections.
38   * <p/>
39   * The purpose of an HTTP connection manager is to serve as a factory for new
40   * HTTP connections, manage persistent connections and synchronize access to
41   * persistent connections making sure that only one thread of execution can
42   * have access to a connection at a time.
43   * <p/>
44   * Implementations of this interface must be thread-safe. Access to shared
45   * data must be synchronized as methods of this interface may be executed
46   * from multiple threads.
47   *
48   * @since 4.3
49   */
50  public interface HttpClientConnectionManager {
51  
52      /**
53       * Returns a new {@link ConnectionRequest}, from which a
54       * {@link HttpClientConnection} can be obtained or the request can be
55       * aborted.
56       * <p/>
57       * Please note that newly allocated connections can be returned
58       * in the closed state. The consumer of that connection is responsible
59       * for fully establishing the route the to the connection target
60       * by calling {@link #connect(org.apache.http.HttpClientConnection,
61       *   org.apache.http.conn.routing.HttpRoute, int,
62       *   org.apache.http.protocol.HttpContext) connect} in order to connect
63       * directly to the target or to the first proxy hop, optionally calling
64       * {@link #upgrade(org.apache.http.HttpClientConnection,
65       *   org.apache.http.conn.routing.HttpRoute,
66       *   org.apache.http.protocol.HttpContext) upgrade} method to upgrade
67       * the connection after having executed <code>CONNECT</code> method to
68       * all intermediate proxy hops and and finally calling {@link #routeComplete(
69       *  org.apache.http.HttpClientConnection,
70       *  org.apache.http.conn.routing.HttpRoute,
71       *  org.apache.http.protocol.HttpContext) routeComplete} to mark the route
72       *  as fully completed.
73       *
74       * @param route HTTP route of the requested connection.
75       * @param state expected state of the connection or <code>null</code>
76       *              if the connection is not expected to carry any state.
77       */
78      ConnectionRequest requestConnection(HttpRoute route, Object state);
79  
80      /**
81       * Releases the connection back to the manager making it potentially
82       * re-usable by other consumers. Optionally, the maximum period
83       * of how long the manager should keep the connection alive can be
84       * defined using <code>validDuration</code> and <code>timeUnit</code>
85       * parameters.
86       *
87       * @param conn      the managed connection to release.
88       * @param validDuration the duration of time this connection is valid for reuse.
89       * @param timeUnit the time unit.
90       *
91       * @see #closeExpiredConnections()
92       */
93      void releaseConnection(
94              HttpClientConnection conn, Object newState, long validDuration, TimeUnit timeUnit);
95  
96      /**
97       * Connects the underlying connection socket to the connection target in case
98       * of a direct route or to the first proxy hop in case of a route via a proxy
99       * (or multiple proxies).
100      *
101      * @param conn the managed connection.
102      * @param route the route of the connection.
103      * @param connectTimeout connect timeout in milliseconds.
104      * @param context the actual HTTP context.
105      * @throws IOException
106      */
107     void connect(
108             HttpClientConnection conn,
109             HttpRoute route,
110             int connectTimeout,
111             HttpContext context) throws IOException;
112 
113     /**
114      * Upgrades the underlying connection socket to TLS/SSL (or another layering
115      * protocol) after having executed <code>CONNECT</code> method to all
116      * intermediate proxy hops
117      *
118      * @param conn the managed connection.
119      * @param route the route of the connection.
120      * @param context the actual HTTP context.
121      * @throws IOException
122      */
123     void upgrade(
124             HttpClientConnection conn,
125             HttpRoute route,
126             HttpContext context) throws IOException;
127 
128     /**
129      * Marks the connection as fully established with all its intermediate
130      * hops completed.
131      *
132      * @param conn the managed connection.
133      * @param route the route of the connection.
134      * @param context the actual HTTP context.
135      * @throws IOException
136      */
137     void routeComplete(
138             HttpClientConnection conn,
139             HttpRoute route,
140             HttpContext context) throws IOException;
141 
142     /**
143      * Closes idle connections in the pool.
144      * <p/>
145      * Open connections in the pool that have not been used for the
146      * timespan given by the argument will be closed.
147      * Currently allocated connections are not subject to this method.
148      * Times will be checked with milliseconds precision
149      *
150      * All expired connections will also be closed.
151      *
152      * @param idletime  the idle time of connections to be closed
153      * @param tunit     the unit for the <code>idletime</code>
154      *
155      * @see #closeExpiredConnections()
156      */
157     void closeIdleConnections(long idletime, TimeUnit tunit);
158 
159     /**
160      * Closes all expired connections in the pool.
161      * <p/>
162      * Open connections in the pool that have not been used for
163      * the timespan defined when the connection was released will be closed.
164      * Currently allocated connections are not subject to this method.
165      * Times will be checked with milliseconds precision.
166      */
167     void closeExpiredConnections();
168 
169     /**
170      * Shuts down this connection manager and releases allocated resources.
171      * This includes closing all connections, whether they are currently
172      * used or not.
173      */
174     void shutdown();
175 
176 }