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