org.apache.commons.httpclient
Class HttpClient

java.lang.Object
  |
  +--org.apache.commons.httpclient.HttpClient

public class HttpClient

extends java.lang.Object

An HTTP "user-agent", containing an HTTP state and one or more HTTP connections, to which HTTP methods can be applied.

Version:

$Revision: 1.76.2.3 $ $Date: 2004/02/04 02:14:32 $

Author:

Remy Maucherat, Rodney Waldhoff, Sean C. Sullivan, dIon Gillard, Ortwin Gl?ck, Michael Becke, Mike Bowler, Sam Maloney, Laura Werner, Oleg Kalnichevski

Constructor Summary

HttpClient()
Creates an instance of HttpClient using a simple HTTP connection manager.

HttpClient(HttpConnectionManager httpConnectionManager)
Creates an instance of HttpClient with a user specified connection manager.

Method Summary

void	endSession() Deprecated. this method has no effect. HttpMethod.releaseConnection() should be used to release resources after a HttpMethod has been executed.
int	executeMethod(HostConfiguration hostConfiguration, HttpMethod method) Executes the given HTTP method using custom host configuration.
int	executeMethod(HostConfiguration hostConfiguration, HttpMethod method, HttpState state) Executes the given HTTP method using the given custom host configuration with the given custom HTTP state.
int	executeMethod(HttpMethod method) Executes the given HTTP method.
java.lang.String	getHost() Returns the host that the client is accessing.
HostConfiguration	getHostConfiguration() Returns the host configuration associated with the HttpClient.
HttpConnectionManager	getHttpConnectionManager() Returns the HTTP connection manager associated with the HttpClient.
int	getPort() Returns the port that the client is accessing.
HttpState	getState() Returns HTTP state associated with the HttpClient.
boolean	isStrictMode() Returns the value of the strict mode flag.
void	setConnectionTimeout(int newTimeoutInMilliseconds) Sets the timeout until a connection is etablished.
void	setHostConfiguration(HostConfiguration hostConfiguration) Assigns the host configuration to use with the HttpClient.
void	setHttpConnectionFactoryTimeout(long timeout) Sets the timeout in milliseconds used when retrieving an HTTP connection from the HTTP connection manager.
void	setHttpConnectionManager(HttpConnectionManager httpConnectionManager) Assigns the HTTP connection manager to use with the HttpClient.
void	setState(HttpState state) Assigns HTTP state for the HttpClient.
void	setStrictMode(boolean strictMode) Defines how strictly the method follows the HTTP protocol specification (see RFC 2616 and other relevant RFCs).
void	setTimeout(int newTimeoutInMilliseconds) Sets the socket timeout (SO_TIMEOUT) in milliseconds which is the timeout for waiting for data.
void	startSession(java.lang.String host, int port) Deprecated. use HostConfiguration
void	startSession(java.lang.String host, int port, boolean https) Deprecated. use HostConfiguration
void	startSession(java.lang.String host, int port, Credentials creds) Deprecated. use HostConfiguration and HttpState
void	startSession(java.lang.String host, int port, Credentials creds, boolean https) Deprecated. use HostConfiguration and HttpState
void	startSession(java.lang.String host, int port, java.lang.String proxyhost, int proxyport) Deprecated. use HostConfiguration
void	startSession(java.lang.String host, int port, java.lang.String proxyhost, int proxyport, boolean secure) Deprecated. use HostConfiguration
void	startSession(URI uri) Deprecated. use HostConfiguration
void	startSession(java.net.URL url) Deprecated. use HostConfiguration
void	startSession(java.net.URL url, Credentials creds) Deprecated. use HostConfiguration and HttpState

Methods inherited from class java.lang.Object

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

Constructor Detail

HttpClient

public HttpClient()

Creates an instance of HttpClient using a simple HTTP connection manager.

See Also:

SimpleHttpConnectionManager

HttpClient

public HttpClient(HttpConnectionManager httpConnectionManager)

Creates an instance of HttpClient with a user specified connection manager.

Parameters:

httpConnectionManager - The connection manager to use.

Since:

2.0

Method Detail

getState

public HttpState getState()

Returns HTTP state associated with the HttpClient.

Returns:

the shared client state

See Also:

setState(HttpState)

setState

public void setState(HttpState state)

Assigns HTTP state for the HttpClient.

Parameters:

state - the new HTTP state for the client

See Also:

getState()

setStrictMode

public void setStrictMode(boolean strictMode)

Defines how strictly the method follows the HTTP protocol specification (see RFC 2616 and other relevant RFCs). In the strict mode the method precisely implements the requirements of the specification, whereas in non-strict mode it attempts to mimic the exact behaviour of commonly used HTTP agents, which many HTTP servers expect.

Parameters:

strictMode - true for strict mode, false otherwise

See Also:

isStrictMode()

isStrictMode

public boolean isStrictMode()

Returns the value of the strict mode flag.

Returns:

true if strict mode is enabled, false otherwise

See Also:

setStrictMode(boolean)

setTimeout

public void setTimeout(int newTimeoutInMilliseconds)

Sets the socket timeout (SO_TIMEOUT) in milliseconds which is the timeout for waiting for data. A timeout value of zero is interpreted as an infinite timeout.

Parameters:

newTimeoutInMilliseconds - Timeout in milliseconds

setHttpConnectionFactoryTimeout

public void setHttpConnectionFactoryTimeout(long timeout)

Sets the timeout in milliseconds used when retrieving an HTTP connection from the HTTP connection manager.

Parameters:

timeout - the timeout in milliseconds

See Also:

HttpConnectionManager.getConnection(HostConfiguration, long)

setConnectionTimeout

public void setConnectionTimeout(int newTimeoutInMilliseconds)

Sets the timeout until a connection is etablished. A timeout value of zero means the timeout is not used. The default value is zero.

Parameters:

newTimeoutInMilliseconds - Timeout in milliseconds.

See Also:

HttpConnection.setConnectionTimeout(int)

startSession

public void startSession(java.lang.String host,
                         int port)

Deprecated. use HostConfiguration

Sets the host, port and default protocol (http) to be used when executing a method.

Parameters:

host - the host to connect to

port - the port to connect to

See Also:

getHostConfiguration()

startSession

public void startSession(java.lang.String host,
                         int port,
                         boolean https)

Deprecated. use HostConfiguration

Sets the host, port and protocol to be used when executing a method.

Parameters:

host - the host to connect to

port - the port to connect to

https - when true, create an HTTPS session

See Also:

getHostConfiguration()

startSession

public void startSession(java.lang.String host,
                         int port,
                         Credentials creds)

Deprecated. use HostConfiguration and HttpState

Sets the host, port, default protocol (http) and credentials to be used when executing a method.

Parameters:

host - the host to connect to

port - the port to connect to

creds - the default credentials to use

See Also:

getHostConfiguration(), getState(), startSession(String, int, Credentials, boolean)

startSession

public void startSession(java.lang.String host,
                         int port,
                         Credentials creds,
                         boolean https)

Deprecated. use HostConfiguration and HttpState

Sets the host, port, protocol and credentials to be used when executing a method.

Parameters:

host - the host to connect to

port - the port to connect to

creds - the default credentials to use

https - when true, create an HTTPS session

See Also:

getHostConfiguration(), getState()

startSession

public void startSession(URI uri)
                  throws URIException,
                         java.lang.IllegalStateException

Deprecated. use HostConfiguration

Sets the host, port, protocol and credentials to be used when executing a method using the server specified by the scheme, userinfo, host and port of the given uri.

Note that the path component is not utilized.

Parameters:

uri - an HttpURL or HttpsURL instance; the URI from which the scheme, userinfo, host and port of the session are determined

Throws:

java.lang.IllegalStateException - not enough information to process

URIException - If the URI is bad.

See Also:

getHostConfiguration()

startSession

public void startSession(java.net.URL url)
                  throws java.lang.IllegalArgumentException

Deprecated. use HostConfiguration

Sets the host, port and protocol to be used when executing a method.

Note that everything but the protocol, host and port of the given url is ignored.

Parameters:

url - the URL from which the protocol, host, and port of the session are determined

Throws:

java.lang.IllegalArgumentException - if the protocol is not http or https

See Also:

getHostConfiguration()

startSession

public void startSession(java.net.URL url,
                         Credentials creds)
                  throws java.lang.IllegalArgumentException

Deprecated. use HostConfiguration and HttpState

Sets the host, port, protocol and credentials to be used when executing a method.

Note that everything but the protocol, host and port of the given url is ignored.

Parameters:

url - the URL from which the protocol, host, and port of the session are determined

creds - the default credentials to use

Throws:

java.lang.IllegalArgumentException - if the protocol is not http or https

See Also:

getHostConfiguration(), getState()

startSession

public void startSession(java.lang.String host,
                         int port,
                         java.lang.String proxyhost,
                         int proxyport)

Deprecated. use HostConfiguration

Sets the host, port, protocol(http) and proxy to be used when executing a method.

Parameters:

host - the host to connect to

port - the port to connect to

proxyhost - the proxy host to connect via

proxyport - the proxy port to connect via

See Also:

getHostConfiguration()

startSession

public void startSession(java.lang.String host,
                         int port,
                         java.lang.String proxyhost,
                         int proxyport,
                         boolean secure)

Deprecated. use HostConfiguration

Sets the host, port, protocol and proxy to be used when executing a method.

Parameters:

host - the host to connect to

port - the port to connect to

proxyhost - the proxy host to connect via

proxyport - the proxy port to connect via

secure - whether or not to connect using HTTPS

See Also:

getHostConfiguration()

executeMethod

public int executeMethod(HttpMethod method)
                  throws java.io.IOException,
                         HttpException

Executes the given HTTP method.

Parameters:

method - the HTTP method to execute.

Returns:

the method's response code

Throws:

java.io.IOException - If an I/O (transport) error occurs. Some transport exceptions can be recovered from.

HttpException - If a protocol exception occurs. Usually protocol exceptions cannot be recovered from.

executeMethod

public int executeMethod(HostConfiguration hostConfiguration,
                         HttpMethod method)
                  throws java.io.IOException,
                         HttpException

Executes the given HTTP method using custom host configuration.

Parameters:

hostConfiguration - The host configuration to use.

method - the HTTP method to execute.

Returns:

the method's response code

Throws:

java.io.IOException - If an I/O (transport) error occurs. Some transport exceptions can be recovered from.

HttpException - If a protocol exception occurs. Usually protocol exceptions cannot be recovered from.

Since:

2.0

executeMethod

public int executeMethod(HostConfiguration hostConfiguration,
                         HttpMethod method,
                         HttpState state)
                  throws java.io.IOException,
                         HttpException

Executes the given HTTP method using the given custom host configuration with the given custom HTTP state.

Parameters:

hostConfiguration - The host configuration to use.

method - the HTTP method to execute.

state - the HTTP state to use when executing the method. If null, the state returned by getState() will be used instead.

Returns:

the method's response code

Throws:

java.io.IOException - If an I/O (transport) error occurs. Some transport exceptions can be recovered from.

HttpException - If a protocol exception occurs. Usually protocol exceptions cannot be recovered from.

Since:

2.0

endSession

public void endSession()
                throws java.io.IOException

Deprecated. this method has no effect. HttpMethod.releaseConnection() should be used to release resources after a HttpMethod has been executed.

See Also:

HttpMethod.releaseConnection()

getHost

public java.lang.String getHost()

Returns the host that the client is accessing.

Returns:

The host that the client is accessing, or null if the session has not been started via startSession.

getPort

public int getPort()

Returns the port that the client is accessing.

Returns:

The port that the client is accessing, or -1 if the session has not been started via startSession().

getHostConfiguration

public HostConfiguration getHostConfiguration()

Returns the host configuration associated with the HttpClient.

Returns:

host configuration

Since:

2.0

setHostConfiguration

public void setHostConfiguration(HostConfiguration hostConfiguration)

Assigns the host configuration to use with the HttpClient.

Parameters:

hostConfiguration - The host configuration to set

Since:

2.0

getHttpConnectionManager

public HttpConnectionManager getHttpConnectionManager()

Returns the HTTP connection manager associated with the HttpClient.

Returns:

HTTP connection manager

Since:

2.0

setHttpConnectionManager

public void setHttpConnectionManager(HttpConnectionManager httpConnectionManager)

Assigns the HTTP connection manager to use with the HttpClient.

Parameters:

httpConnectionManager - The HTTP connection manager to set

Since:

2.0