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