|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.apache.commons.httpclient.HttpConnection
public class HttpConnection
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 | HttpConnectionParams.setTcpNoDelay(boolean)
|
Socket.setSoTimeout(int)
| SO_TIMEOUT | HttpConnectionParams.setSoTimeout(int)
|
Socket.setSendBufferSize(int)
| SO_SNDBUF | HttpConnectionParams.setSendBufferSize(int)
|
Socket.setReceiveBufferSize(int)
| SO_RCVBUF | HttpConnectionParams.setReceiveBufferSize(int)
|
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,
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,
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 proxyHost,
int proxyPort,
String host,
String virtualHost,
int port,
Protocol protocol)
Deprecated. use #HttpConnection(String, int, String, int, 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. |
boolean |
closeIfStale()
Closes the connection if stale. |
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. |
HttpConnectionParams |
getParams()
Returns HTTP protocol parameters associated with this method. |
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. |
InputStream |
getResponseInputStream()
Return a InputStream suitable for reading the response. |
int |
getSendBufferSize()
Gets the socket's sendBufferSize. |
protected Socket |
getSocket()
Returns the connection socket. |
int |
getSoTimeout()
Deprecated. Use HttpConnectionParams.getSoTimeout() ,
getParams() . |
String |
getVirtualHost()
Deprecated. no longer applicable |
protected boolean |
isLocked()
Tests if the connection is locked. |
boolean |
isOpen()
Tests if the connection is open. |
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()
Deprecated. Use HttpConnectionParams.isStaleCheckingEnabled() ,
getParams() . |
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)
Deprecated. Use print(String, String)
Writes the specified String (as bytes) to the output stream. |
void |
print(String data,
String charset)
Writes the specified String (as bytes) to the output stream. |
void |
printLine()
Writes "\r\n".getBytes() to the output stream. |
void |
printLine(String data)
Deprecated. Use printLine(String, String)
Writes the specified String (as bytes), followed by
"\r\n".getBytes() to the output stream. |
void |
printLine(String data,
String charset)
Writes the specified String (as bytes), followed by "\r\n".getBytes() to the output stream. |
String |
readLine()
Deprecated. use #readLine(String) |
String |
readLine(String charset)
Reads up to "\n" from the (unchunked) input stream. |
void |
releaseConnection()
Releases the connection. |
void |
setConnectionTimeout(int timeout)
Deprecated. Use HttpConnectionParams.setConnectionTimeout(int) ,
getParams() . |
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. |
protected void |
setLocked(boolean locked)
Locks or unlocks the connection. |
void |
setParams(HttpConnectionParams params)
Assigns HTTP protocol parameters for this method. |
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 |
setSendBufferSize(int sendBufferSize)
Deprecated. Use HttpConnectionParams.setSendBufferSize(int) ,
getParams() . |
void |
setSocketTimeout(int timeout)
Sets SO_TIMEOUT value directly on the underlying socket . |
void |
setSoTimeout(int timeout)
Deprecated. Use HttpConnectionParams.setSoTimeout(int) ,
getParams() . |
void |
setStaleCheckingEnabled(boolean staleCheckEnabled)
Deprecated. Use HttpConnectionParams.setStaleCheckingEnabled(boolean) ,
getParams() . |
void |
setVirtualHost(String host)
Deprecated. no longer applicable |
void |
shutdownOutput()
Deprecated. unused |
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 |
---|
protected boolean isOpen
Constructor Detail |
---|
public HttpConnection(String host, int port)
host
- the host to connect toport
- the port to connect topublic HttpConnection(String host, int port, Protocol protocol)
host
- the host to connect toport
- the port to connect toprotocol
- the protocol to usepublic HttpConnection(String host, String virtualHost, int port, Protocol protocol)
host
- the host to connect tovirtualHost
- the virtual host requests will be sent toport
- the port to connect toprotocol
- the protocol to usepublic HttpConnection(String proxyHost, int proxyPort, String host, int port)
proxyHost
- the host to proxy viaproxyPort
- the port to proxy viahost
- the host to connect toport
- the port to connect topublic HttpConnection(HostConfiguration hostConfiguration)
hostConfiguration
- the host/proxy/protocol to usepublic HttpConnection(String proxyHost, int proxyPort, String host, String virtualHost, int port, Protocol protocol)
proxyHost
- the host to proxy viaproxyPort
- the port to proxy viahost
- the host to connect to. Parameter value must be non-null.virtualHost
- No longer applicable.port
- the port to connect toprotocol
- The protocol to use. Parameter value must be non-null.public HttpConnection(String proxyHost, int proxyPort, String host, int port, Protocol protocol)
proxyHost
- the host to proxy viaproxyPort
- the port to proxy viahost
- the host to connect to. Parameter value must be non-null.port
- the port to connect toprotocol
- The protocol to use. Parameter value must be non-null.Method Detail |
---|
protected Socket getSocket()
public String getHost()
public void setHost(String host) throws IllegalStateException
host
- the host to connect to. Parameter value must be non-null.
IllegalStateException
- if the connection is already openpublic String getVirtualHost()
public void setVirtualHost(String host) throws IllegalStateException
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
IllegalStateException
- if the connection is already openpublic int getPort()
public void setPort(int port) throws IllegalStateException
port
- the port to connect to
IllegalStateException
- if the connection is already openpublic String getProxyHost()
public void setProxyHost(String host) throws IllegalStateException
host
- the host to proxy through.
IllegalStateException
- if the connection is already openpublic int getProxyPort()
public void setProxyPort(int port) throws IllegalStateException
port
- the port of the host to proxy through.
IllegalStateException
- if the connection is already openpublic boolean isSecure()
public Protocol getProtocol()
public void setProtocol(Protocol protocol)
protocol
- The protocol to use.
IllegalStateException
- if the connection is already openpublic InetAddress getLocalAddress()
public void setLocalAddress(InetAddress localAddress)
localAddress
- the local address to usepublic boolean isOpen()
true
if the connection is openpublic boolean closeIfStale() throws IOException
true
if the connection was stale and therefore closed,
false
otherwise.
IOException
isStale()
public boolean isStaleCheckingEnabled()
HttpConnectionParams.isStaleCheckingEnabled()
,
getParams()
.
true
if enabledisStale()
public void setStaleCheckingEnabled(boolean staleCheckEnabled)
HttpConnectionParams.setStaleCheckingEnabled(boolean)
,
getParams()
.
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.
staleCheckEnabled
- true
to enable isStale()isStale()
,
isOpen()
protected boolean isStale() throws IOException
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.
IOException
- if the stale connection test is interrupted.public boolean isProxied()
public void setLastResponseInputStream(InputStream inStream)
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.
inStream
- The stream associated with an HttpMethod.public InputStream getLastResponseInputStream()
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.
InputStream
corresponding to the body of the last
response.public HttpConnectionParams getParams()
HTTP protocol parameters
associated with this method.
public void setParams(HttpConnectionParams params)
HTTP protocol parameters
for this method.
HttpConnectionParams
public void setSoTimeout(int timeout) throws SocketException, IllegalStateException
HttpConnectionParams.setSoTimeout(int)
,
getParams()
.
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!
timeout
- the timeout value
SocketException
- - if there is an error in the underlying
protocol, such as a TCP error.
IllegalStateException
public void setSocketTimeout(int timeout) throws SocketException, IllegalStateException
SO_TIMEOUT
value directly on the underlying socket
.
This method does not change the default read timeout value set via
HttpConnectionParams
.
timeout
- the timeout value
SocketException
- - if there is an error in the underlying
protocol, such as a TCP error.
IllegalStateException
- if not connectedpublic int getSoTimeout() throws SocketException
HttpConnectionParams.getSoTimeout()
,
getParams()
.
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!
SocketException
public void setConnectionTimeout(int timeout)
HttpConnectionParams.setConnectionTimeout(int)
,
getParams()
.
timeout
- The timeout in milliseconds. 0 means timeout is not used.public void open() throws IOException
ProtocolSocketFactory
.
IOException
- if an attempt to establish the connection results in an
I/O error.public void tunnelCreated() throws IllegalStateException, IOException
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.public boolean isTransparent()
public void flushRequestOutputStream() throws IOException
IOException
- if an I/O problem occurspublic OutputStream getRequestOutputStream() throws IOException, IllegalStateException
OutputStream
suitable for writing the request.
IllegalStateException
- if the connection is not open
IOException
- if an I/O problem occurspublic InputStream getResponseInputStream() throws IOException, IllegalStateException
InputStream
suitable for reading the response.
IOException
- If an IO problem occurs
IllegalStateException
- If the connection isn't open.public boolean isResponseAvailable() throws IOException
IOException
- If an IO problem occurs
IllegalStateException
- If the connection isn't open.public boolean isResponseAvailable(int timeout) throws IOException
timeout
- The number milliseconds to wait for input data to become available
IOException
- If an IO problem occurs
IllegalStateException
- If the connection isn't open.public void write(byte[] data) throws IOException, IllegalStateException
data
- the data to be written
IllegalStateException
- if not connected
IOException
- if an I/O problem occurswrite(byte[],int,int)
public void write(byte[] data, int offset, int length) throws IOException, IllegalStateException
data
- array containing the data to be written.offset
- the start offset in the data.length
- the number of bytes to write.
IllegalStateException
- if not connected
IOException
- if an I/O problem occurspublic void writeLine(byte[] data) throws IOException, IllegalStateException
data
- the bytes to be written
IllegalStateException
- if the connection is not open
IOException
- if an I/O problem occurspublic void writeLine() throws IOException, IllegalStateException
IllegalStateException
- if the connection is not open
IOException
- if an I/O problem occurspublic void print(String data) throws IOException, IllegalStateException
print(String, String)
Writes the specified String (as bytes) to the output stream.
data
- the string to be written
IllegalStateException
- if the connection is not open
IOException
- if an I/O problem occurspublic void print(String data, String charset) throws IOException, IllegalStateException
data
- the string to be writtencharset
- the charset to use for writing the data
IllegalStateException
- if the connection is not open
IOException
- if an I/O problem occurspublic void printLine(String data) throws IOException, IllegalStateException
printLine(String, String)
Writes the specified String (as bytes), followed by
"\r\n".getBytes() to the output stream.
data
- the data to be written
IllegalStateException
- if the connection is not open
IOException
- if an I/O problem occurspublic void printLine(String data, String charset) throws IOException, IllegalStateException
data
- the data to be writtencharset
- the charset to use for writing the data
IllegalStateException
- if the connection is not open
IOException
- if an I/O problem occurspublic void printLine() throws IOException, IllegalStateException
IllegalStateException
- if the connection is not open
IOException
- if an I/O problem occurspublic String readLine() throws IOException, IllegalStateException
IllegalStateException
- if the connection is not open
IOException
- if an I/O problem occurspublic String readLine(String charset) throws IOException, IllegalStateException
charset
- the charset to use for reading the data
IllegalStateException
- if the connection is not open
IOException
- if an I/O problem occurspublic void shutdownOutput()
Socket
's output, via Socket.shutdownOutput()
when running on JVM 1.3 or higher.
public void close()
public HttpConnectionManager getHttpConnectionManager()
public void setHttpConnectionManager(HttpConnectionManager httpConnectionManager)
httpConnectionManager
- The httpConnectionManager to setpublic void releaseConnection()
protected boolean isLocked()
protected void setLocked(boolean locked)
locked
- true to lock the connection, false to unlock
the connection.protected void closeSocketAndStreams()
protected void assertNotOpen() throws IllegalStateException
IllegalStateException
if the connection is already open.
IllegalStateException
- if connectedprotected void assertOpen() throws IllegalStateException
IllegalStateException
if the connection is not open.
IllegalStateException
- if not connectedpublic int getSendBufferSize() throws SocketException
SocketException
- if an error occurs while getting the socket valueSocket.getSendBufferSize()
public void setSendBufferSize(int sendBufferSize) throws SocketException
HttpConnectionParams.setSendBufferSize(int)
,
getParams()
.
sendBufferSize
- the size to set for the socket OutputStream
SocketException
- if an error occurs while setting the socket valueSocket.setSendBufferSize(int)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |