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 timeUnit the unit for the {@code idletime}
169 *
170 * @see #closeExpiredConnections()
171 */
172 void closeIdleConnections(long idletime, TimeUnit timeUnit);
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 }