001/* 002 * ==================================================================== 003 * Licensed to the Apache Software Foundation (ASF) under one 004 * or more contributor license agreements. See the NOTICE file 005 * distributed with this work for additional information 006 * regarding copyright ownership. The ASF licenses this file 007 * to you under the Apache License, Version 2.0 (the 008 * "License"); you may not use this file except in compliance 009 * with the License. You may obtain a copy of the License at 010 * 011 * http://www.apache.org/licenses/LICENSE-2.0 012 * 013 * Unless required by applicable law or agreed to in writing, 014 * software distributed under the License is distributed on an 015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 016 * KIND, either express or implied. See the License for the 017 * specific language governing permissions and limitations 018 * under the License. 019 * ==================================================================== 020 * 021 * This software consists of voluntary contributions made by many 022 * individuals on behalf of the Apache Software Foundation. For more 023 * information on the Apache Software Foundation, please see 024 * <http://www.apache.org/>. 025 * 026 */ 027package org.apache.http.conn; 028 029import java.io.IOException; 030import java.util.concurrent.TimeUnit; 031 032import org.apache.http.HttpClientConnection; 033import org.apache.http.conn.routing.HttpRoute; 034import org.apache.http.protocol.HttpContext; 035 036/** 037 * Represents a manager of persistent client connections. 038 * <p> 039 * The purpose of an HTTP connection manager is to serve as a factory for new 040 * HTTP connections, manage persistent connections and synchronize access to 041 * persistent connections making sure that only one thread of execution can 042 * have access to a connection at a time. 043 * </p> 044 * <p> 045 * Implementations of this interface must be thread-safe. Access to shared 046 * data must be synchronized as methods of this interface may be executed 047 * from multiple threads. 048 * </p> 049 * 050 * @since 4.3 051 */ 052public interface HttpClientConnectionManager { 053 054 /** 055 * Returns a new {@link ConnectionRequest}, from which a 056 * {@link HttpClientConnection} can be obtained or the request can be 057 * aborted. 058 * <p> 059 * Please note that newly allocated connections can be returned 060 * in the closed state. The consumer of that connection is responsible 061 * for fully establishing the route the to the connection target 062 * by calling {@link #connect(org.apache.http.HttpClientConnection, 063 * org.apache.http.conn.routing.HttpRoute, int, 064 * org.apache.http.protocol.HttpContext) connect} in order to connect 065 * directly to the target or to the first proxy hop, optionally calling 066 * {@link #upgrade(org.apache.http.HttpClientConnection, 067 * org.apache.http.conn.routing.HttpRoute, 068 * org.apache.http.protocol.HttpContext) upgrade} method to upgrade 069 * the connection after having executed {@code CONNECT} method to 070 * all intermediate proxy hops and and finally calling {@link #routeComplete( 071 * org.apache.http.HttpClientConnection, 072 * org.apache.http.conn.routing.HttpRoute, 073 * org.apache.http.protocol.HttpContext) routeComplete} to mark the route 074 * as fully completed. 075 * </p> 076 * 077 * @param route HTTP route of the requested connection. 078 * @param state expected state of the connection or {@code null} 079 * if the connection is not expected to carry any state. 080 */ 081 ConnectionRequest requestConnection(HttpRoute route, Object state); 082 083 /** 084 * Releases the connection back to the manager making it potentially 085 * re-usable by other consumers. Optionally, the maximum period 086 * of how long the manager should keep the connection alive can be 087 * defined using {@code validDuration} and {@code timeUnit} 088 * parameters. 089 * 090 * @param conn the managed connection to release. 091 * @param validDuration the duration of time this connection is valid for reuse. 092 * @param timeUnit the time unit. 093 * 094 * @see #closeExpiredConnections() 095 */ 096 void releaseConnection( 097 HttpClientConnection conn, Object newState, long validDuration, TimeUnit timeUnit); 098 099 /** 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}