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.nio.conn;
28  
29  import java.io.IOException;
30  import java.util.concurrent.Future;
31  import java.util.concurrent.TimeUnit;
32  
33  import org.apache.http.concurrent.FutureCallback;
34  import org.apache.http.conn.routing.HttpRoute;
35  import org.apache.http.nio.NHttpClientConnection;
36  import org.apache.http.nio.reactor.IOEventDispatch;
37  import org.apache.http.protocol.HttpContext;
38  
39  /**
40   * Represents a manager of persistent client connections.
41   * <p>
42   * The purpose of an HTTP connection manager is to serve as a factory for new
43   * HTTP connections, manage persistent connections and synchronize access to
44   * persistent connections making sure that only one thread of execution can
45   * have access to a connection at a time.
46   * <p>
47   * Implementations of this interface must be thread-safe. Access to shared
48   * data must be synchronized as methods of this interface may be executed
49   * from multiple threads.
50   *
51   * @since 4.0
52   */
53  public interface NHttpClientConnectionManager {
54  
55      /**
56       * Returns a {@link Future} for a {@link NHttpClientConnection}.
57       * <p>
58       * Please note that the consumer of that connection is responsible
59       * for fully establishing the route the to the connection target
60       * by calling {@link #startRoute(org.apache.http.nio.NHttpClientConnection,
61       *   org.apache.http.conn.routing.HttpRoute,
62       *   org.apache.http.protocol.HttpContext) startRoute} in order to start
63       * the process of connection initialization, optionally calling
64       * {@link #upgrade(org.apache.http.nio.NHttpClientConnection,
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} method to
68       * all intermediate proxy hops and and finally calling
69       * {@link #routeComplete(org.apache.http.nio.NHttpClientConnection,
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}
76       *              if the connection is not expected to carry any state.
77       * @param connectTimeout connect timeout.
78       * @param connectionRequestTimeout  connection request timeout.
79       * @param timeUnit time unit of the previous two timeout values.
80       * @param callback future callback.
81       */
82      Future<NHttpClientConnection> requestConnection(
83              HttpRoute route,
84              Object state,
85              long connectTimeout,
86              long connectionRequestTimeout,
87              TimeUnit timeUnit,
88              FutureCallback<NHttpClientConnection> callback);
89  
90      /**
91       * Releases the connection back to the manager making it potentially
92       * re-usable by other consumers. Optionally, the maximum period
93       * of how long the manager should keep the connection alive can be
94       * defined using {@code validDuration} and {@code timeUnit}
95       * parameters.
96       *
97       * @param conn      the managed connection to release.
98       * @param validDuration the duration of time this connection is valid for reuse.
99       * @param timeUnit the time unit.
100      *
101      * @see #closeExpiredConnections()
102      */
103     void releaseConnection(
104             NHttpClientConnection conn, Object newState, long validDuration, TimeUnit timeUnit);
105 
106     /**
107      * Starts the process of connection initialization. Connection route may consist of several
108      * intermediate hops and may require a protocol upgrade. Once the route is fully established
109      * the {@link #routeComplete(org.apache.http.nio.NHttpClientConnection,
110      *   org.apache.http.conn.routing.HttpRoute,
111      *   org.apache.http.protocol.HttpContext) routeComplete} method must be called.
112      *
113      * @param conn the managed connection to initialize.
114      * @param route the connection route.
115      * @param context the context
116      */
117     void startRoute(
118             NHttpClientConnection conn,
119             HttpRoute route,
120             HttpContext context) throws IOException;
121 
122     /**
123      * Upgrades the underlying connection I/O session to TLS/SSL (or another layering
124      * protocol) after having executed {@code CONNECT} method to all
125      * intermediate proxy hops.
126      *
127      * @param conn the managed connection to upgrade.
128      * @param route the connection route.
129      * @param context the context
130      */
131     void upgrade(
132             NHttpClientConnection conn,
133             HttpRoute route,
134             HttpContext context) throws IOException;
135 
136     /**
137      * Marks the connection as fully established with all its intermediate
138      * hops completed.
139      *
140      * @param conn the managed connection to mark as route complete.
141      * @param route the connection route.
142      * @param context the context
143      */
144     void routeComplete(
145             NHttpClientConnection conn,
146             HttpRoute route,
147             HttpContext context);
148 
149     /**
150      * Determines if the given connection has been fully established and
151      * marked as route complete.
152      *
153      * @param conn the managed connection.
154      */
155     boolean isRouteComplete(NHttpClientConnection conn);
156 
157     /**
158      * Closes idle connections in the pool.
159      * <p>
160      * Open connections in the pool that have not been used for the
161      * timespan given by the argument will be closed.
162      * Currently allocated connections are not subject to this method.
163      * Times will be checked with milliseconds precision
164      *
165      * All expired connections will also be closed.
166      *
167      * @param idletime  the idle time of connections to be closed
168      * @param tunit     the unit for the {@code idletime}
169      *
170      * @see #closeExpiredConnections()
171      */
172     void closeIdleConnections(long idletime, TimeUnit tunit);
173 
174     /**
175      * Closes all expired connections in the pool.
176      * <p>
177      * Open connections in the pool that have not been used for
178      * the timespan defined when the connection was released will be closed.
179      * Currently allocated connections are not subject to this method.
180      * Times will be checked with milliseconds precision.
181      */
182     void closeExpiredConnections();
183 
184     /**
185      * Starts the underlying I/O reactor and initiates the dispatch of
186      * I/O event notifications to the given {@link IOEventDispatch}.
187      */
188     void execute(IOEventDispatch eventDispatch) throws IOException;
189 
190     /**
191      * Shuts down this connection manager and releases allocated resources.
192      * This includes closing all connections, whether they are currently
193      * used or not.
194      */
195     void shutdown() throws IOException;
196 
197 }