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