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 28 package org.apache.hc.client5.http.async; 29 30 import org.apache.hc.client5.http.EndpointInfo; 31 import org.apache.hc.client5.http.HttpRoute; 32 import org.apache.hc.client5.http.protocol.HttpClientContext; 33 import org.apache.hc.core5.annotation.Internal; 34 import org.apache.hc.core5.concurrent.Cancellable; 35 import org.apache.hc.core5.concurrent.FutureCallback; 36 import org.apache.hc.core5.http.nio.AsyncClientExchangeHandler; 37 import org.apache.hc.core5.util.TimeValue; 38 39 /** 40 * Execution runtime that provides access to the underlying connection endpoint and helps 41 * manager its life cycle. 42 * <p> 43 * This interface is considered internal and generally ought not be used or accessed 44 * by custom request exec handlers. 45 * </p> 46 * 47 * @since 5.0 48 */ 49 @Internal 50 public interface AsyncExecRuntime { 51 52 /** 53 * Determines of a connection endpoint has been acquired. 54 * 55 * @return {@code true} if an endpoint has been acquired, {@code false} otherwise. 56 */ 57 boolean isEndpointAcquired(); 58 59 /** 60 * Initiates operation to acquire a connection endpoint. Endpoints can leased from a pool 61 * or unconnected new endpoint can be created. 62 * 63 * @param id unique operation ID or {@code null}. 64 * @param route the connection route. 65 * @param state the expected connection state. May be {@code null} if connection 66 * can be state-less or its state is irrelevant. 67 * @param context the execution context. 68 * @param callback the result callback. 69 * @return handle that can be used to cancel the operation. 70 */ 71 Cancellable acquireEndpoint( 72 String id, 73 HttpRoute route, 74 Object state, 75 HttpClientContext context, 76 FutureCallback<AsyncExecRuntime> callback); 77 78 /** 79 * Releases the acquired endpoint potentially making it available for re-use. 80 */ 81 void releaseEndpoint(); 82 83 /** 84 * Shuts down and discards the acquired endpoint. 85 */ 86 void discardEndpoint(); 87 88 /** 89 * Determines of there the endpoint is connected to the initial hop (connection target 90 * in case of a direct route or to the first proxy hop in case of a route via a proxy 91 * or multiple proxies). 92 * 93 * @return {@code true} if the endpoint is connected, {@code false} otherwise. 94 */ 95 boolean isEndpointConnected(); 96 97 /** 98 * Initiates operation to connect the local endpoint to the initial hop (connection 99 * target in case of a direct route or to the first proxy hop in case of a route 100 * via a proxy or multiple proxies). 101 * 102 * @param context the execution context. 103 * @param callback the result callback. 104 * @return handle that can be used to cancel the operation. 105 */ 106 Cancellable connectEndpoint( 107 HttpClientContext context, 108 FutureCallback<AsyncExecRuntime> callback); 109 110 /** 111 * Disconnects the local endpoint from the initial hop in the connection route. 112 */ 113 void disconnectEndpoint(); 114 115 /** 116 * Upgrades transport security of the active connection by using the TLS security protocol. 117 * 118 * @param context the execution context. 119 */ 120 void upgradeTls(HttpClientContext context); 121 122 /** 123 * Upgrades transport security of the active connection by using the TLS security protocol. 124 * 125 * @param context the execution context. 126 * 127 * @since 5.2 128 */ 129 default void upgradeTls(HttpClientContext context, 130 FutureCallback<AsyncExecRuntime> callback) { 131 upgradeTls(context); 132 if (callback != null) { 133 callback.completed(this); 134 } 135 } 136 137 /** 138 * Returns information about the underlying endpoint when connected or {@code null} otherwise. 139 */ 140 default EndpointInfo getEndpointInfo() { 141 return null; 142 } 143 144 /** 145 * Validates the connection making sure it can be used to execute requests. 146 * 147 * @return {@code true} if the connection is valid, {@code false}. 148 */ 149 boolean validateConnection(); 150 151 /** 152 * Initiates a message exchange using the given handler. 153 * 154 * @param id unique operation ID or {@code null}. 155 * @param exchangeHandler the client message handler. 156 * @param context the execution context. 157 */ 158 Cancellable execute( 159 String id, 160 AsyncClientExchangeHandler exchangeHandler, 161 HttpClientContext context); 162 163 /** 164 * Marks the connection as potentially re-usable for the given period of time 165 * and also marks it as stateful if the state representation is given. 166 * @param state the connection state representation or {@code null} if stateless. 167 * @param validityTime the period of time this connection is valid for. 168 */ 169 void markConnectionReusable(Object state, TimeValue validityTime); 170 171 /** 172 * Marks the connection as non re-usable. 173 */ 174 void markConnectionNonReusable(); 175 176 /** 177 * Forks this runtime for parallel execution. 178 * 179 * @return another runtime with the same configuration. 180 */ 181 AsyncExecRuntime fork(); 182 183 }