org.asynchttpclient.AsyncHttpClient Maven / Gradle / Ivy
/*
* Copyright 2010 Ning, Inc.
*
* Ning licenses this file to you under the Apache License, version 2.0
* (the "License"); you may not use this file except in compliance with the
* License. You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*
*/
package org.asynchttpclient;
import java.io.Closeable;
import java.util.concurrent.Future;
import org.asynchttpclient.config.AsyncHttpClientConfig;
import org.asynchttpclient.future.ListenableFuture;
import org.asynchttpclient.handler.AsyncCompletionHandler;
import org.asynchttpclient.handler.AsyncHandler;
import org.asynchttpclient.request.BoundRequestBuilder;
import org.asynchttpclient.request.Request;
import org.asynchttpclient.request.RequestBuilder;
import org.asynchttpclient.request.SignatureCalculator;
import org.asynchttpclient.response.Response;
/**
* This class support asynchronous and synchronous HTTP request.
*
* To execute synchronous HTTP request, you just need to do
*
* AsyncHttpClient c = new AsyncHttpClient();
* Future f = c.prepareGet("http://www.ning.com/").execute();
*
* The code above will block until the response is fully received. To execute asynchronous HTTP request, you
* create an {@link AsyncHandler} or its abstract implementation, {@link AsyncCompletionHandler}
*
*
* AsyncHttpClient c = new AsyncHttpClient();
* Future f = c.prepareGet("http://www.ning.com/").execute(new AsyncCompletionHandler() {
*
* @Override
* public Response onCompleted(Response response) throws IOException {
* // Do something
* return response;
* }
*
* @Override
* public void onThrowable(Throwable t) {
* }
* });
* Response response = f.get();
*
* // We are just interested to retrieve the status code.
* Future f = c.prepareGet("http://www.ning.com/").execute(new AsyncCompletionHandler() {
*
* @Override
* public Integer onCompleted(Response response) throws IOException {
* // Do something
* return response.getStatusCode();
* }
*
* @Override
* public void onThrowable(Throwable t) {
* }
* });
* Integer statusCode = f.get();
*
* You can also have more control about the how the response is asynchronously processed by using a {@link AsyncHandler}
*
* AsyncHttpClient c = new AsyncHttpClient();
* Future f = c.prepareGet("http://www.ning.com/").execute(new AsyncHandler() {
* private StringBuilder builder = new StringBuilder();
*
* @Override
* public STATE onStatusReceived(HttpResponseStatus s) throws Exception {
* // return STATE.CONTINUE or STATE.ABORT
* return STATE.CONTINUE
* }
*
* @Override
* public STATE onHeadersReceived(HttpResponseHeaders bodyPart) throws Exception {
* // return STATE.CONTINUE or STATE.ABORT
* return STATE.CONTINUE
*
* }
* @Override
*
* public STATE onBodyPartReceived(HttpResponseBodyPart bodyPart) throws Exception {
* builder.append(new String(bodyPart));
* // return STATE.CONTINUE or STATE.ABORT
* return STATE.CONTINUE
* }
*
* @Override
* public String onCompleted() throws Exception {
* // Will be invoked once the response has been fully read or a ResponseComplete exception
* // has been thrown.
* return builder.toString();
* }
*
* @Override
* public void onThrowable(Throwable t) {
* }
* });
*
* String bodyResponse = f.get();
*
* This class can also be used without the need of {@link AsyncHandler}
*
* AsyncHttpClient c = new AsyncHttpClient();
* Future f = c.prepareGet(TARGET_URL).execute();
* Response r = f.get();
*
*
* Finally, you can configure the AsyncHttpClient using an {@link AsyncHttpClientConfig} instance
*
* AsyncHttpClient c = new AsyncHttpClient(new AsyncHttpClientConfig.Builder().setRequestTimeoutInMs(...).build());
* Future f = c.prepareGet(TARGET_URL).execute();
* Response r = f.get();
*
*
* An instance of this class will cache every HTTP 1.1 connections and close them when the {@link AsyncHttpClientConfig#getReadTimeout()}
* expires. This object can hold many persistent connections to different host.
*/
public interface AsyncHttpClient extends Closeable {
/**
* Return the asynchronous {@link AsyncHttpProvider}
*
* @return an {@link AsyncHttpProvider}
*/
AsyncHttpProvider getProvider();
/**
* Close the underlying connections.
*/
void close();
/**
* Asynchronous close the {@link AsyncHttpProvider} by spawning a thread and avoid blocking.
*/
void closeAsynchronously();
/**
* Return true if closed
*
* @return true if closed
*/
boolean isClosed();
/**
* Return the {@link AsyncHttpClientConfig}
*
* @return {@link AsyncHttpClientConfig}
*/
AsyncHttpClientConfig getConfig();
/**
* Set default signature calculator to use for requests build by this client instance
*/
AsyncHttpClient setSignatureCalculator(SignatureCalculator signatureCalculator);
/**
* Prepare an HTTP client GET request.
*
* @param url A well formed URL.
* @return {@link RequestBuilder}
*/
BoundRequestBuilder prepareGet(String url);
/**
* Prepare an HTTP client CONNECT request.
*
* @param url A well formed URL.
* @return {@link RequestBuilder}
*/
BoundRequestBuilder prepareConnect(String url);
/**
* Prepare an HTTP client OPTIONS request.
*
* @param url A well formed URL.
* @return {@link RequestBuilder}
*/
BoundRequestBuilder prepareOptions(String url);
/**
* Prepare an HTTP client HEAD request.
*
* @param url A well formed URL.
* @return {@link RequestBuilder}
*/
BoundRequestBuilder prepareHead(String url);
/**
* Prepare an HTTP client POST request.
*
* @param url A well formed URL.
* @return {@link RequestBuilder}
*/
BoundRequestBuilder preparePost(String url);
/**
* Prepare an HTTP client PUT request.
*
* @param url A well formed URL.
* @return {@link RequestBuilder}
*/
BoundRequestBuilder preparePut(String url);
/**
* Prepare an HTTP client DELETE request.
*
* @param url A well formed URL.
* @return {@link RequestBuilder}
*/
BoundRequestBuilder prepareDelete(String url);
/**
* Prepare an HTTP client PATCH request.
*
* @param url A well formed URL.
* @return {@link RequestBuilder}
*/
BoundRequestBuilder preparePatch(String url);
/**
* Prepare an HTTP client TRACE request.
*
* @param url A well formed URL.
* @return {@link RequestBuilder}
*/
BoundRequestBuilder prepareTrace(String url);
/**
* Construct a {@link RequestBuilder} using a {@link Request}
*
* @param request a {@link Request}
* @return {@link RequestBuilder}
*/
BoundRequestBuilder prepareRequest(Request request);
/**
* Execute an HTTP request.
*
* @param request {@link Request}
* @param handler an instance of {@link AsyncHandler}
* @param Type of the value that will be returned by the associated {@link java.util.concurrent.Future}
* @return a {@link Future} of type T
*/
ListenableFuture executeRequest(Request request, AsyncHandler handler);
/**
* Execute an HTTP request.
*
* @param request {@link Request}
* @return a {@link Future} of type Response
*/
ListenableFuture executeRequest(Request request);
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy