net.shibboleth.utilities.java.support.httpclient
Class HttpClientBuilder

java.lang.Object
  net.shibboleth.utilities.java.support.httpclient.HttpClientBuilder

public class HttpClientBuilder
extends Object

Builder used to construct HttpClient objects configured with particular settings.

Field Summary

private boolean	connectionCloseAfterResponse Whether to instruct the server to close the connection after it has sent its response.
private boolean	connectionDisregardSslCertificate Whether the SSL certificates used by the responder should be ignored.
private String	connectionProxyHost Host name of the HTTP proxy server through which connections will be made.
private String	connectionProxyPassword Password used to connect to the HTTP proxy server.
private int	connectionProxyPort Port number of the HTTP proxy server through which connections will be made.
private String	connectionProxyUsername Username used to connect to the HTTP proxy server.
private int	connectionsMaxPerRoute Maximum number of connections that may be opened to a single host.
private int	connectionsMaxTotal Total number of connections that may be open.
private boolean	connectionStalecheck Whether to check a connection for staleness before using.
private int	connectionTimeout Maximum length of time in milliseconds to wait for the connection to be established.
private String	httpContentCharSet Character set used for HTTP entity content.
private boolean	httpFollowRedirects Whether to follow HTTP redirects.
private int	socketBufferSize Socket buffer size in bytes.
private InetAddress	socketLocalAddress Local IP address used when establishing connections.
private int	socketTimeout Maximum period inactivity between two consecutive data packets in milliseconds.

Constructor Summary

HttpClientBuilder()
Constructor.

Method Summary

HttpClient	buildClient() Constructs an HttpClient using the settings of this builder.
private ClientConnectionManager	buildConnectionManager() Builds the connection manager used by the HTTP client.
private SchemeRegistry	buildSchemeRegistry() Creates the default scheme registry for connection.
String	getConnectionProxyHost() Gets the hostname of the default proxy used when making connection.
String	getConnectionProxyPassword() Gets the password used when authenticating to the proxy.
int	getConnectionProxyPort() Gets the port of the default proxy used when making connection.
String	getConnectionProxyUsername() Gets the username to use when authenticating to the proxy.
int	getConnectionsMaxPerRoute() Gets the maximum number of connection per route.
int	getConnectionsMaxTotal() Gets the maximum number of connections that may be open at any given time when pooling is used.
int	getConnectionTimeout() Gets the maximum length of time in milliseconds to wait for the connection to be established.
String	getHttpContentCharSet() Gets the character set used with the HTTP entity (body).
int	getSocketBufferSize() Gets the size of the socket buffer, in bytes, used for request/response buffering.
InetAddress	getSocketLocalAddress() Gets the local IP address used when making requests.
int	getSocketTimeout() Gets the maximum period inactivity between two consecutive data packets in milliseconds.
boolean	isConnectionCloseAfterResponse() Gets whether to instruct the server to close the connection after it has sent its response.
boolean	isConnectionDisregardSslCertificate() Gets whether the responder's SSL certificate should be ignored.
boolean	isConnectionStalecheck() Gets whether reused connections are checked if they are closed before being used by the client.
boolean	isHttpFollowRedirects() Gets whether HTTP redirects will be followed.
void	resetDefaults() Resets all builder parameters to their defaults.
void	setConnectionCloseAfterResponse(boolean close) Sets whether to instruct the server to close the connection after it has sent its response.
void	setConnectionDisregardSslCertificate(boolean disregard) Sets whether the responder's SSL certificate should be ignored.
void	setConnectionProxyHost(String host) Sets the hostname of the default proxy used when making connection.
void	setConnectionProxyPassword(String password) Sets the password used when authenticating to the proxy.
void	setConnectionProxyPort(int port) Sets the port of the default proxy used when making connection.
void	setConnectionProxyUsername(String usename) Sets the username to use when authenticating to the proxy.
void	setConnectionsMaxPerRoute(int max) Sets the maximum number of connection per route.
void	setConnectionsMaxTotal(int max) Sets the maximum number of connections that may be open at any given time when pooling is used.
void	setConnectionStalecheck(boolean check) Sets whether reused connections are checked if they are closed before being used by the client.
void	setConnectionTimeout(int timeout) Sets the maximum length of time in milliseconds to wait for the connection to be established.
void	setHttpContentCharSet(String charSet) Sets the character set used with the HTTP entity (body).
void	setHttpFollowRedirects(boolean followRedirects) Gets whether HTTP redirects will be followed.
void	setSocketBufferSize(int size) Sets size of the socket buffer, in bytes, used for request/response buffering.
void	setSocketLocalAddress(InetAddress address) Sets the local IP address used when making requests.
void	setSocketLocalAddress(String ipOrHost) Sets the local IP address used when making requests.
void	setSocketTimeout(int timeout) Sets the maximum period inactivity between two consecutive data packets in milliseconds.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

socketLocalAddress

private InetAddress socketLocalAddress

Local IP address used when establishing connections. Default value: system default local address

socketTimeout

private int socketTimeout

Maximum period inactivity between two consecutive data packets in milliseconds. Default value: 5000 (5 seconds)

socketBufferSize

private int socketBufferSize

Socket buffer size in bytes. Default size is 8192 bytes.

connectionTimeout

private int connectionTimeout

Maximum length of time in milliseconds to wait for the connection to be established. Default value: 5000 (5 seconds)

connectionDisregardSslCertificate

private boolean connectionDisregardSslCertificate

Whether the SSL certificates used by the responder should be ignored. Default value: false

connectionCloseAfterResponse

private boolean connectionCloseAfterResponse

Whether to instruct the server to close the connection after it has sent its response. Default value: true

connectionStalecheck

private boolean connectionStalecheck

Whether to check a connection for staleness before using. This can be an expensive operation. Default value: false

connectionsMaxTotal

private int connectionsMaxTotal

Total number of connections that may be open. Default value: 20

connectionsMaxPerRoute

private int connectionsMaxPerRoute

Maximum number of connections that may be opened to a single host. Default value: 2

connectionProxyHost

private String connectionProxyHost

Host name of the HTTP proxy server through which connections will be made. Default value: null.

connectionProxyPort

private int connectionProxyPort

Port number of the HTTP proxy server through which connections will be made. Default value: 8080.

connectionProxyUsername

private String connectionProxyUsername

Username used to connect to the HTTP proxy server. Default value: null.

connectionProxyPassword

private String connectionProxyPassword

Password used to connect to the HTTP proxy server. Default value: null.

httpFollowRedirects

private boolean httpFollowRedirects

Whether to follow HTTP redirects. Default value: true

httpContentCharSet

private String httpContentCharSet

Character set used for HTTP entity content. Default value: UTF-8

Constructor Detail

HttpClientBuilder

public HttpClientBuilder()

Constructor.

Method Detail

resetDefaults

public void resetDefaults()

Resets all builder parameters to their defaults.

getSocketLocalAddress

public InetAddress getSocketLocalAddress()

Gets the local IP address used when making requests.

Returns:

local IP address used when making requests

setSocketLocalAddress

public void setSocketLocalAddress(InetAddress address)

Sets the local IP address used when making requests.

Parameters:

address - local IP address used when making requests

setSocketLocalAddress

public void setSocketLocalAddress(String ipOrHost)
                           throws UnknownHostException

Sets the local IP address used when making requests.

Parameters:

ipOrHost - IP address or hostname, never null

Throws:

UnknownHostException - thrown if the given IP or hostname can not be resolved

getSocketTimeout

public int getSocketTimeout()

Gets the maximum period inactivity between two consecutive data packets in milliseconds. A value of less than 1 indicates no timeout.

Returns:

maximum period inactivity between two consecutive data packets in milliseconds

setSocketTimeout

public void setSocketTimeout(int timeout)

Sets the maximum period inactivity between two consecutive data packets in milliseconds. A value of less than 1 indicates no timeout.

Parameters:

timeout - maximum period inactivity between two consecutive data packets in milliseconds

getSocketBufferSize

public int getSocketBufferSize()

Gets the size of the socket buffer, in bytes, used for request/response buffering.

Returns:

size of the socket buffer, in bytes, used for request/response buffering

setSocketBufferSize

public void setSocketBufferSize(int size)

Sets size of the socket buffer, in bytes, used for request/response buffering.

Parameters:

size - size of the socket buffer, in bytes, used for request/response buffering; must be greater than 0

getConnectionTimeout

public int getConnectionTimeout()

Gets the maximum length of time in milliseconds to wait for the connection to be established. A value of less than 1 indicates no timeout.

Returns:

maximum length of time in milliseconds to wait for the connection to be established

setConnectionTimeout

public void setConnectionTimeout(int timeout)

Sets the maximum length of time in milliseconds to wait for the connection to be established. A value of less than 1 indicates no timeout.

Parameters:

timeout - maximum length of time in milliseconds to wait for the connection to be established

isConnectionDisregardSslCertificate

public boolean isConnectionDisregardSslCertificate()

Gets whether the responder's SSL certificate should be ignored.

Returns:

whether the responder's SSL certificate should be ignored

setConnectionDisregardSslCertificate

public void setConnectionDisregardSslCertificate(boolean disregard)

Sets whether the responder's SSL certificate should be ignored.

Parameters:

disregard - whether the responder's SSL certificate should be ignored

isConnectionCloseAfterResponse

public boolean isConnectionCloseAfterResponse()

Gets whether to instruct the server to close the connection after it has sent its response.

Returns:

whether to instruct the server to close the connection after it has sent its response

setConnectionCloseAfterResponse

public void setConnectionCloseAfterResponse(boolean close)

Sets whether to instruct the server to close the connection after it has sent its response.

Parameters:

close - whether to instruct the server to close the connection after it has sent its response

isConnectionStalecheck

public boolean isConnectionStalecheck()

Gets whether reused connections are checked if they are closed before being used by the client.

Returns:

whether reused connections are checked if they are closed before being used by the client

setConnectionStalecheck

public void setConnectionStalecheck(boolean check)

Sets whether reused connections are checked if they are closed before being used by the client. Checking can take up to 30ms (per request). If checking is turned off an I/O error occurs if the connection is used request. This should be enabled uncles the code using the client explicitly handles the error case and retries connection as appropriate.

Parameters:

check - whether reused connections are checked if they are closed before being used by the client

getConnectionsMaxTotal

public int getConnectionsMaxTotal()

Gets the maximum number of connections that may be open at any given time when pooling is used.

Returns:

maximum number of connections that may be open at any given time when pooling is used

setConnectionsMaxTotal

public void setConnectionsMaxTotal(int max)

Sets the maximum number of connections that may be open at any given time when pooling is used.

Parameters:

max - maximum number of connections that may be open at any given time when pooling is used; must be greater than zero

getConnectionsMaxPerRoute

public int getConnectionsMaxPerRoute()

Gets the maximum number of connection per route. A route is the destination host plus all intermediary proxies.

Returns:

maximum number of connection per route

setConnectionsMaxPerRoute

public void setConnectionsMaxPerRoute(int max)

Sets the maximum number of connection per route. A route is the destination host plus all intermediary proxies.

Parameters:

max - maximum number of connection per route; must be greater than zero

getConnectionProxyHost

public String getConnectionProxyHost()

Gets the hostname of the default proxy used when making connection. A null indicates no default proxy.

Returns:

hostname of the default proxy used when making connection

setConnectionProxyHost

public void setConnectionProxyHost(String host)

Sets the hostname of the default proxy used when making connection. A null indicates no default proxy.

Parameters:

host - hostname of the default proxy used when making connection

getConnectionProxyPort

public int getConnectionProxyPort()

Gets the port of the default proxy used when making connection.

Returns:

port of the default proxy used when making connection

setConnectionProxyPort

public void setConnectionProxyPort(int port)

Sets the port of the default proxy used when making connection.

Parameters:

port - port of the default proxy used when making connection; must be greater than 0 and less than 65536

getConnectionProxyUsername

public String getConnectionProxyUsername()

Gets the username to use when authenticating to the proxy.

Returns:

username to use when authenticating to the proxy

setConnectionProxyUsername

public void setConnectionProxyUsername(String usename)

Sets the username to use when authenticating to the proxy.

Parameters:

usename - username to use when authenticating to the proxy; may be null

getConnectionProxyPassword

public String getConnectionProxyPassword()

Gets the password used when authenticating to the proxy.

Returns:

password used when authenticating to the proxy

setConnectionProxyPassword

public void setConnectionProxyPassword(String password)

Sets the password used when authenticating to the proxy.

Parameters:

password - password used when authenticating to the proxy; may be null

isHttpFollowRedirects

public boolean isHttpFollowRedirects()

Gets whether HTTP redirects will be followed.

Returns:

whether HTTP redirects will be followed

setHttpFollowRedirects

public void setHttpFollowRedirects(boolean followRedirects)

Gets whether HTTP redirects will be followed.

Parameters:

followRedirects - true if redirects are followed, false otherwise

getHttpContentCharSet

public String getHttpContentCharSet()

Gets the character set used with the HTTP entity (body).

Returns:

character set used with the HTTP entity (body)

setHttpContentCharSet

public void setHttpContentCharSet(String charSet)

Sets the character set used with the HTTP entity (body).

Parameters:

charSet - character set used with the HTTP entity (body)

buildClient

public HttpClient buildClient()

Constructs an HttpClient using the settings of this builder.

Returns:

the constructed client

buildConnectionManager

private ClientConnectionManager buildConnectionManager()

Builds the connection manager used by the HTTP client. A ThreadSafeClientConnManager is used with ThreadSafeClientConnManager.setDefaultMaxPerRoute(int) set to connectionsMaxPerRoute and ThreadSafeClientConnManager.setMaxTotal(int) set to connectionsMaxTotal.

Returns:

the connection manager used by the HTTP client

buildSchemeRegistry

private SchemeRegistry buildSchemeRegistry()

Creates the default scheme registry for connection. The constructed registry supports http with a default port of 80 and https with a default port of 443. If connectionDisregardSslCertificate is true, than the https port will accept any certificate presented by the responder.

Returns:

the default scheme registry.