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