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.core5.http.nio;
29
30 import java.util.concurrent.Future;
31
32 import org.apache.hc.core5.annotation.Contract;
33 import org.apache.hc.core5.annotation.ThreadingBehavior;
34 import org.apache.hc.core5.concurrent.BasicFuture;
35 import org.apache.hc.core5.concurrent.FutureCallback;
36 import org.apache.hc.core5.http.nio.support.BasicClientExchangeHandler;
37 import org.apache.hc.core5.http.protocol.HttpContext;
38 import org.apache.hc.core5.http.protocol.HttpCoreContext;
39
40 /**
41 * Client endpoint leased from a connection manager.
42 * <p>
43 * Once the endpoint is no longer needed it MUST be released with {@link #releaseAndReuse()}
44 * or {@link #releaseAndDiscard()}.
45 *
46 * @since 5.0
47 */
48 @Contract(threading = ThreadingBehavior.SAFE)
49 public abstract class AsyncClientEndpoint {
50
51 /**
52 * Initiates a message exchange using the given handler.
53 * <p>
54 * Once the endpoint is no longer needed it MUST be released with {@link #releaseAndReuse()}
55 * or {@link #releaseAndDiscard()}.
56 */
57 public abstract void execute(
58 AsyncClientExchangeHandler exchangeHandler,
59 HandlerFactory<AsyncPushConsumer> pushHandlerFactory,
60 HttpContext context);
61
62 /**
63 * Initiates a message exchange using the given handler.
64 * <p>
65 * Once the endpoint is no longer needed it MUST be released with {@link #releaseAndReuse()}
66 * or {@link #releaseAndDiscard()}.
67 */
68 public void execute(
69 final AsyncClientExchangeHandler exchangeHandler,
70 final HttpContext context) {
71 execute(exchangeHandler, null, context);
72 }
73
74 /**
75 * Releases the underlying connection back to the connection pool as re-usable.
76 */
77 public abstract void releaseAndReuse();
78
79 /**
80 * Shuts down the underlying connection and removes it from the connection pool.
81 */
82 public abstract void releaseAndDiscard();
83
84 /**
85 * Determines if the connection to the remote endpoint is still open and valid.
86 */
87 public abstract boolean isConnected();
88
89 /**
90 * Initiates message exchange using the given request producer and response consumer.
91 * <p>
92 * Once the endpoint is no longer needed it MUST be released with {@link #releaseAndReuse()}
93 * or {@link #releaseAndDiscard()}.
94 */
95 public final <T> Future<T> execute(
96 final AsyncRequestProducer requestProducer,
97 final AsyncResponseConsumer<T> responseConsumer,
98 final HandlerFactory<AsyncPushConsumer> pushHandlerFactory,
99 final HttpContext context,
100 final FutureCallback<T> callback) {
101 final BasicFuture<T> future = new BasicFuture<>(callback);
102 execute(new BasicClientExchangeHandler<>(requestProducer, responseConsumer,
103 new FutureCallback<T>() {
104
105 @Override
106 public void completed(final T result) {
107 future.completed(result);
108 }
109
110 @Override
111 public void failed(final Exception ex) {
112 future.failed(ex);
113 }
114
115 @Override
116 public void cancelled() {
117 future.cancel();
118 }
119
120 }),
121 pushHandlerFactory, context != null ? context : HttpCoreContext.create());
122 return future;
123 }
124
125 /**
126 * Initiates message exchange using the given request producer and response consumer.
127 * <p>
128 * Once the endpoint is no longer needed it MUST be released with {@link #releaseAndReuse()}
129 * or {@link #releaseAndDiscard()}.
130 */
131 public final <T> Future<T> execute(
132 final AsyncRequestProducer requestProducer,
133 final AsyncResponseConsumer<T> responseConsumer,
134 final HttpContext context,
135 final FutureCallback<T> callback) {
136 return execute(requestProducer, responseConsumer, null, context, callback);
137 }
138
139 /**
140 * Initiates a message exchange using the given request producer and response consumer.
141 * <p>
142 * Once the endpoint is no longer needed it MUST be released with {@link #releaseAndReuse()}
143 * or {@link #releaseAndDiscard()}.
144 */
145 public final <T> Future<T> execute(
146 final AsyncRequestProducer requestProducer,
147 final AsyncResponseConsumer<T> responseConsumer,
148 final FutureCallback<T> callback) {
149 return execute(requestProducer, responseConsumer, null, null, callback);
150 }
151
152 }