| java.lang.Object
 org.apache.commons.httpclient.HttpConnection
| HttpConnection | | public class HttpConnection (Code) | | 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
HttpConnection.open() method:
author:
Rod Waldhoff
author:
Sean C. Sullivan
author:
Ortwin Glueck
author:
Jeff Dever
author:
Mike Bowler
author:
Oleg Kalnichevski
author:
Michael Becke
author:
Eric E Johnson
author:
Laura Werner
version:
$Revision: 5024 $ $Date: 2007-03-23 21:40:57 +0000 (Fri, 23 Mar 2007) $ |
| Field Summary | |
| protected boolean | isOpen
Whether or not the connection is connected. |
| Constructor Summary | |
| public | HttpConnection(String host, int port)
Creates a new HTTP connection for the given host and port. | | public | HttpConnection(String host, int port, Protocol protocol)
Creates a new HTTP connection for the given host and port
using the given protocol. | | 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. | | 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. | | public | HttpConnection(HostConfiguration hostConfiguration)
Creates a new HTTP connection for the given host configuration. | | 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
Parameters:
proxyPort - the port to proxy via
Parameters:
host - the host to connect to. | | public | HttpConnection(String proxyHost, int proxyPort, String host, 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
Parameters:
proxyPort - the port to proxy via
Parameters:
host - the host to connect to. |
| 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. | | public void | close()
Closes the socket and streams. | | public boolean | closeIfStale()
Closes the connection if stale. | | protected void | closeSocketAndStreams()
Closes everything out. | | public void | flushRequestOutputStream()
Flushes the output request stream. | | public String | getHost()
Returns the host. | | public HttpConnectionManager | getHttpConnectionManager()
Returns the httpConnectionManager. | | 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 .
For those clients, call this function, and if it returns a non-null stream,
close the stream before attempting to execute a method. | | public InetAddress | getLocalAddress()
Return the local address used when creating the connection. | | public HttpConnectionParams | getParams()
Returns
HttpConnectionParams HTTP protocol parameters associated with this method. | | public int | getPort()
Returns the port of the host. | | public Protocol | getProtocol()
Returns the protocol used to establish the connection. | | public String | getProxyHost()
Returns the proxy host. | | public int | getProxyPort()
Returns the port of the proxy host. | | public OutputStream | getRequestOutputStream()
Returns an
OutputStream suitable for writing the request. | | public InputStream | getResponseInputStream()
Return a
InputStream suitable for reading the response. | | public int | getSendBufferSize()
Gets the socket's sendBufferSize. | | public int | getSoTimeout()
Returns the
Socket 's timeout, via
Socket.getSoTimeout , if the
connection is already open. | | protected Socket | getSocket()
Returns the connection socket. | | public String | getVirtualHost()
Returns the target virtual host. | | protected boolean | isLocked()
Tests if the connection is locked. | | public boolean | isOpen()
Tests if the connection is open. | | public boolean | isProxied()
Returns true if the connection is established via a proxy,
false otherwise. | | public boolean | isResponseAvailable()
Tests if input data avaialble. | | public boolean | isResponseAvailable(int timeout)
Tests if input data becomes available within the given period time in milliseconds. | | public 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.
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. | | public boolean | isStaleCheckingEnabled()
Tests if stale checking is enabled. | | public boolean | isTransparent()
Indicates if the connection is completely transparent from end to end. | | public void | open()
Establishes a connection to the specified host and port
(via a proxy if specified). | | public void | print(String data)
| | public void | print(String data, String charset)
Writes the specified String (as bytes) to the output stream. | | public void | printLine(String data)
| | public void | printLine(String data, String charset)
Writes the specified String (as bytes), followed by
"\r\n".getBytes() to the output stream. | | public void | printLine()
Writes "\r\n".getBytes() to the output stream. | | public String | readLine()
Reads up to "\n" from the (unchunked) input stream. | | public String | readLine(String charset)
Reads up to "\n" from the (unchunked) input stream. | | public void | releaseConnection()
Releases the connection. | | public void | setConnectionTimeout(int timeout)
Sets the connection timeout. | | public void | setHost(String host)
Sets the host to connect to.
Parameters:
host - the host to connect to. | | public void | setHttpConnectionManager(HttpConnectionManager httpConnectionManager)
Sets the httpConnectionManager. | | 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. | | public void | setLocalAddress(InetAddress localAddress)
Set the local address used when creating the connection. | | protected void | setLocked(boolean locked)
Locks or unlocks the connection. | | public void | setParams(HttpConnectionParams params)
Assigns
HttpConnectionParams HTTP protocol parameters for this method. | | public void | setPort(int port)
Sets the port to connect to. | | public void | setProtocol(Protocol protocol)
| | public void | setProxyHost(String host)
Sets the host to proxy through. | | public void | setProxyPort(int port)
Sets the port of the host to proxy through. | | public void | setSendBufferSize(int sendBufferSize)
Sets the socket's sendBufferSize. | | public void | setSoTimeout(int timeout)
Set the
Socket 's timeout, via
Socket.setSoTimeout . | | public void | setSocketTimeout(int timeout)
Sets SO_TIMEOUT value directly on the underlying
Socket socket . | | 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. | | public void | setVirtualHost(String host)
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. | | public void | shutdownOutput()
Attempts to shutdown the
Socket 's output, via Socket.shutdownOutput()
when running on JVM 1.3 or higher. | | public void | tunnelCreated()
Instructs the proxy to establish a secure tunnel to the host. | | public void | write(byte[] data)
Writes the specified bytes to the output stream. | | public void | write(byte[] data, int offset, int length)
Writes length bytes in data starting at
offset to the output stream. | | public void | writeLine(byte[] data)
Writes the specified bytes, followed by "\r\n".getBytes() to the
output stream. | | public void | writeLine()
Writes "\r\n".getBytes() to the output stream. |
| isOpen | | protected boolean isOpen(Code) | | Whether or not the connection is connected.
|
| HttpConnection | | public HttpConnection(String host, int port)(Code) | | Creates a new HTTP connection for the given host and port.
Parameters:
host - the host to connect to
Parameters:
port - the port to connect to |
| HttpConnection | | public HttpConnection(String host, int port, Protocol protocol)(Code) | | Creates a new HTTP connection for the given host and port
using the given protocol.
Parameters:
host - the host to connect to
Parameters:
port - the port to connect to
Parameters:
protocol - the protocol to use |
| HttpConnection | | public HttpConnection(String host, String virtualHost, int port, Protocol protocol)(Code) | | 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
Parameters:
virtualHost - the virtual host requests will be sent to
Parameters:
port - the port to connect to
Parameters:
protocol - the protocol to use |
| HttpConnection | | public HttpConnection(String proxyHost, int proxyPort, String host, int port)(Code) | | 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
Parameters:
proxyPort - the port to proxy via
Parameters:
host - the host to connect to
Parameters:
port - the port to connect to |
| HttpConnection | | public HttpConnection(HostConfiguration hostConfiguration)(Code) | | 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)(Code) | | 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
Parameters:
proxyPort - the port to proxy via
Parameters:
host - the host to connect to. Parameter value must be non-null.
Parameters:
virtualHost - No longer applicable.
Parameters:
port - the port to connect to
Parameters:
protocol - The protocol to use. Parameter value must be non-null. |
| HttpConnection | | public HttpConnection(String proxyHost, int proxyPort, String host, int port, Protocol protocol)(Code) | | 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
Parameters:
proxyPort - the port to proxy via
Parameters:
host - the host to connect to. Parameter value must be non-null.
Parameters:
port - the port to connect to
Parameters:
protocol - The protocol to use. Parameter value must be non-null. |
| close | | public void close()(Code) | | Closes the socket and streams.
|
| closeIfStale | | public boolean closeIfStale() throws IOException(Code) | | Closes the connection if stale.
true if the connection was stale and therefore closed, false otherwise.
See Also: HttpConnection.isStale()
since:
3.0 |
| closeSocketAndStreams | | protected void closeSocketAndStreams()(Code) | | Closes everything out.
|
| flushRequestOutputStream | | public void flushRequestOutputStream() throws IOException(Code) | | 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 |
| getHost | | public String getHost()(Code) | | Returns the host.
the host. |
| getHttpConnectionManager | | public HttpConnectionManager getHttpConnectionManager()(Code) | | Returns the httpConnectionManager.
HttpConnectionManager |
| getLastResponseInputStream | | public InputStream getLastResponseInputStream()(Code) | | 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 .
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.
An InputStream corresponding to the body of the lastresponse. |
| getLocalAddress | | public InetAddress getLocalAddress()(Code) | | Return the local address used when creating the connection.
If null, the default address is used.
InetAddress the local address to be used when creating Sockets |
| getParams | | public HttpConnectionParams getParams()(Code) | | Returns
HttpConnectionParams HTTP protocol parameters associated with this method.
HTTP parameters.
since:
3.0 |
| getPort | | public int getPort()(Code) | | Returns the port of the host.
If the port is -1 (or less than 0) the default port for
the current protocol is returned.
the port. |
| getProtocol | | public Protocol getProtocol()(Code) | | Returns the protocol used to establish the connection.
The protocol |
| getProxyHost | | public String getProxyHost()(Code) | | Returns the proxy host.
the proxy host. |
| getProxyPort | | public int getProxyPort()(Code) | | Returns the port of the proxy host.
the proxy port. |
| getSendBufferSize | | public int getSendBufferSize() throws SocketException(Code) | | Gets the socket's sendBufferSize.
the size of the buffer for the socket OutputStream, -1 if the valuehas 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 |
| getSoTimeout | | public int getSoTimeout() throws SocketException(Code) | | 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!
the timeout valueHttpConnectionParams.getSoTimeoutHttpConnection.getParams |
| getSocket | | protected Socket getSocket()(Code) | | Returns the connection socket.
the socket.
since:
3.0 |
| getVirtualHost | | public String getVirtualHost()(Code) | | Returns the target virtual host.
the virtual host. |
| isLocked | | protected boolean isLocked()(Code) | | Tests if the connection is locked. Locked connections cannot be released.
An attempt to release a locked connection will have no effect.
true if the connection is locked, false otherwise.
since:
3.0 |
| isOpen | | public boolean isOpen()(Code) | | Tests if the connection is open.
true if the connection is open |
| isProxied | | public boolean isProxied()(Code) | | Returns true if the connection is established via a proxy,
false otherwise.
true if a proxy is used to establish the connection, false otherwise. |
| isResponseAvailable | | public boolean isResponseAvailable() throws IOException(Code) | | Tests if input data avaialble. This method returns immediately
and does not perform any read operations on the input socket
boolean true if input data is available, false otherwise.
throws:
IOException - If an IO problem occurs
throws:
IllegalStateException - If the connection isn't open. |
| isResponseAvailable | | public boolean isResponseAvailable(int timeout) throws IOException(Code) | | 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 boolean true if input data is availble, false otherwise.
throws:
IOException - If an IO problem occurs
throws:
IllegalStateException - If the connection isn't open. |
| isSecure | | public boolean isSecure()(Code) | | Returns true if the connection is established over
a secure protocol.
true if connected over a secure protocol. |
| isStale | | protected boolean isStale() throws IOException(Code) | | 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
BufferedInputStream , so although data might be read, what is visible
to clients of the connection will not change with this call.throws:
IOException - if the stale connection test is interrupted. true if the connection is already closed, or a read wouldfail. |
| isTransparent | | public boolean isTransparent()(Code) | | Indicates if the connection is completely transparent from end to end.
true if conncetion is not proxied or tunneled through a transparentproxy; false otherwise. |
| open | | public void open() throws IOException(Code) | | 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 anI/O error. |
| printLine | | public void printLine(String data, String charset) throws IOException, IllegalStateException(Code) | | Writes the specified String (as bytes), followed by
"\r\n".getBytes() to the output stream.
Parameters:
data - the data to be written
Parameters:
charset - the charset to use for writing the data
throws:
IllegalStateException - if the connection is not open
throws:
IOException - if an I/O problem occurs
since:
3.0 |
| readLine | | public String readLine(String charset) throws IOException, IllegalStateException(Code) | | 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.
Parameters:
charset - the charset to use for reading the data
throws:
IllegalStateException - if the connection is not open
throws:
IOException - if an I/O problem occurs a line from the response
since:
3.0 |
| releaseConnection | | public void releaseConnection()(Code) | | Releases the connection. If the connection is locked or does not have a connection
manager associated with it, this method has no effect. Note that it is completely safe
to call this method multiple times.
|
| setConnectionTimeout | | public void setConnectionTimeout(int timeout)(Code) | | 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.HttpConnectionParams.setConnectionTimeout(int)HttpConnection.getParams |
| setHttpConnectionManager | | public void setHttpConnectionManager(HttpConnectionManager httpConnectionManager)(Code) | | Sets the httpConnectionManager.
Parameters:
httpConnectionManager - The httpConnectionManager to set |
| setLastResponseInputStream | | public void setLastResponseInputStream(InputStream inStream)(Code) | | 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. |
| setLocalAddress | | public void setLocalAddress(InetAddress localAddress)(Code) | | 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 |
| setLocked | | protected void setLocked(boolean locked)(Code) | | Locks or unlocks the connection. Locked connections cannot be released.
An attempt to release a locked connection will have no effect.
Parameters:
locked - true to lock the connection, false to unlockthe connection.
since:
3.0 |
| setParams | | public void setParams(HttpConnectionParams params)(Code) | | Assigns
HttpConnectionParams HTTP protocol parameters for this method.
since:
3.0
See Also: HttpConnectionParams |
| setProtocol | | public void setProtocol(Protocol protocol)(Code) | | Sets the protocol used to establish the connection
Parameters:
protocol - The protocol to use.
throws:
IllegalStateException - if the connection is already open |
| setProxyPort | | public void setProxyPort(int port) throws IllegalStateException(Code) | | 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 |
| setSoTimeout | | public void setSoTimeout(int timeout) throws SocketException, IllegalStateException(Code) | | Set the
Socket 's timeout, via
Socket.setSoTimeout . 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 underlyingprotocol, such as a TCP error.HttpConnectionParams.setSoTimeout(int)HttpConnection.getParams |
| setSocketTimeout | | public void setSocketTimeout(int timeout) throws SocketException, IllegalStateException(Code) | | Sets SO_TIMEOUT value directly on the underlying
Socket socket .
This method does not change the default read timeout value set via
HttpConnectionParams .
Parameters:
timeout - the timeout value
throws:
SocketException - - if there is an error in the underlyingprotocol, such as a TCP error.
throws:
IllegalStateException - if not connected
since:
3.0 |
| setStaleCheckingEnabled | | public void setStaleCheckingEnabled(boolean staleCheckEnabled)(Code) | | 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: HttpConnection.isStale()
See Also: HttpConnection.isOpen()HttpConnectionParams.setStaleCheckingEnabled(boolean)HttpConnection.getParams |
| setVirtualHost | | public void setVirtualHost(String host) throws IllegalStateException(Code) | | 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 notto be used
throws:
IllegalStateException - if the connection is already open |
| shutdownOutput | | public void shutdownOutput()(Code) | | Attempts to shutdown the
Socket 's output, via Socket.shutdownOutput()
when running on JVM 1.3 or higher.
|
| tunnelCreated | | public void tunnelCreated() throws IllegalStateException, IOException(Code) | | 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 orif the socket is already secure.
throws:
IOException - if an attempt to establish the secure tunnel results in anI/O error. |
| write | | public void write(byte[] data, int offset, int length) throws IOException, IllegalStateException(Code) | | 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.
Parameters:
offset - the start offset in the data.
Parameters:
length - the number of bytes to write.
throws:
IllegalStateException - if not connected
throws:
IOException - if an I/O problem occurs |
|
|