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 }