View Javadoc
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       * Initiates message exchange using the given request producer and response consumer.
86       * <p>
87       * Once the endpoint is no longer needed it MUST be released with {@link #releaseAndReuse()}
88       * or {@link #releaseAndDiscard()}.
89       */
90      public final <T> Future<T> execute(
91              final AsyncRequestProducer requestProducer,
92              final AsyncResponseConsumer<T> responseConsumer,
93              final HandlerFactory<AsyncPushConsumer> pushHandlerFactory,
94              final HttpContext context,
95              final FutureCallback<T> callback) {
96          final BasicFuture<T> future = new BasicFuture<>(callback);
97          execute(new BasicClientExchangeHandler<>(requestProducer, responseConsumer,
98                          new FutureCallback<T>() {
99  
100                             @Override
101                             public void completed(final T result) {
102                                 future.completed(result);
103                             }
104 
105                             @Override
106                             public void failed(final Exception ex) {
107                                 future.failed(ex);
108                             }
109 
110                             @Override
111                             public void cancelled() {
112                                 future.cancel();
113                             }
114 
115                         }),
116                 pushHandlerFactory, context != null ? context : HttpCoreContext.create());
117         return future;
118     }
119 
120     /**
121      * Initiates message exchange using the given request producer and response consumer.
122      * <p>
123      * Once the endpoint is no longer needed it MUST be released with {@link #releaseAndReuse()}
124      * or {@link #releaseAndDiscard()}.
125      */
126     public final <T> Future<T> execute(
127             final AsyncRequestProducer requestProducer,
128             final AsyncResponseConsumer<T> responseConsumer,
129             final HttpContext context,
130             final FutureCallback<T> callback) {
131         return execute(requestProducer, responseConsumer, null, context, callback);
132     }
133 
134     /**
135      * Initiates a message exchange using the given request producer and response consumer.
136      * <p>
137      * Once the endpoint is no longer needed it MUST be released with {@link #releaseAndReuse()}
138      * or {@link #releaseAndDiscard()}.
139      */
140     public final <T> Future<T> execute(
141             final AsyncRequestProducer requestProducer,
142             final AsyncResponseConsumer<T> responseConsumer,
143             final FutureCallback<T> callback) {
144         return execute(requestProducer, responseConsumer, null, null, callback);
145     }
146 
147 }