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