Class HttpConnection
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)
|
- Version:
- $Revision: 480424 $ $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
-
Field Summary
Modifier and TypeFieldDescriptionprotected boolean
Whether or not the connection is connected. -
Constructor Summary
ConstructorDescriptionHttpConnection
(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
Modifier and TypeMethodDescriptionprotected void
Throws anIllegalStateException
if the connection is already open.protected void
Throws anIllegalStateException
if the connection is not open.void
close()
Closes the socket and streams.boolean
Closes the connection if stale.protected void
Closes everything out.void
Flushes the output request stream.getHost()
Returns the host.Returns the httpConnectionManager.Returns the stream used to read the last response's body.Return the local address used when creating the connection.ReturnsHTTP protocol parameters
associated with this method.int
getPort()
Returns the port of the host.Returns the protocol used to establish the connection.Returns the proxy host.int
Returns the port of the proxy host.Returns anOutputStream
suitable for writing the request.Return aInputStream
suitable for reading the response.int
Gets the socket's sendBufferSize.protected Socket
Returns the connection socket.int
Deprecated.Deprecated.no longer applicableprotected boolean
isLocked()
Tests if the connection is locked.boolean
isOpen()
Tests if the connection is open.boolean
Returns true if the connection is established via a proxy, false otherwise.boolean
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
Deprecated.boolean
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
Deprecated.Useprint(String, String)
Writes the specified String (as bytes) to the output stream.void
Writes the specified String (as bytes) to the output stream.void
Writes "\r\n".getBytes() to the output stream.void
Deprecated.UseprintLine(String, String)
Writes the specified String (as bytes), followed by "\r\n".getBytes() to the output stream.void
Writes the specified String (as bytes), followed by "\r\n".getBytes() to the output stream.readLine()
Deprecated.use #readLine(String)Reads up to "\n" from the (unchunked) input stream.void
Releases the connection.void
setConnectionTimeout
(int timeout) Deprecated.void
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) AssignsHTTP 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 connectionvoid
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.void
setSocketTimeout
(int timeout) SetsSO_TIMEOUT
value directly on the underlyingsocket
.void
setSoTimeout
(int timeout) Deprecated.void
setStaleCheckingEnabled
(boolean staleCheckEnabled) Deprecated.void
setVirtualHost
(String host) Deprecated.no longer applicablevoid
Deprecated.unusedvoid
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
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.
-
Field Details
-
isOpen
protected boolean isOpenWhether or not the connection is connected.
-
-
Constructor Details
-
HttpConnection
Creates a new HTTP connection for the given host and port.- Parameters:
host
- the host to connect toport
- the port to connect to
-
HttpConnection
Creates a new HTTP connection for the given host and port using the given protocol.- Parameters:
host
- the host to connect toport
- the port to connect toprotocol
- the protocol to use
-
HttpConnection
Creates a new HTTP connection for the given host with the virtual alias and port using given protocol.- Parameters:
host
- the host to connect tovirtualHost
- the virtual host requests will be sent toport
- the port to connect toprotocol
- the protocol to use
-
HttpConnection
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 viaproxyPort
- the port to proxy viahost
- the host to connect toport
- the port to connect to
-
HttpConnection
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) Deprecated.use #HttpConnection(String, int, String, int, 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 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.
-
HttpConnection
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 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 Details
-
getSocket
Returns the connection socket.- Returns:
- the socket.
- Since:
- 3.0
-
getHost
Returns the host.- Returns:
- the host.
-
setHost
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
Deprecated.no longer applicableReturns the target virtual host.- Returns:
- the virtual host.
-
setVirtualHost
Deprecated.no longer applicableSets 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
Sets the port to connect to.- Parameters:
port
- the port to connect to- Throws:
IllegalStateException
- if the connection is already open
-
getProxyHost
Returns the proxy host.- Returns:
- the proxy host.
-
setProxyHost
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
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
Returns the protocol used to establish the connection.- Returns:
- The protocol
-
setProtocol
Sets the protocol used to establish the connection- Parameters:
protocol
- The protocol to use.- Throws:
IllegalStateException
- if the connection is already open
-
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
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()Tests if the connection is open.- Returns:
true
if the connection is open
-
closeIfStale
Closes the connection if stale.- Returns:
true
if the connection was stale and therefore closed,false
otherwise.- Throws:
IOException
- Since:
- 3.0
- See Also:
-
isStaleCheckingEnabled
public boolean isStaleCheckingEnabled()Deprecated.Tests if stale checking is enabled.- Returns:
true
if enabled- See Also:
-
setStaleCheckingEnabled
public void setStaleCheckingEnabled(boolean staleCheckEnabled) Deprecated.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 tofalse
some method executions will result in IOExceptions and they will have to be retried. -
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
BufferedInputStream
, so although data might be read, what is visible to clients of the connection will not change with this call.</p.- Returns:
- true if the connection is already closed, or a read would fail.
- Throws:
IOException
- if the stale connection test is interrupted.
-
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
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
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(edu.internet2.middleware.grouperClientExt.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.
-
getParams
ReturnsHTTP protocol parameters
associated with this method.- Returns:
- HTTP parameters.
- Since:
- 3.0
-
setParams
AssignsHTTP protocol parameters
for this method.- Since:
- 3.0
- See Also:
-
setSoTimeout
Deprecated.Set theSocket
's timeout, viaSocket.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.IllegalStateException
-
setSocketTimeout
SetsSO_TIMEOUT
value directly on the underlyingsocket
. This method does not change the default read timeout value set viaHttpConnectionParams
.- Parameters:
timeout
- the timeout value- Throws:
SocketException
- - if there is an error in the underlying protocol, such as a TCP error.IllegalStateException
- if not connected- Since:
- 3.0
-
getSoTimeout
Deprecated.Returns theSocket
's timeout, viaSocket.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
- Throws:
SocketException
-
setConnectionTimeout
public void setConnectionTimeout(int timeout) Deprecated.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
Establishes a connection to the specified host and port (via a proxy if specified). The underlying socket is created from theProtocolSocketFactory
.- Throws:
IOException
- if an attempt to establish the connection results in an I/O error.
-
tunnelCreated
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
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
Returns anOutputStream
suitable for writing the request.- Returns:
- a stream to write the request to
- Throws:
IllegalStateException
- if the connection is not openIOException
- if an I/O problem occurs
-
getResponseInputStream
Return aInputStream
suitable for reading the response.- Returns:
- InputStream The response input stream.
- Throws:
IOException
- If an IO problem occursIllegalStateException
- If the connection isn't open.
-
isResponseAvailable
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 occursIllegalStateException
- If the connection isn't open.
-
isResponseAvailable
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 occursIllegalStateException
- If the connection isn't open.
-
write
Writes the specified bytes to the output stream.- Parameters:
data
- the data to be written- Throws:
IllegalStateException
- if not connectedIOException
- if an I/O problem occurs- See Also:
-
write
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:
IllegalStateException
- if not connectedIOException
- if an I/O problem occurs
-
writeLine
Writes the specified bytes, followed by "\r\n".getBytes() to the output stream.- Parameters:
data
- the bytes to be written- Throws:
IllegalStateException
- if the connection is not openIOException
- if an I/O problem occurs
-
writeLine
Writes "\r\n".getBytes() to the output stream.- Throws:
IllegalStateException
- if the connection is not openIOException
- if an I/O problem occurs
-
print
Deprecated.Useprint(String, String)
Writes the specified String (as bytes) to the output stream.- Parameters:
data
- the string to be written- Throws:
IllegalStateException
- if the connection is not openIOException
- if an I/O problem occurs
-
print
Writes the specified String (as bytes) to the output stream.- Parameters:
data
- the string to be writtencharset
- the charset to use for writing the data- Throws:
IllegalStateException
- if the connection is not openIOException
- if an I/O problem occurs- Since:
- 3.0
-
printLine
Deprecated.UseprintLine(String, String)
Writes the specified String (as bytes), followed by "\r\n".getBytes() to the output stream.- Parameters:
data
- the data to be written- Throws:
IllegalStateException
- if the connection is not openIOException
- if an I/O problem occurs
-
printLine
Writes the specified String (as bytes), followed by "\r\n".getBytes() to the output stream.- Parameters:
data
- the data to be writtencharset
- the charset to use for writing the data- Throws:
IllegalStateException
- if the connection is not openIOException
- if an I/O problem occurs- Since:
- 3.0
-
printLine
Writes "\r\n".getBytes() to the output stream.- Throws:
IllegalStateException
- if the connection is not openIOException
- if an I/O problem occurs
-
readLine
Deprecated.use #readLine(String)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 openIOException
- if an I/O problem occurs
-
readLine
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- Returns:
- a line from the response
- Throws:
IllegalStateException
- if the connection is not openIOException
- if an I/O problem occurs- Since:
- 3.0
-
shutdownOutput
public void shutdownOutput()Deprecated.unusedAttempts to shutdown theSocket
's output, via Socket.shutdownOutput() when running on JVM 1.3 or higher. -
close
public void close()Closes the socket and streams. -
getHttpConnectionManager
Returns the httpConnectionManager.- Returns:
- HttpConnectionManager
-
setHttpConnectionManager
Sets the httpConnectionManager.- Parameters:
httpConnectionManager
- The httpConnectionManager to set
-
releaseConnection
public void releaseConnection()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. -
isLocked
protected boolean isLocked()Tests if the connection is locked. Locked connections cannot be released. An attempt to release a locked connection will have no effect.- Returns:
- true if the connection is locked, false otherwise.
- Since:
- 3.0
-
setLocked
protected void setLocked(boolean locked) 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 unlock the connection.- Since:
- 3.0
-
closeSocketAndStreams
protected void closeSocketAndStreams()Closes everything out. -
assertNotOpen
Throws anIllegalStateException
if the connection is already open.- Throws:
IllegalStateException
- if connected
-
assertOpen
Throws anIllegalStateException
if the connection is not open.- Throws:
IllegalStateException
- if not connected
-
getSendBufferSize
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:
-
setSendBufferSize
Deprecated.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:
-