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