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.hc.client5.http.nio; 28 29 import java.util.concurrent.Future; 30 31 import org.apache.hc.client5.http.HttpRoute; 32 import org.apache.hc.core5.annotation.Contract; 33 import org.apache.hc.core5.annotation.ThreadingBehavior; 34 import org.apache.hc.core5.concurrent.FutureCallback; 35 import org.apache.hc.core5.http.protocol.HttpContext; 36 import org.apache.hc.core5.io.ModalCloseable; 37 import org.apache.hc.core5.reactor.ConnectionInitiator; 38 import org.apache.hc.core5.util.TimeValue; 39 import org.apache.hc.core5.util.Timeout; 40 41 /** 42 * Represents a manager of persistent non-blocking client connections. 43 * <p> 44 * The purpose of an HTTP connection manager is to serve as a factory for new 45 * HTTP connections, manage persistent connections and synchronize access to 46 * persistent connections making sure that only one thread of execution can 47 * have access to a connection at a time. 48 * </p> 49 * <p> 50 * Implementations of this interface must be thread-safe. Access to shared 51 * data must be synchronized as methods of this interface may be executed 52 * from multiple threads. 53 * </p> 54 * 55 * @since 5.0 56 */ 57 @Contract(threading = ThreadingBehavior.SAFE) 58 public interface AsyncClientConnectionManager extends ModalCloseable { 59 60 /** 61 * Returns a {@link Future} object which can be used to obtain 62 * an {@link AsyncConnectionEndpoint} or to cancel the request by calling 63 * {@link Future#cancel(boolean)}. 64 * <p> 65 * Please note that newly allocated endpoints can be leased 66 * {@link AsyncConnectionEndpoint#isConnected() disconnected}. The consumer 67 * of the endpoint is responsible for fully establishing the route to 68 * the endpoint target by calling {@link #connect(AsyncConnectionEndpoint, 69 * ConnectionInitiator, Timeout, Object, HttpContext, FutureCallback)} 70 * in order to connect directly to the target or to the first proxy hop, 71 * and optionally calling {@link #upgrade(AsyncConnectionEndpoint, Object, HttpContext)} 72 * method to upgrade the underlying transport to Transport Layer Security 73 * after having executed a {@code CONNECT} method to all intermediate 74 * proxy hops. 75 * 76 * @param id unique operation ID or {@code null}. 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 * @param requestTimeout lease request timeout. 81 * @param callback result callback. 82 */ 83 Future<AsyncConnectionEndpoint> lease( 84 String id, 85 HttpRoute route, 86 Object state, 87 Timeout requestTimeout, 88 FutureCallback<AsyncConnectionEndpoint> callback); 89 90 /** 91 * Releases the endpoint 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 endpoint the managed endpoint. 98 * @param newState the new connection state of {@code null} if state-less. 99 * @param validDuration the duration of time this connection is valid for reuse. 100 */ 101 void release(AsyncConnectionEndpoint endpoint, Object newState, TimeValue validDuration); 102 103 /** 104 * Connects the endpoint to the initial hop (connection target in case 105 * of a direct route or to the first proxy hop in case of a route via a proxy 106 * or multiple proxies). 107 * 108 * @param endpoint the managed endpoint. 109 * @param connectTimeout connect timeout. 110 * @param context the actual HTTP context. 111 * @param attachment connect request attachment. 112 * @param callback result callback. 113 */ 114 Future<AsyncConnectionEndpoint> connect( 115 AsyncConnectionEndpoint endpoint, 116 ConnectionInitiator connectionInitiator, 117 Timeout connectTimeout, 118 Object attachment, 119 HttpContext context, 120 FutureCallback<AsyncConnectionEndpoint> callback); 121 122 /** 123 * Upgrades transport security of the given endpoint by using the TLS security protocol. 124 * 125 * @param endpoint the managed endpoint. 126 * @param attachment the attachment the upgrade attachment object. 127 * @param context the actual HTTP context. 128 */ 129 void upgrade( 130 AsyncConnectionEndpoint endpoint, 131 Object attachment, 132 HttpContext context); 133 134 /** 135 * Upgrades transport security of the given endpoint by using the TLS security protocol. 136 * 137 * @param endpoint the managed endpoint. 138 * @param attachment the attachment the upgrade attachment object. 139 * @param context the actual HTTP context. 140 * @param callback result callback. 141 * 142 * @since 5.2 143 */ 144 default void upgrade( 145 AsyncConnectionEndpoint endpoint, 146 Object attachment, 147 HttpContext context, 148 FutureCallback<AsyncConnectionEndpoint> callback) { 149 upgrade(endpoint, attachment, context); 150 if (callback != null) { 151 callback.completed(endpoint); 152 } 153 } 154 155 }