org.apache.commons.httpclient
Class HttpConnection

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

public class HttpConnection
extends java.lang.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.36 $ $Date: 2003/01/25 04:46:39 $
Author:
Rod Waldhoff, Sean C. Sullivan, Ortwin Glück, Jeff Dever

Nested Class Summary
 class HttpConnection.ConnectionTimeoutException
          Signals that a timeout occured while opening the socket.
 
Constructor Summary
HttpConnection(HostConfiguration hostConfiguration)
          Creates a new HttpConnection.
HttpConnection(java.lang.String host, int port)
          Constructor.
HttpConnection(java.lang.String host, int port, boolean secure)
          Deprecated. use HttpConnection(String, int, Protocol)
HttpConnection(java.lang.String host, int port, Protocol protocol)
          Constructor.
HttpConnection(java.lang.String proxyHost, int proxyPort, java.lang.String host, int port)
          Constructor.
HttpConnection(java.lang.String proxyHost, int proxyPort, java.lang.String host, int port, boolean secure)
          Deprecated. use HttpConnection(String, int, String, int, Protocol)
HttpConnection(java.lang.String proxyHost, int proxyPort, java.lang.String host, int port, Protocol protocol)
           
 
Method Summary
protected  void assertNotOpen()
          Throw an IllegalStateException if I am connected.
protected  void assertOpen()
          Throw an IllegalStateException if I am not connected.
 void close()
          Close my socket and streams.
protected  void closeSocketAndStreams()
          Close everything out.
 java.lang.String getHost()
          Return my host.
 HttpConnectionManager getHttpConnectionManager()
          Returns the httpConnectionManager.
 java.io.InputStream getLastResponseInputStream()
          Returns the stream used to read the last response's body.
 int getPort()
          Return my port.
 Protocol getProtocol()
          Get the protocol.
 java.lang.String getProxyHost()
          Return my proxy host.
 int getProxyPort()
          Return my proxy port.
 java.io.OutputStream getRequestOutputStream()
          Return a RequestOutputStream suitable for writing (possibly chunked) bytes to my OutputStream.
 java.io.OutputStream getRequestOutputStream(boolean useChunking)
          Deprecated. Use new ChunkedOutputStream(httpConnecion.getRequestOutputStream());
 java.io.InputStream getResponseInputStream()
           
 java.io.InputStream getResponseInputStream(HttpMethod method)
          Deprecated. Use getResponseInputStream() instead.
 boolean isOpen()
          Return true if I am connected, false otherwise.
 boolean isProxied()
          Return true if I am (or I will be) connected via a proxy, false otherwise.
 boolean isSecure()
          Return true if I will (or I am) connected over a secure (HTTPS/SSL) protocol.
 boolean isTransparent()
          Indicates if the connection is completely transparent from end to end.
 void open()
          Open this connection to the current host and port (via a proxy if so configured).
 void print(java.lang.String data)
          Write the specified String (as bytes) to my output stream.
 void printLine()
          Write "\r\n".getBytes() to my output stream.
 void printLine(java.lang.String data)
          Write the specified String (as bytes), followed by "\r\n".getBytes() to my output stream.
 java.lang.String readLine()
          Read up to "\r\n" from my (unchunked) input stream.
 void releaseConnection()
           
 void setConnectionTimeout(int timeout)
          Sets the connection timeout.
 void setHost(java.lang.String host)
          Set my host.
 void setHttpConnectionManager(HttpConnectionManager httpConnectionManager)
          Sets the httpConnectionManager.
 void setLastResponseInputStream(java.io.InputStream inStream)
          Set the state to keep track of the last response for the last request.
 void setPort(int port)
          Set my port.
 void setProtocol(Protocol protocol)
          Sets the protocol used by this connection.
 void setProxyHost(java.lang.String host)
          Set the host I should proxy through.
 void setProxyPort(int port)
          Set the port I should proxy through.
 void setSecure(boolean secure)
          Deprecated. use setProtocol(Protocol)
 void setSoTimeout(int timeout)
          Set my Socket's timeout, via Socket.setSoTimeout(int).
 void shutdownOutput()
          Shutdown my Socket's output, via Socket.shutdownOutput().
 void tunnelCreated()
          Calling this method indicates that the proxy has successfully created the tunnel to the host.
 void write(byte[] data)
          Write the specified bytes to my output stream.
 void write(byte[] data, int offset, int length)
          Write length bytes in data starting at offset to my output stream.
 void writeLine()
          Write "\r\n".getBytes() to my output stream.
 void writeLine(byte[] data)
          Write the specified bytes, followed by "\r\n".getBytes() to my output stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

HttpConnection

public HttpConnection(java.lang.String host,
                      int port)
Constructor.

Parameters:
host - the host I should connect to
port - the port I should connect to

HttpConnection

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

Constructor.

Parameters:
host - the host I should connect to
port - the port I should connect to
secure - when true, connect via HTTPS (SSL)
See Also:
HttpConnection(String,int,Protocol)

HttpConnection

public HttpConnection(java.lang.String host,
                      int port,
                      Protocol protocol)
Constructor.

Parameters:
host - the host I should connect to
port - the port I should connect to
protocol - the protocol to use

HttpConnection

public HttpConnection(java.lang.String proxyHost,
                      int proxyPort,
                      java.lang.String host,
                      int port)
Constructor.

Parameters:
proxyHost - the host I should proxy via
proxyPort - the port I should proxy via
host - the host I should connect to
port - the port I should connect to

HttpConnection

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

Fully-specified constructor.

Parameters:
proxyHost - the host I should proxy via
proxyPort - the port I should proxy via
host - the host I should connect to. Parameter value must be non-null.
port - the port I should connect to
secure - when true, connect via HTTPS (SSL)
See Also:
HttpConnection(String, int, String, int, Protocol)

HttpConnection

public HttpConnection(HostConfiguration hostConfiguration)
Creates a new HttpConnection.

Parameters:
hostConfiguration - the host/proxy/protocol to use

HttpConnection

public HttpConnection(java.lang.String proxyHost,
                      int proxyPort,
                      java.lang.String host,
                      int port,
                      Protocol protocol)
Method Detail

getHost

public java.lang.String getHost()
Return my host.

Returns:
my host.

setHost

public void setHost(java.lang.String host)
             throws java.lang.IllegalStateException
Set my host.

Parameters:
host - the host I should connect to. Parameter value must be non-null.
Throws:
java.lang.IllegalStateException - if I am already connected

getPort

public int getPort()
Return my port. If the port is -1 (or less than 0) the default port for the current protocol is returned.

Returns:
my port.

setPort

public void setPort(int port)
             throws java.lang.IllegalStateException
Set my port.

Parameters:
port - the port I should connect to
Throws:
java.lang.IllegalStateException - if I am already connected

getProxyHost

public java.lang.String getProxyHost()
Return my proxy host.

Returns:
my proxy host.

setProxyHost

public void setProxyHost(java.lang.String host)
                  throws java.lang.IllegalStateException
Set the host I should proxy through.

Parameters:
host - the host I should proxy through.
Throws:
java.lang.IllegalStateException - if I am already connected

getProxyPort

public int getProxyPort()
Return my proxy port.

Returns:
my proxy port.

setProxyPort

public void setProxyPort(int port)
                  throws java.lang.IllegalStateException
Set the port I should proxy through.

Parameters:
port - the host I should proxy through.
Throws:
java.lang.IllegalStateException - if I am already connected

isSecure

public boolean isSecure()
Return true if I will (or I am) connected over a secure (HTTPS/SSL) protocol.

Returns:
true if I will (or I am) connected over a secure (HTTPS/SSL) protocol.

getProtocol

public Protocol getProtocol()
Get the protocol.

Returns:
HTTPS if secure, HTTP otherwise

setSecure

public void setSecure(boolean secure)
               throws java.lang.IllegalStateException
Deprecated. use setProtocol(Protocol)

Set whether or not I should connect over HTTPS (SSL).

Parameters:
secure - whether or not I should connect over HTTPS (SSL).
Throws:
java.lang.IllegalStateException - if I am already connected
See Also:
setProtocol(Protocol)

setProtocol

public void setProtocol(Protocol protocol)
Sets the protocol used by this connection.

Parameters:
protocol -

isOpen

public boolean isOpen()
Return true if I am connected, false otherwise.

Returns:
true if I am connected

isProxied

public boolean isProxied()
Return true if I am (or I will be) connected via a proxy, false otherwise.

Returns:
true if I am (or I will be) connected via a proxy, false otherwise.

setLastResponseInputStream

public void setLastResponseInputStream(java.io.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 java.io.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 java.net.SocketException,
                         java.lang.IllegalStateException
Set my 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:
java.net.SocketException - - if there is an error in the underlying protocol, such as a TCP error.
java.lang.IllegalStateException - if I am not connected

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 java.io.IOException
Open this connection to the current host and port (via a proxy if so configured). The underlying socket is created from the ProtocolSocketFactory.

Throws:
java.io.IOException - when there are errors opening the connection

tunnelCreated

public void tunnelCreated()
                   throws java.lang.IllegalStateException,
                          java.io.IOException
Calling this method indicates that the proxy has successfully created the 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:
java.lang.IllegalStateException - if connection is not secure and proxied or if the socket is already secure.
java.io.IOException - if an error occured creating the secure socket

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.

getRequestOutputStream

public java.io.OutputStream getRequestOutputStream()
                                            throws java.io.IOException,
                                                   java.lang.IllegalStateException
Return a RequestOutputStream suitable for writing (possibly chunked) bytes to my OutputStream.

Returns:
a stream to write the request to
Throws:
java.lang.IllegalStateException - if I am not connected
java.io.IOException - if an I/O problem occurs

getRequestOutputStream

public java.io.OutputStream getRequestOutputStream(boolean useChunking)
                                            throws java.io.IOException,
                                                   java.lang.IllegalStateException
Deprecated. Use new ChunkedOutputStream(httpConnecion.getRequestOutputStream());

Return a RequestOutputStream suitable for writing (possibly chunked) bytes to my OutputStream.

Parameters:
useChunking - when true the chunked transfer-encoding will be used
Returns:
a stream to write the request to
Throws:
java.lang.IllegalStateException - if I am not connected
java.io.IOException - if an I/O problem occurs

getResponseInputStream

public java.io.InputStream getResponseInputStream(HttpMethod method)
                                           throws java.io.IOException,
                                                  java.lang.IllegalStateException
Deprecated. Use getResponseInputStream() instead.

Return a ResponseInputStream suitable for reading (possibly chunked) bytes from my InputStream.

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:
java.lang.IllegalStateException - if I am not connected
java.io.IOException - if an I/O problem occurs

getResponseInputStream

public java.io.InputStream getResponseInputStream()
                                           throws java.io.IOException,
                                                  java.lang.IllegalStateException
java.io.IOException
java.lang.IllegalStateException

write

public void write(byte[] data)
           throws java.io.IOException,
                  java.lang.IllegalStateException,
                  HttpRecoverableException
Write the specified bytes to my output stream.

Parameters:
data - the data to be written
Throws:
HttpRecoverableException - if a SocketException occurs
java.lang.IllegalStateException - if not connected
java.io.IOException - if an I/O problem occurs
See Also:
write(byte[],int,int)

write

public void write(byte[] data,
                  int offset,
                  int length)
           throws java.io.IOException,
                  java.lang.IllegalStateException,
                  HttpRecoverableException
Write length bytes in data starting at offset to my 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
java.lang.IllegalStateException - if not connected
java.io.IOException - if an I/O problem occurs

writeLine

public void writeLine(byte[] data)
               throws java.io.IOException,
                      java.lang.IllegalStateException,
                      HttpRecoverableException
Write the specified bytes, followed by "\r\n".getBytes() to my output stream.

Parameters:
data - the bytes to be written
Throws:
HttpRecoverableException - when socket exceptions occur writing data
java.lang.IllegalStateException - if I am not connected
java.io.IOException - if an I/O problem occurs

writeLine

public void writeLine()
               throws java.io.IOException,
                      java.lang.IllegalStateException,
                      HttpRecoverableException
Write "\r\n".getBytes() to my output stream.

Throws:
HttpRecoverableException - when socket exceptions occur writing data
java.lang.IllegalStateException - if I am not connected
java.io.IOException - if an I/O problem occurs

print

public void print(java.lang.String data)
           throws java.io.IOException,
                  java.lang.IllegalStateException,
                  HttpRecoverableException
Write the specified String (as bytes) to my output stream.

Parameters:
data - the string to be written
Throws:
HttpRecoverableException - when socket exceptions occur writing data
java.lang.IllegalStateException - if I am not connected
java.io.IOException - if an I/O problem occurs

printLine

public void printLine(java.lang.String data)
               throws java.io.IOException,
                      java.lang.IllegalStateException,
                      HttpRecoverableException
Write the specified String (as bytes), followed by "\r\n".getBytes() to my output stream.

Parameters:
data - the data to be written
Throws:
HttpRecoverableException - when socket exceptions occur writing data
java.lang.IllegalStateException - if I am not connected
java.io.IOException - if an I/O problem occurs

printLine

public void printLine()
               throws java.io.IOException,
                      java.lang.IllegalStateException,
                      HttpRecoverableException
Write "\r\n".getBytes() to my output stream.

Throws:
HttpRecoverableException - when socket exceptions occur writing data
java.lang.IllegalStateException - if I am not connected
java.io.IOException - if an I/O problem occurs

readLine

public java.lang.String readLine()
                          throws java.io.IOException,
                                 java.lang.IllegalStateException
Read up to "\r\n" from my (unchunked) input stream.

Returns:
a line from the response
Throws:
java.lang.IllegalStateException - if I am not connected
java.io.IOException - if an I/O problem occurs

shutdownOutput

public void shutdownOutput()
Shutdown my Socket's output, via Socket.shutdownOutput().


close

public void close()
Close my 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()

closeSocketAndStreams

protected void closeSocketAndStreams()
Close everything out.


assertNotOpen

protected void assertNotOpen()
                      throws java.lang.IllegalStateException
Throw an IllegalStateException if I am connected.

Throws:
java.lang.IllegalStateException - if connected

assertOpen

protected void assertOpen()
                   throws java.lang.IllegalStateException
Throw an IllegalStateException if I am not connected.

Throws:
java.lang.IllegalStateException - if not connected


Copyright © 2001-2003 Apache Software Foundation. All Rights Reserved.