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.nio;
29
30 import java.io.IOException;
31 import java.util.concurrent.Future;
32
33 import org.apache.hc.client5.http.EndpointInfo;
34 import org.apache.hc.core5.annotation.Contract;
35 import org.apache.hc.core5.annotation.ThreadingBehavior;
36 import org.apache.hc.core5.concurrent.BasicFuture;
37 import org.apache.hc.core5.concurrent.FutureCallback;
38 import org.apache.hc.core5.http.nio.AsyncClientExchangeHandler;
39 import org.apache.hc.core5.http.nio.AsyncPushConsumer;
40 import org.apache.hc.core5.http.nio.AsyncRequestProducer;
41 import org.apache.hc.core5.http.nio.AsyncResponseConsumer;
42 import org.apache.hc.core5.http.nio.HandlerFactory;
43 import org.apache.hc.core5.http.nio.support.BasicClientExchangeHandler;
44 import org.apache.hc.core5.http.protocol.HttpContext;
45 import org.apache.hc.core5.http.protocol.HttpCoreContext;
46 import org.apache.hc.core5.io.CloseMode;
47 import org.apache.hc.core5.io.ModalCloseable;
48 import org.apache.hc.core5.util.Timeout;
49
50 /**
51 * Client connection endpoint that can be used to execute message exchanges.
52 *
53 * @since 5.0
54 */
55 @Contract(threading = ThreadingBehavior.SAFE)
56 public abstract class AsyncConnectionEndpoint implements ModalCloseable {
57
58 /**
59 * Initiates a message exchange using the given handler.
60 *
61 * @param id unique operation ID or {@code null}.
62 * @param exchangeHandler the message exchange handler.
63 * @param pushHandlerFactory the push handler factory.
64 * @param context the execution context.
65 */
66 public abstract void execute(
67 String id,
68 AsyncClientExchangeHandler exchangeHandler,
69 HandlerFactory<AsyncPushConsumer> pushHandlerFactory,
70 HttpContext context);
71
72 /**
73 * Determines if the connection to the remote endpoint is still open and valid.
74 */
75 public abstract boolean isConnected();
76
77 /**
78 * Sets socket timeout.
79 *
80 * @param timeout the socket timeout.
81 */
82 public abstract void setSocketTimeout(Timeout timeout);
83
84 @Override
85 public final void close() throws IOException {
86 close(CloseMode.GRACEFUL);
87 }
88
89 /**
90 * Initiates a message exchange using the given handler.
91 *
92 * @param id unique operation ID or {@code null}.
93 * @param exchangeHandler the message exchange handler.
94 * @param context the execution context.
95 */
96 public void execute(
97 final String id,
98 final AsyncClientExchangeHandler exchangeHandler,
99 final HttpContext context) {
100 execute(id, exchangeHandler, null, context);
101 }
102
103 /**
104 * Initiates message exchange using the given request producer and response consumer.
105 *
106 * @param id unique operation ID or {@code null}.
107 * @param requestProducer the request producer.
108 * @param responseConsumer the response consumer.
109 * @param pushHandlerFactory the push handler factory.
110 * @param context the execution context.
111 * @param callback the result callback.
112 * @param <T> the result representation.
113 * @return the result future.
114 */
115 public final <T> Future<T> execute(
116 final String id,
117 final AsyncRequestProducer requestProducer,
118 final AsyncResponseConsumer<T> responseConsumer,
119 final HandlerFactory<AsyncPushConsumer> pushHandlerFactory,
120 final HttpContext context,
121 final FutureCallback<T> callback) {
122 final BasicFuture<T> future = new BasicFuture<>(callback);
123 execute(id, new BasicClientExchangeHandler<>(requestProducer, responseConsumer,
124 new FutureCallback<T>() {
125
126 @Override
127 public void completed(final T result) {
128 future.completed(result);
129 }
130
131 @Override
132 public void failed(final Exception ex) {
133 future.failed(ex);
134 }
135
136 @Override
137 public void cancelled() {
138 future.cancel();
139 }
140
141 }),
142 pushHandlerFactory,
143 context != null ? context : HttpCoreContext.create());
144 return future;
145 }
146
147 /**
148 * Initiates message exchange using the given request producer and response consumer.
149 *
150 * @param id unique operation ID or {@code null}.
151 * @param requestProducer the request producer.
152 * @param responseConsumer the response consumer.
153 * @param context the execution context.
154 * @param callback the result callback.
155 * @param <T> the result representation.
156 * @return the result future.
157 */
158 public final <T> Future<T> execute(
159 final String id,
160 final AsyncRequestProducer requestProducer,
161 final AsyncResponseConsumer<T> responseConsumer,
162 final HttpContext context,
163 final FutureCallback<T> callback) {
164 return execute(id, requestProducer, responseConsumer, null, context, callback);
165 }
166
167 /**
168 * Initiates message exchange using the given request producer and response consumer.
169 *
170 * @param id unique operation ID or {@code null}.
171 * @param requestProducer the request producer.
172 * @param responseConsumer the response consumer.
173 * @param pushHandlerFactory the push handler factory.
174 * @param callback the result callback.
175 * @param <T> the result representation.
176 * @return the result future.
177 */
178 public final <T> Future<T> execute(
179 final String id,
180 final AsyncRequestProducer requestProducer,
181 final AsyncResponseConsumer<T> responseConsumer,
182 final HandlerFactory<AsyncPushConsumer> pushHandlerFactory,
183 final FutureCallback<T> callback) {
184 return execute(id, requestProducer, responseConsumer, pushHandlerFactory, null, callback);
185 }
186
187 /**
188 * Initiates message exchange using the given request producer and response consumer.
189 *
190 * @param id unique operation ID or {@code null}.
191 * @param requestProducer the request producer.
192 * @param responseConsumer the response consumer.
193 * @param callback the result callback.
194 * @param <T> the result representation.
195 * @return the result future.
196 */
197 public final <T> Future<T> execute(
198 final String id,
199 final AsyncRequestProducer requestProducer,
200 final AsyncResponseConsumer<T> responseConsumer,
201 final FutureCallback<T> callback) {
202 return execute(id, requestProducer, responseConsumer, null, null, callback);
203 }
204
205 /**
206 * Returns information about the endpoint or {@code null} when not connected.
207 *
208 * @since 5.4
209 */
210 public EndpointInfo getInfo() {
211 return null;
212 }
213
214 }