org.apache.commons.httpclient
Class HttpConnection

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

public class HttpConnection

extends Object

An abstraction of an HTTP InputStream and OutputStream pair, together with the relevant attributes.

The following options are set on the socket before getting the input/output streams in the open() method:

Socket Method	Sockets Option	Configuration
Socket.setTcpNoDelay(boolean)	SO_NODELAY	None
Socket.setSoTimeout(int)	SO_TIMEOUT	setConnectionTimeout(int)

Version:

$Revision: 1.67.2.13 $ $Date: 2004/09/06 17:41:45 $

Author:

Rod Waldhoff, Sean C. Sullivan, Ortwin Gl??ck, Jeff Dever, Mike Bowler, Oleg Kalnichevski, Michael Becke, Eric E Johnson, Laura Werner

Inner Class Summary

static class

HttpConnection.ConnectionTimeoutException Signals that a timeout occured while opening the socket.

Field Summary

protected boolean

isOpen Whether or not the connection is connected.

Constructor Summary

HttpConnection(HostConfiguration hostConfiguration)
Creates a new HTTP connection for the given host configuration.

HttpConnection(String host, int port)
Creates a new HTTP connection for the given host and port.

HttpConnection(String host, int port, boolean secure)
Deprecated. use HttpConnection(String, int, Protocol)

HttpConnection(String host, int port, Protocol protocol)
Creates a new HTTP connection for the given host and port using the given protocol.

HttpConnection(String proxyHost, int proxyPort, String host, int port)
Creates a new HTTP connection for the given host and port via the given proxy host and port using the default protocol.

HttpConnection(String proxyHost, int proxyPort, String host, int port, boolean secure)
Deprecated. use HttpConnection(String, int, String, int, Protocol)

HttpConnection(String proxyHost, int proxyPort, String host, String virtualHost, int port, Protocol protocol)
Creates a new HTTP connection for the given host with the virtual alias and port via the given proxy host and port using the given protocol.

HttpConnection(String host, String virtualHost, int port, Protocol protocol)
Creates a new HTTP connection for the given host with the virtual alias and port using given protocol.

Method Summary

protected void	assertNotOpen() Throws an IllegalStateException if the connection is already open.
protected void	assertOpen() Throws an IllegalStateException if the connection is not open.
void	close() Closes the socket and streams.
protected void	closeSocketAndStreams() Closes everything out.
void	flushRequestOutputStream() Flushes the output request stream.
String	getHost() Returns the host.
HttpConnectionManager	getHttpConnectionManager() Returns the httpConnectionManager.
InputStream	getLastResponseInputStream() Returns the stream used to read the last response's body.
InetAddress	getLocalAddress() Return the local address used when creating the connection.
int	getPort() Returns the port of the host.
Protocol	getProtocol() Returns the protocol used to establish the connection.
String	getProxyHost() Returns the proxy host.
int	getProxyPort() Returns the port of the proxy host.
OutputStream	getRequestOutputStream() Returns an OutputStream suitable for writing the request.
OutputStream	getRequestOutputStream(boolean useChunking) Deprecated. Use new ChunkedOutputStream(httpConnecion.getRequestOutputStream());
InputStream	getResponseInputStream() Return a InputStream suitable for reading the response.
InputStream	getResponseInputStream(HttpMethod method) Deprecated. Use getResponseInputStream() instead.
int	getSendBufferSize() Gets the socket's sendBufferSize.
int	getSoTimeout() Returns the Socket's timeout, via Socket.getSoTimeout(), if the connection is already open.
String	getVirtualHost() Returns the target virtual host.
boolean	isOpen() Returns true if the connection is open, false otherwise.
boolean	isProxied() Returns true if the connection is established via a proxy, false otherwise.
boolean	isResponseAvailable() Tests if input data avaialble.
boolean	isResponseAvailable(int timeout) Tests if input data becomes available within the given period time in milliseconds.
boolean	isSecure() Returns true if the connection is established over a secure protocol.
protected boolean	isStale() Determines whether this connection is "stale", which is to say that either it is no longer open, or an attempt to read the connection would fail.
boolean	isStaleCheckingEnabled() Tests if stale checking is enabled.
boolean	isTransparent() Indicates if the connection is completely transparent from end to end.
void	open() Establishes a connection to the specified host and port (via a proxy if specified).
void	print(String data) Writes the specified String (as bytes) to the output stream.
void	printLine() Writes "\r\n".getBytes() to the output stream.
void	printLine(String data) Writes the specified String (as bytes), followed by "\r\n".getBytes() to the output stream.
String	readLine() Reads up to "\n" from the (unchunked) input stream.
void	releaseConnection() Release the connection.
void	setConnectionTimeout(int timeout) Sets the connection timeout.
void	setHost(String host) Sets the host to connect to.
void	setHttpConnectionManager(HttpConnectionManager httpConnectionManager) Sets the httpConnectionManager.
void	setLastResponseInputStream(InputStream inStream) Set the state to keep track of the last response for the last request.
void	setLocalAddress(InetAddress localAddress) Set the local address used when creating the connection.
void	setPort(int port) Sets the port to connect to.
void	setProtocol(Protocol protocol) Sets the protocol used to establish the connection
void	setProxyHost(String host) Sets the host to proxy through.
void	setProxyPort(int port) Sets the port of the host to proxy through.
void	setSecure(boolean secure) Deprecated. use setProtocol(Protocol)
void	setSendBufferSize(int sendBufferSize) Sets the socket's sendBufferSize.
void	setSoTimeout(int timeout) Sets the Socket's timeout, via Socket.setSoTimeout(int).
void	setStaleCheckingEnabled(boolean staleCheckEnabled) Sets whether or not isStale() will be called when testing if this connection is open.
void	setVirtualHost(String host) Sets the virtual host to target.
void	shutdownOutput() Attempts to shutdown the Socket's output, via Socket.shutdownOutput() when running on JVM 1.3 or higher.
void	tunnelCreated() Instructs the proxy to establish a secure tunnel to the host.
void	write(byte[] data) Writes the specified bytes to the output stream.
void	write(byte[] data, int offset, int length) Writes length bytes in data starting at offset to the output stream.
void	writeLine() Writes "\r\n".getBytes() to the output stream.
void	writeLine(byte[] data) Writes the specified bytes, followed by "\r\n".getBytes() to the output stream.

Methods inherited from class java.lang.Object

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

Field Detail

isOpen

protected boolean isOpen

Whether or not the connection is connected.

Constructor Detail

HttpConnection

public HttpConnection(String host,
                      int port)

Creates a new HTTP connection for the given host and port.

Parameters:

host - the host to connect to

port - the port to connect to

HttpConnection

public HttpConnection(String host,
                      int port,
                      boolean secure)

Deprecated. use HttpConnection(String, int, Protocol)

Creates a new HTTP connection for the given host and port. If secure attribute is set, use SSL to establish the connection.

Parameters:

host - the host to connect to

port - the port to connect to

secure - when true, connect via HTTPS (SSL)

See Also:

HttpConnection(String,int,Protocol)

HttpConnection

public HttpConnection(String host,
                      int port,
                      Protocol protocol)

Creates a new HTTP connection for the given host and port using the given protocol.

Parameters:

host - the host to connect to

port - the port to connect to

protocol - the protocol to use

HttpConnection

public HttpConnection(String host,
                      String virtualHost,
                      int port,
                      Protocol protocol)

Creates a new HTTP connection for the given host with the virtual alias and port using given protocol.

Parameters:

host - the host to connect to

virtualHost - the virtual host requests will be sent to

port - the port to connect to

protocol - the protocol to use

HttpConnection

public HttpConnection(String proxyHost,
                      int proxyPort,
                      String host,
                      int port)

Creates a new HTTP connection for the given host and port via the given proxy host and port using the default protocol.

Parameters:

proxyHost - the host to proxy via

proxyPort - the port to proxy via

host - the host to connect to

port - the port to connect to

HttpConnection

public HttpConnection(String proxyHost,
                      int proxyPort,
                      String host,
                      int port,
                      boolean secure)

Deprecated. use HttpConnection(String, int, String, int, Protocol)

Creates a new HTTP connection for the given host and port via the given proxy host and port. If secure attribute is set, use SSL to establish the connection.

Parameters:

proxyHost - the host I should proxy via

proxyPort - the port I should proxy via

host - the host to connect to. Parameter value must be non-null.

port - the port to connect to

secure - when true, connect via HTTPS (SSL)

See Also:

HttpConnection(String, int, String, String, int, Protocol)

HttpConnection

public HttpConnection(HostConfiguration hostConfiguration)

Creates a new HTTP connection for the given host configuration.

Parameters:

hostConfiguration - the host/proxy/protocol to use

HttpConnection

public HttpConnection(String proxyHost,
                      int proxyPort,
                      String host,
                      String virtualHost,
                      int port,
                      Protocol protocol)

Creates a new HTTP connection for the given host with the virtual alias and port via the given proxy host and port using the given protocol.

Parameters:

proxyHost - the host to proxy via

proxyPort - the port to proxy via

host - the host to connect to. Parameter value must be non-null.

virtualHost - the virtual host requests will be sent to

port - the port to connect to

protocol - The protocol to use. Parameter value must be non-null.

Method Detail

getHost

public String getHost()

Returns the host.

Returns:

the host.

setHost

public void setHost(String host)
             throws IllegalStateException

Sets the host to connect to.

Parameters:

host - the host to connect to. Parameter value must be non-null.

Throws:

IllegalStateException - if the connection is already open

getVirtualHost

public String getVirtualHost()

Returns the target virtual host.

Returns:

the virtual host.

setVirtualHost

public void setVirtualHost(String host)
                    throws IllegalStateException

Sets the virtual host to target.

Parameters:

host - the virtual host name that should be used instead of physical host name when sending HTTP requests. Virtual host name can be set to null if virtual host name is not to be used

Throws:

IllegalStateException - if the connection is already open

getPort

public int getPort()

Returns the port of the host. If the port is -1 (or less than 0) the default port for the current protocol is returned.

Returns:

the port.

setPort

public void setPort(int port)
             throws IllegalStateException

Sets the port to connect to.

Parameters:

port - the port to connect to

Throws:

IllegalStateException - if the connection is already open

getProxyHost

public String getProxyHost()

Returns the proxy host.

Returns:

the proxy host.

setProxyHost

public void setProxyHost(String host)
                  throws IllegalStateException

Sets the host to proxy through.

Parameters:

host - the host to proxy through.

Throws:

IllegalStateException - if the connection is already open

getProxyPort

public int getProxyPort()

Returns the port of the proxy host.

Returns:

the proxy port.

setProxyPort

public void setProxyPort(int port)
                  throws IllegalStateException

Sets the port of the host to proxy through.

Parameters:

port - the port of the host to proxy through.

Throws:

IllegalStateException - if the connection is already open

isSecure

public boolean isSecure()

Returns true if the connection is established over a secure protocol.

Returns:

true if connected over a secure protocol.

getProtocol

public Protocol getProtocol()

Returns the protocol used to establish the connection.

Returns:

The protocol

setSecure

public void setSecure(boolean secure)
               throws IllegalStateException

Deprecated. use setProtocol(Protocol)

Defines whether the connection should be established over a secure protocol.

Parameters:

secure - whether or not to connect over a secure protocol.

Throws:

IllegalStateException - if the connection is already open

See Also:

setProtocol(Protocol)

setProtocol

public void setProtocol(Protocol protocol)

Sets the protocol used to establish the connection

Parameters:

protocol - The protocol to use.

Throws:

IllegalStateException - if the connection is already open

getLocalAddress

public InetAddress getLocalAddress()

Return the local address used when creating the connection. If null, the default address is used.

Returns:

InetAddress the local address to be used when creating Sockets

setLocalAddress

public void setLocalAddress(InetAddress localAddress)

Set the local address used when creating the connection. If unset or null, the default address is used.

Parameters:

localAddress - the local address to use

isOpen

public boolean isOpen()

Returns true if the connection is open, false otherwise.

Returns:

true if the connection is open

isStaleCheckingEnabled

public boolean isStaleCheckingEnabled()

Tests if stale checking is enabled.

Returns:

true if enabled

See Also:

isStale()

setStaleCheckingEnabled

public void setStaleCheckingEnabled(boolean staleCheckEnabled)

Sets whether or not isStale() will be called when testing if this connection is open.

Setting this flag to false will increase performance when reusing connections, but it will also make them less reliable. Stale checking ensures that connections are viable before they are used. When set to false some method executions will result in IOExceptions and they will have to be retried.

Parameters:

staleCheckEnabled - true to enable isStale()

See Also:

isStale(), isOpen()

isStale

protected boolean isStale()

Determines whether this connection is "stale", which is to say that either it is no longer open, or an attempt to read the connection would fail.

Unfortunately, due to the limitations of the JREs prior to 1.4, it is not possible to test a connection to see if both the read and write channels are open - except by reading and writing. This leads to a difficulty when some connections leave the "write" channel open, but close the read channel and ignore the request. This function attempts to ameliorate that problem by doing a test read, assuming that the caller will be doing a write followed by a read, rather than the other way around.

To avoid side-effects, the underlying connection is wrapped by a PushbackInputStream, so although data might be read, what is visible to clients of the connection will not change with this call.

Returns:

true if the connection is already closed, or a read would fail.

isProxied

public boolean isProxied()

Returns true if the connection is established via a proxy, false otherwise.

Returns:

true if a proxy is used to establish the connection, false otherwise.

setLastResponseInputStream

public void setLastResponseInputStream(InputStream inStream)

Set the state to keep track of the last response for the last request.

The connection managers use this to ensure that previous requests are properly closed before a new request is attempted. That way, a GET request need not be read in its entirety before a new request is issued. Instead, this stream can be closed as appropriate.

Parameters:

inStream - The stream associated with an HttpMethod.

getLastResponseInputStream

public InputStream getLastResponseInputStream()

Returns the stream used to read the last response's body.

Clients will generally not need to call this function unless using HttpConnection directly, instead of calling HttpClient.executeMethod(org.apache.commons.httpclient.HttpMethod). For those clients, call this function, and if it returns a non-null stream, close the stream before attempting to execute a method. Note that calling "close" on the stream returned by this function may close the connection if the previous response contained a "Connection: close" header.

Returns:

An InputStream corresponding to the body of the last response.

setSoTimeout

public void setSoTimeout(int timeout)
                  throws SocketException,
                         IllegalStateException

Sets the Socket's timeout, via Socket.setSoTimeout(int). If the connection is already open, the SO_TIMEOUT is changed. If no connection is open, then subsequent connections will use the timeout value.

Note: This is not a connection timeout but a timeout on network traffic!

Parameters:

timeout - the timeout value

Throws:

SocketException - - if there is an error in the underlying protocol, such as a TCP error.

getSoTimeout

public int getSoTimeout()
                 throws SocketException

Returns the Socket's timeout, via Socket.getSoTimeout(), if the connection is already open. If no connection is open, return the value subsequent connection will use.

Note: This is not a connection timeout but a timeout on network traffic!

Returns:

the timeout value

setConnectionTimeout

public void setConnectionTimeout(int timeout)

Sets the connection timeout. This is the maximum time that may be spent until a connection is established. The connection will fail after this amount of time.

Parameters:

timeout - The timeout in milliseconds. 0 means timeout is not used.

open

public void open()
          throws IOException

Establishes a connection to the specified host and port (via a proxy if specified). The underlying socket is created from the ProtocolSocketFactory.

Throws:

IOException - if an attempt to establish the connection results in an I/O error.

tunnelCreated

public void tunnelCreated()
                   throws IllegalStateException,
                          IOException

Instructs the proxy to establish a secure tunnel to the host. The socket will be switched to the secure socket. Subsequent communication is done via the secure socket. The method can only be called once on a proxied secure connection.

Throws:

IllegalStateException - if connection is not secure and proxied or if the socket is already secure.

IOException - if an attempt to establish the secure tunnel results in an I/O error.

isTransparent

public boolean isTransparent()

Indicates if the connection is completely transparent from end to end.

Returns:

true if conncetion is not proxied or tunneled through a transparent proxy; false otherwise.

flushRequestOutputStream

public void flushRequestOutputStream()
                              throws IOException

Flushes the output request stream. This method should be called to ensure that data written to the request OutputStream is sent to the server.

Throws:

IOException - if an I/O problem occurs

getRequestOutputStream

public OutputStream getRequestOutputStream()
                                    throws IOException,
                                           IllegalStateException

Returns an OutputStream suitable for writing the request.

Returns:

a stream to write the request to

Throws:

IllegalStateException - if the connection is not open

IOException - if an I/O problem occurs

getRequestOutputStream

public OutputStream getRequestOutputStream(boolean useChunking)
                                    throws IOException,
                                           IllegalStateException

Deprecated. Use new ChunkedOutputStream(httpConnecion.getRequestOutputStream());

Returns an OutputStream suitable for writing the request.

Parameters:

useChunking - when true the chunked transfer-encoding will be used

Returns:

a stream to write the request to

Throws:

IllegalStateException - if the connection is not open

IOException - if an I/O problem occurs

getResponseInputStream

public InputStream getResponseInputStream(HttpMethod method)
                                   throws IOException,
                                          IllegalStateException

Deprecated. Use getResponseInputStream() instead.

Return a InputStream suitable for reading the response.

If the given HttpMethod contains a Transfer-Encoding: chunked header, the returned stream will be configured to read chunked bytes.

Parameters:

method - This argument is ignored.

Returns:

a stream to read the response from

Throws:

IllegalStateException - if the connection is not open

IOException - if an I/O problem occurs

getResponseInputStream

public InputStream getResponseInputStream()
                                   throws IOException,
                                          IllegalStateException

Return a InputStream suitable for reading the response.

Returns:

InputStream The response input stream.

Throws:

IOException - If an IO problem occurs

IllegalStateException - If the connection isn't open.

isResponseAvailable

public boolean isResponseAvailable()
                            throws IOException

Tests if input data avaialble. This method returns immediately and does not perform any read operations on the input socket

Returns:

boolean true if input data is available, false otherwise.

Throws:

IOException - If an IO problem occurs

IllegalStateException - If the connection isn't open.

isResponseAvailable

public boolean isResponseAvailable(int timeout)
                            throws IOException

Tests if input data becomes available within the given period time in milliseconds.

Parameters:

timeout - The number milliseconds to wait for input data to become available

Returns:

boolean true if input data is availble, false otherwise.

Throws:

IOException - If an IO problem occurs

IllegalStateException - If the connection isn't open.

write

public void write(byte[] data)
           throws IOException,
                  IllegalStateException,
                  HttpRecoverableException

Writes the specified bytes to the output stream.

Parameters:

data - the data to be written

Throws:

HttpRecoverableException - if a SocketException occurs

IllegalStateException - if not connected

IOException - if an I/O problem occurs

See Also:

write(byte[],int,int)

write

public void write(byte[] data,
                  int offset,
                  int length)
           throws IOException,
                  IllegalStateException,
                  HttpRecoverableException

Writes length bytes in data starting at offset to the output stream. The general contract for write(b, off, len) is that some of the bytes in the array b are written to the output stream in order; element b[off] is the first byte written and b[off+len-1] is the last byte written by this operation.

Parameters:

data - array containing the data to be written.

offset - the start offset in the data.

length - the number of bytes to write.

Throws:

HttpRecoverableException - if a SocketException occurs

IllegalStateException - if not connected

IOException - if an I/O problem occurs

writeLine

public void writeLine(byte[] data)
               throws IOException,
                      IllegalStateException,
                      HttpRecoverableException

Writes the specified bytes, followed by "\r\n".getBytes() to the output stream.

Parameters:

data - the bytes to be written

Throws:

HttpRecoverableException - when socket exceptions occur writing data

IllegalStateException - if the connection is not open

IOException - if an I/O problem occurs

writeLine

public void writeLine()
               throws IOException,
                      IllegalStateException,
                      HttpRecoverableException

Writes "\r\n".getBytes() to the output stream.

Throws:

HttpRecoverableException - when socket exceptions occur writing data

IllegalStateException - if the connection is not open

IOException - if an I/O problem occurs

print

public void print(String data)
           throws IOException,
                  IllegalStateException,
                  HttpRecoverableException

Writes the specified String (as bytes) to the output stream.

Parameters:

data - the string to be written

Throws:

HttpRecoverableException - when socket exceptions occur writing data

IllegalStateException - if the connection is not open

IOException - if an I/O problem occurs

printLine

public void printLine(String data)
               throws IOException,
                      IllegalStateException,
                      HttpRecoverableException

Writes the specified String (as bytes), followed by "\r\n".getBytes() to the output stream.

Parameters:

data - the data to be written

Throws:

HttpRecoverableException - when socket exceptions occur writing data

IllegalStateException - if the connection is not open

IOException - if an I/O problem occurs

printLine

public void printLine()
               throws IOException,
                      IllegalStateException,
                      HttpRecoverableException

Writes "\r\n".getBytes() to the output stream.

Throws:

HttpRecoverableException - when socket exceptions occur writing data

IllegalStateException - if the connection is not open

IOException - if an I/O problem occurs

readLine

public String readLine()
                throws IOException,
                       IllegalStateException

Reads up to "\n" from the (unchunked) input stream. If the stream ends before the line terminator is found, the last part of the string will still be returned.

Returns:

a line from the response

Throws:

IllegalStateException - if the connection is not open

IOException - if an I/O problem occurs

shutdownOutput

public void shutdownOutput()

Attempts to shutdown the Socket's output, via Socket.shutdownOutput() when running on JVM 1.3 or higher.

close

public void close()

Closes the socket and streams.

getHttpConnectionManager

public HttpConnectionManager getHttpConnectionManager()

Returns the httpConnectionManager.

Returns:

HttpConnectionManager

setHttpConnectionManager

public void setHttpConnectionManager(HttpConnectionManager httpConnectionManager)

Sets the httpConnectionManager.

Parameters:

httpConnectionManager - The httpConnectionManager to set

releaseConnection

public void releaseConnection()

Release the connection.

closeSocketAndStreams

protected void closeSocketAndStreams()

Closes everything out.

assertNotOpen

protected void assertNotOpen()
                      throws IllegalStateException

Throws an IllegalStateException if the connection is already open.

Throws:

IllegalStateException - if connected

assertOpen

protected void assertOpen()
                   throws IllegalStateException

Throws an IllegalStateException if the connection is not open.

Throws:

IllegalStateException - if not connected

getSendBufferSize

public int getSendBufferSize()
                      throws SocketException

Gets the socket's sendBufferSize.

Returns:

the size of the buffer for the socket OutputStream, -1 if the value has not been set and the socket has not been opened

Throws:

SocketException - if an error occurs while getting the socket value

See Also:

Socket.getSendBufferSize()

setSendBufferSize

public void setSendBufferSize(int sendBufferSize)
                       throws SocketException

Sets the socket's sendBufferSize.

Parameters:

sendBufferSize - the size to set for the socket OutputStream

Throws:

SocketException - if an error occurs while setting the socket value

See Also:

Socket.setSendBufferSize(int)