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.

Version:

$Revision: 1.19 $ $Date: 2002/09/02 14:52:47 $

Author:

Rod Waldhoff, Sean C. Sullivan, Ortwin Glück

Constructor Summary

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

HttpConnection(java.lang.String host, int port, boolean secure)
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)
Fully-specified constructor.

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.
int	getPort() Return my port.
java.lang.String	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) Return a RequestOutputStream suitable for writing (possibly chunked) bytes to my OutputStream.
java.io.InputStream	getResponseInputStream(HttpMethod method) Return a ResponseInputStream suitable for reading (possibly chunked) bytes from my InputStream.
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	setHost(java.lang.String host) Set my host.
void	setPort(int port) Set my port.
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) Set whether or not I should connect over HTTPS (SSL).
void	setSoTimeout(int timeout) Set my Socket's timeout, via Socket.setSoTimeout(int).
void	setSSLSocketFactory(javax.net.ssl.SSLSocketFactory factory) Specifies an alternative factory for SSL sockets.
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)

Constructor.

Parameters:

host - the host I should connect to

port - the port I should connect to

secure - when true, connect via HTTPS (SSL)

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)

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)

Method Detail

setSSLSocketFactory

public void setSSLSocketFactory(javax.net.ssl.SSLSocketFactory factory)

Specifies an alternative factory for SSL sockets. If factory is null the default implementation is used.

Parameters:

factory - An instance of a SSLSocketFactory or null.

Throws:

java.lang.IllegalStateException - If called after the connection was opened

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 java.lang.String getProtocol()

Get the protocol.

Returns:

HTTPS if secure, HTTP otherwise

setSecure

public void setSecure(boolean secure)
               throws java.lang.IllegalStateException

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

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.

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.

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

open

public void open()
          throws java.io.IOException

Open this connection to the current host and port (via a proxy if so configured).

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

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

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 - the http method to get the input stream from

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

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.

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