org.eclipse.webdav.http.client
Class HttpClient

java.lang.Object
  org.eclipse.webdav.http.client.HttpClient

All Implemented Interfaces:

IStatusCodes

public class HttpClient
extends Object
implements IStatusCodes

An HTTP 1.0 or 1.1 client. Single instances of this client enable users to talk with multiple origin servers. Moreover, connections to origin servers are maintained for reuse.

Conveniences are provided for managing proxy servers, handling authentication, and setting up request headers.

Here is some sample code: HttpClient client = new HttpClient(); try { Request request = null; Response response = null; try { URL resourceUrl = new URL("http://hostname/index.html"); request = new Request("GET", resourceUrl, (Context) null); response = client.invoke(request); System.out.print(response); InputStream is = response.getInputStream(); int c; while ((c = is.read()) != -1) { System.out.print((char) c); } } catch (IOException e) { e.printStackTrace(); } finally { if (request != null) { try { request.close(); } catch (IOException e) { e.printStackTrace(); } } if (response != null) { try { response.close(); } catch (IOException e) { e.printStackTrace(); } } } } finally { client.close(); }

Note: This class/interface is part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.

Nested Class Summary

class

HttpClient.ConnectionsRecycler The ConnectionsRecycler manages a collection of persistent HttpConnections.

Field Summary

Fields inherited from interface org.eclipse.webdav.http.client.IStatusCodes

HTTP_ACCEPTED, HTTP_BAD_GATEWAY, HTTP_BAD_REQUEST, HTTP_CONFLICT, HTTP_CONTINUE, HTTP_CREATED, HTTP_EXPECTATION_FAILED, HTTP_FORBIDDEN, HTTP_GATEWAY_TIMEOUT, HTTP_GONE, HTTP_HTTP_VERSION_NOT_SUPPORTED, HTTP_INTERNAL_SERVER_ERROR, HTTP_LENGTH_REQUIRED, HTTP_METHOD_NOT_ALLOWED, HTTP_MOVED_PERMANENTLY, HTTP_MOVED_TEMPORARILY, HTTP_MULTIPLE_CHOICES, HTTP_NO_CONTENT, HTTP_NON_AUTHORITATIVE_INFORMATION, HTTP_NOT_ACCEPTABLE, HTTP_NOT_FOUND, HTTP_NOT_IMPLEMENTED, HTTP_NOT_MODIFIED, HTTP_OK, HTTP_PARTIAL_CONTENT, HTTP_PAYMENT_REQUIRED, HTTP_PRECONDITION_FAILED, HTTP_PROXY_AUTHENTICATION_REQUIRED, HTTP_REQUEST_TIMEOUT, HTTP_REQUEST_TOO_LONG, HTTP_REQUEST_URI_TOO_LONG, HTTP_REQUESTED_RANGE_NOT_SATISFIABLE, HTTP_RESET_CONTENT, HTTP_SEE_OTHER, HTTP_SERVICE_UNAVAILABLE, HTTP_SWITCHING_PROTOCOLS, HTTP_TEMPORARY_REDIRECT, HTTP_UNAUTHORIZED, HTTP_UNSUPPORTED_MEDIA_TYPE, HTTP_USE_PROXY

Constructor Summary

HttpClient()
Creates a new HttpClient.

Method Summary

void	addProxyServerException(String pattern) Adds the given proxy server exception pattern to this client.
void	close() Closes this client.
long	getConnectionTimeout()
IContext	getContext(URL originServerUrl) Returns the context for the origin server at the given URL.
IContext	getDefaultContext() Returns the default context.
URL	getDefaultProxyServerUrl() Returns the URL of the default proxy server which is used for all servers that do not have their proxy server set and do not match a proxy server exception.
double	getHttpVersion() Returns the version of HTTP this client uses for communication with servers.
int	getMaxRedirects() Returns the maximum number of URL location redirects.
int	getMaxRetries() Returns the maximum number of times a request is retried after an IOException occurs.
Enumeration	getOriginServerUrls() Returns an Enumeration over the origin server URLs known to this client.
Enumeration	getProxyServerExceptions() Returns an Enumeration over this client's proxy server exception patterns.
URL	getProxyServerUrl(URL originServerUrl) Returns the URL of the proxy server that the origin server at the given URL uses, or null if no proxy server is used.
int	getSoTimeout() Returns the socket read timeout (in milliseconds) for this client.
Response	invoke(Request request) Sends the given request to the server and returns the server's response.
void	removeProxyServerException(String pattern) Removes the given proxy server exception pattern from this client.
void	setAuthenticator(IAuthenticator authenticator) Sets the authenticator.
void	setConnectionTimeout(long connectionTimeout)
void	setContext(URL originServerUrl, IContext context) Set the context for the origin server at the given URL.
void	setDefaultContext(IContext context) Sets the default context which is used by all servers that do not already have a context set.
void	setDefaultProxyServerUrl(URL proxyServerUrl) Sets the URL of the default proxy server that is used by all servers that do not have their proxy server set and do not match a proxy server exception pattern.
void	setHttpVersion(double httpVersion) Sets the version of HTTP this client uses for communication with servers.
void	setMaxRedirects(int maxRedirects) Sets the maximum number of URL location redirects.
void	setMaxRetries(int maxRetries) Sets the maximum number of times a request is retried after an IOException occurs.
void	setProxyServerUrl(URL originServerUrl, URL proxyServerUrl) Sets the URL of the proxy server that this client uses to communicate with the origin server at the given URL.
void	setSocketFactory(ISocketFactory socketFactory) Sets the factory that this client uses to create sockets.
void	setSoTimeout(int timeout) Sets the socket read timeout (in milliseconds) for this client.

Methods inherited from class java.lang.Object

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

Constructor Detail

HttpClient

public HttpClient()

Creates a new HttpClient.

Method Detail

addProxyServerException

public void addProxyServerException(String pattern)

Adds the given proxy server exception pattern to this client. Origin servers whose hostname match the pattern do not communicate through the defualt proxy server. The pattern must contain zero or one stars (*). A star must appear at either the beginning or the end of the pattern. A star matches zero or more characters. The following are valid patterns:

• www.company.com:80
• *.company.com
• www.company.*

Parameters:

pattern - a proxy server exception pattern, for example: "*.company.com".

See Also:

getDefaultProxyServerUrl(), getProxyServerExceptions(), getProxyServerUrl(URL), removeProxyServerException(String), setDefaultProxyServerUrl(URL), setProxyServerUrl(URL, URL)

close

public void close()

Closes this client.

getConnectionTimeout

public long getConnectionTimeout()

getContext

public IContext getContext(URL originServerUrl)

Returns the context for the origin server at the given URL.

Parameters:

originServerUrl - the URL of an origin server

Returns:

the context for the origin server at the given URL

See Also:

getDefaultContext(), #setDefaultContext(Context), #setContext(URL, Context)

getDefaultContext

public IContext getDefaultContext()

Returns the default context. The default context is used for servers that do not have a context set. Initially the default context is null.

Returns:

the default context, or null

See Also:

getContext(URL), #setContext(URL, Context), #setDefaultContext(Context)

getDefaultProxyServerUrl

public URL getDefaultProxyServerUrl()

Returns the URL of the default proxy server which is used for all servers that do not have their proxy server set and do not match a proxy server exception. If the default proxy server URL is null, no default proxy server is used. Initially the default proxy server URL is null.

Returns:

the URL of the default proxy server, or null

See Also:

addProxyServerException(String), getProxyServerExceptions(), getProxyServerUrl(URL), removeProxyServerException(String), setDefaultProxyServerUrl(URL), setProxyServerUrl(URL, URL)

getHttpVersion

public double getHttpVersion()

Returns the version of HTTP this client uses for communication with servers. HTTP/1.1 is used by default.

Returns:

the version of HTTP this client uses for communication with servers

See Also:

setHttpVersion(double)

getMaxRedirects

public int getMaxRedirects()

Returns the maximum number of URL location redirects. The maximum is 4 by default.

Returns:

the maximum number of URL location redirects

getMaxRetries

public int getMaxRetries()

Returns the maximum number of times a request is retried after an IOException occurs. The maximum is 1 by default.

Returns:

the maximum number of retries

See Also:

setMaxRetries(int)

getOriginServerUrls

public Enumeration getOriginServerUrls()

Returns an Enumeration over the origin server URLs known to this client. The known origin server URLs are gleaned from this client's mapped contexts and mapped proxy server URLs.

Returns:

an Enumeration over the origin server URLs known to this client

See Also:

getContext(URL), #setContext(URL, Context), getProxyServerUrl(URL), setProxyServerUrl(URL, URL)

getProxyServerExceptions

public Enumeration getProxyServerExceptions()

Returns an Enumeration over this client's proxy server exception patterns.

Returns:

an Enumeration over this client's proxy server exception patterns

See Also:

addProxyServerException(String), getDefaultProxyServerUrl(), getProxyServerUrl(URL), removeProxyServerException(String), setDefaultProxyServerUrl(URL), setProxyServerUrl(URL, URL)

getProxyServerUrl

public URL getProxyServerUrl(URL originServerUrl)

Returns the URL of the proxy server that the origin server at the given URL uses, or null if no proxy server is used.

Parameters:

originServerUrl - the URL of an origin server

Returns:

the URL of a proxy server, or null

See Also:

addProxyServerException(String), getDefaultProxyServerUrl(), getProxyServerExceptions(), removeProxyServerException(String), setDefaultProxyServerUrl(URL), setProxyServerUrl(URL, URL)

getSoTimeout

public int getSoTimeout()

Returns the socket read timeout (in milliseconds) for this client. A value of zero indicates that a socket read operation will block indefinitely waiting for data. The value is zero by default.

Returns:

the socket read timeout (in milliseconds) for this client

See Also:

setSoTimeout(int)

invoke

public Response invoke(Request request)
                throws IOException

Sends the given request to the server and returns the server's response.

Parameters:

request - the request to send to the server

Returns:

the server's response

Throws:

IOException - if an I/O error occurs. Reasons include:

• The client is closed.
• The client could not connect to the server
• An I/O error occurs while communicating with the server

removeProxyServerException

public void removeProxyServerException(String pattern)

Removes the given proxy server exception pattern from this client.

Parameters:

pattern - a proxy server exception pattern

See Also:

addProxyServerException(String), getDefaultProxyServerUrl(), getProxyServerExceptions(), getProxyServerUrl(URL), setDefaultProxyServerUrl(URL), setProxyServerUrl(URL, URL)

setAuthenticator

public void setAuthenticator(IAuthenticator authenticator)

Sets the authenticator. Authenticators store authentication information and are required to access protected resources. If the authenticator is null protected resources cannot be accessed. The authenticator is null by default.

Parameters:

authenticator - the authenticator, or null

setConnectionTimeout

public void setConnectionTimeout(long connectionTimeout)

setContext

public void setContext(URL originServerUrl,
                       IContext context)

Set the context for the origin server at the given URL. If the given context is null, the context for the specified origin server is removed.

Parameters:

originServerUrl - the URL of an origin server

context - the context for the specified origin server

See Also:

getContext(URL), getDefaultContext(), #setDefaultContext(Context)

setDefaultContext

public void setDefaultContext(IContext context)

Sets the default context which is used by all servers that do not already have a context set.

Parameters:

context - the default context

See Also:

getContext(URL), getDefaultContext(), #setContext(URL, Context)

setDefaultProxyServerUrl

public void setDefaultProxyServerUrl(URL proxyServerUrl)

Sets the URL of the default proxy server that is used by all servers that do not have their proxy server set and do not match a proxy server exception pattern. If the given proxy server URL is null, no default proxy server is used.

Parameters:

proxyServerUrl - the URL of the default proxy server

See Also:

addProxyServerException(String), getDefaultProxyServerUrl(), getProxyServerExceptions(), getProxyServerUrl(URL), removeProxyServerException(String), setProxyServerUrl(URL, URL)

setHttpVersion

public void setHttpVersion(double httpVersion)

Sets the version of HTTP this client uses for communication with servers. HTTP/1.1 is used by default.

Parameters:

httpVersion - the version of HTTP this client uses for communication with servers

See Also:

getHttpVersion()

setMaxRedirects

public void setMaxRedirects(int maxRedirects)

Sets the maximum number of URL location redirects. The maximum is 4 by default.

Parameters:

maxRedirects - the maximum number of URL redirects

setMaxRetries

public void setMaxRetries(int maxRetries)

Sets the maximum number of times a request is retried after an IOException occurs. The maximum is 1 by default.

Parameters:

maxRetries - the maximum number of times a request is retried after an IOException occurs

See Also:

getMaxRetries()

setProxyServerUrl

public void setProxyServerUrl(URL originServerUrl,
                              URL proxyServerUrl)

Sets the URL of the proxy server that this client uses to communicate with the origin server at the given URL. If the proxy server URL is null, the default proxy server is used if the specified origin server does not match a proxy server exception pattern.

Parameters:

originServerUrl - the URL of on origin server

proxyServerUrl - the URL of a proxy server, or null

See Also:

addProxyServerException(String), getDefaultProxyServerUrl(), getProxyServerExceptions(), getProxyServerUrl(URL), removeProxyServerException(String), setDefaultProxyServerUrl(URL)

setSocketFactory

public void setSocketFactory(ISocketFactory socketFactory)

Sets the factory that this client uses to create sockets.

Parameters:

socketFactory - the factory that this client uses to create sockets

setSoTimeout

public void setSoTimeout(int timeout)

Sets the socket read timeout (in milliseconds) for this client. A value of zero indicates that a socket read operation will block indefinitely waiting for data. The value is zero by default.

Parameters:

timeout - the socket read timeout

See Also:

getSoTimeout()