io.jsync.http.HttpClient Maven / Gradle / Ivy
Show all versions of jsync.io Show documentation
/*
* Copyright (c) 2011-2013 The original author or authors
* ------------------------------------------------------
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* and Apache License v2.0 which accompanies this distribution.
*
* The Eclipse Public License is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* The Apache License v2.0 is available at
* http://www.opensource.org/licenses/apache2.0.php
*
* You may elect to redistribute this code under either of these licenses.
*/
package io.jsync.http;
import io.jsync.ClientSSLSupport;
import io.jsync.Handler;
import io.jsync.MultiMap;
import io.jsync.TCPSupport;
import java.util.Set;
/**
* An HTTP client that maintains a pool of connections to a specific host, at a specific port. The client supports
* pipelining of requests.
* As well as HTTP requests, the client can act as a factory for {@code WebSocket websockets}.
* If an instance is instantiated from an event loop then the handlers
* of the instance will always be called on that same event loop.
* If an instance is instantiated from some other arbitrary Java thread (i.e. when running embedded) then
* and event loop will be assigned to the instance and used when any of its handlers
* are called.
* Instances of HttpClient are thread-safe.
*
* @author Tim Fox
*/
public interface HttpClient extends ClientSSLSupport, TCPSupport {
/**
* Set an exception handler
*
* @return A reference to this, so multiple invocations can be chained together.
*/
HttpClient exceptionHandler(Handler handler);
/**
* Returns the maximum number of connections in the pool
*/
int getMaxPoolSize();
/**
* Set the maximum pool size
* The client will maintain up to {@code maxConnections} HTTP connections in an internal pool
*
* @return A reference to this, so multiple invocations can be chained together.
*/
HttpClient setMaxPoolSize(int maxConnections);
/**
* Returns the maximum number of waiting requests
*/
int getMaxWaiterQueueSize();
/**
* Set the maximum waiter queue size
* The client will keep up to {@code maxWaiterQueueSize} requests in an internal waiting queue
*
* @return A reference to this, so multiple invocations can be chained together.
*/
HttpClient setMaxWaiterQueueSize(int maxWaiterQueueSize);
/**
* Returns the maximum number of outstanding requests for each connection
*/
int getConnectionMaxOutstandingRequestCount();
/**
* Set the maximum outstanding request size for every connection
* The connection will keep up to {@code connectionMaxOutstandingRequestCount} outstanding requests
*
* @return A reference to this, so multiple invocations can be chained together.
*/
HttpClient setConnectionMaxOutstandingRequestCount(int connectionMaxOutstandingRequestCount);
/**
* @return Is the client keep alive?
*/
boolean isKeepAlive();
/**
* If {@code keepAlive} is {@code true} then the connection will be returned to the pool after the request has ended (if
* {@code pipelining} is {@code true}), or after both request and response have ended (if {@code pipelining} is
* {@code false}). In this manner, many HTTP requests can reuse the same HTTP connection.
* Keep alive connections will not be closed until the {@link #close() close()} method is invoked.
* If {@code keepAlive} is {@code false} then a new connection will be created for each request and it won't ever go in the pool,
* the connection will get closed after the response has been received. Even with no keep alive,
* the client will not allow more than {@link #getMaxPoolSize()} connections to be created at any one time.
*
* @return A reference to this, so multiple invocations can be chained together.
*/
HttpClient setKeepAlive(boolean keepAlive);
/**
* @return Is enabled HTTP pipelining?
*/
boolean isPipelining();
/**
* If {@code pipelining} is {@code true} and {@code keepAlive} is also {@code true} then, after the request has ended the
* connection will be returned to the pool where it can be used by another request. In this manner, many HTTP requests can
* be pipelined over an HTTP connection. If {@code pipelining} is {@code false} and {@code keepAlive} is {@code true}, then
* the connection will be returned to the pool when both request and response have ended. If {@code keepAlive} is false,
* then pipelining value is ignored.
*
* @return A reference to this, so multiple invocations can be chained together.
*/
HttpClient setPipelining(boolean pipelining);
/**
* @return The port
*/
int getPort();
/**
* Set the port that the client will attempt to connect to the server on to {@code port}. The default value is
* {@code 80}
*
* @return A reference to this, so multiple invocations can be chained together.
*/
HttpClient setPort(int port);
/**
* @return The host
*/
String getHost();
/**
* Set the host that the client will attempt to connect to the server on to {@code host}. The default value is
* {@code localhost}
*
* @return A reference to this, so multiple invocations can be chained together.
*/
HttpClient setHost(String host);
/**
* Attempt to connect an HTML5 websocket to the specified URI
* The connect is done asynchronously and {@code wsConnect} is called back with the websocket
*/
HttpClient connectWebsocket(String uri, Handler wsConnect);
/**
* Attempt to connect an HTML5 websocket to the specified URI
* This version of the method allows you to specify the websockets version using the {@code wsVersion parameter}
* The connect is done asynchronously and {@code wsConnect} is called back with the websocket
*/
HttpClient connectWebsocket(String uri, WebSocketVersion wsVersion, Handler wsConnect);
/**
* Attempt to connect an HTML5 websocket to the specified URI
* This version of the method allows you to specify the websockets version using the {@code wsVersion parameter}
* You can also specify a set of headers to append to the upgrade request
* The connect is done asynchronously and {@code wsConnect} is called back with the websocket
*/
HttpClient connectWebsocket(String uri, WebSocketVersion wsVersion, MultiMap headers, Handler wsConnect);
/**
* Attempt to connect an HTML5 websocket to the specified URI
* This version of the method allows you to specify the websockets version using the {@code wsVersion parameter}
* You can also specify a set of headers to append to the upgrade request and specify the supported subprotocols.
* The connect is done asynchronously and {@code wsConnect} is called back with the websocket
*/
HttpClient connectWebsocket(String uri, WebSocketVersion wsVersion, MultiMap headers, Set subprotocols, Handler wsConnect);
/**
* This is a quick version of the {@link #get(String, io.jsync.Handler)}
* method where you do not want to do anything with the request before sending.
* Normally with any of the HTTP methods you create the request then when you are ready to send it you call
* {@link HttpClientRequest#end()} on it. With this method the request is immediately sent.
* When an HTTP response is received from the server the {@code responseHandler} is called passing in the response.
*/
HttpClient getNow(String uri, Handler responseHandler);
/**
* This method works in the same manner as {@link #getNow(String, io.jsync.Handler)},
* except that it allows you specify a set of {@code headers} that will be sent with the request.
*/
HttpClient getNow(String uri, MultiMap headers, Handler responseHandler);
/**
* This method returns an {@link HttpClientRequest} instance which represents an HTTP OPTIONS request with the specified {@code uri}.
* When an HTTP response is received from the server the {@code responseHandler} is called passing in the response.
*/
HttpClientRequest options(String uri, Handler responseHandler);
/**
* This method returns an {@link HttpClientRequest} instance which represents an HTTP GET request with the specified {@code uri}.
* When an HTTP response is received from the server the {@code responseHandler} is called passing in the response.
*/
HttpClientRequest get(String uri, Handler responseHandler);
/**
* This method returns an {@link HttpClientRequest} instance which represents an HTTP HEAD request with the specified {@code uri}.
* When an HTTP response is received from the server the {@code responseHandler} is called passing in the response.
*/
HttpClientRequest head(String uri, Handler responseHandler);
/**
* This method returns an {@link HttpClientRequest} instance which represents an HTTP POST request with the specified {@code uri}.
* When an HTTP response is received from the server the {@code responseHandler} is called passing in the response.
*/
HttpClientRequest post(String uri, Handler responseHandler);
/**
* This method returns an {@link HttpClientRequest} instance which represents an HTTP PUT request with the specified {@code uri}.
* When an HTTP response is received from the server the {@code responseHandler} is called passing in the response.
*/
HttpClientRequest put(String uri, Handler responseHandler);
/**
* This method returns an {@link HttpClientRequest} instance which represents an HTTP DELETE request with the specified {@code uri}.
* When an HTTP response is received from the server the {@code responseHandler} is called passing in the response.
*/
HttpClientRequest delete(String uri, Handler responseHandler);
/**
* This method returns an {@link HttpClientRequest} instance which represents an HTTP TRACE request with the specified {@code uri}.
* When an HTTP response is received from the server the {@code responseHandler} is called passing in the response.
*/
HttpClientRequest trace(String uri, Handler responseHandler);
/**
* This method returns an {@link HttpClientRequest} instance which represents an HTTP CONNECT request with the specified {@code uri}.
* When an HTTP response is received from the server the {@code responseHandler} is called passing in the response.
*
* Because of the nature of CONNECT the connection is automatically upgraded to raw TCP if a response code of 200 is received from the
* remote peer. In this case you are able to get hold of the raw TCP socket via calling {@link HttpClientResponse#netSocket()}.
*/
HttpClientRequest connect(String uri, Handler responseHandler);
/**
* This method returns an {@link HttpClientRequest} instance which represents an HTTP PATCH request with the specified {@code uri}.
* When an HTTP response is received from the server the {@code responseHandler} is called passing in the response.
*/
HttpClientRequest patch(String uri, Handler responseHandler);
/**
* This method returns an {@link HttpClientRequest} instance which represents an HTTP request with the specified {@code uri}.
* The specific HTTP method (e.g. GET, POST, PUT etc) is specified using the parameter {@code method}
* When an HTTP response is received from the server the {@code responseHandler} is called passing in the response.
*/
HttpClientRequest request(String method, String uri, Handler responseHandler);
/**
* Close the HTTP client. This will cause any pooled HTTP connections to be closed.
*/
void close();
/**
* @return true if this client will validate the remote server's certificate hostname against the requested host
*/
boolean isVerifyHost();
/**
* If {@code verifyHost} is {@code true}, then the client will try to validate the remote server's certificate
* hostname against the requested host. Should default to 'true'.
* This method should only be used in SSL mode, i.e. after {@link #setSSL(boolean)} has been set to {@code true}.
*
* @return A reference to this, so multiple invocations can be chained together.
*/
HttpClient setVerifyHost(boolean verifyHost);
/**
* @return The connect timeout in milliseconds
*/
int getConnectTimeout();
/**
* Set the connect timeout in milliseconds.
*
* @return a reference to this so multiple method calls can be chained together
*/
HttpClient setConnectTimeout(int timeout);
/**
* Returns {@code true} if the {@link HttpClient} should try to use compression.
*/
boolean getTryUseCompression();
/**
* Set if the {@link HttpClient} should try to use compression.
*/
HttpClient setTryUseCompression(boolean tryUseCompression);
/**
* Get the maximum websocket frame size in bytes.
*/
int getMaxWebSocketFrameSize();
/**
* Sets the maximum websocket frame size in bytes. Default is 65536 bytes.
*
* @param maxSize The size in bytes
*/
HttpClient setMaxWebSocketFrameSize(int maxSize);
}