* The following options are set on the socket before getting the input/output * streams in the {@link #open()} method: *
| Socket Method * | Sockets Option * | Configuration * |
|---|---|---|
| {@link java.net.Socket#setTcpNoDelay(boolean)} * | SO_NODELAY * | None * |
| {@link java.net.Socket#setSoTimeout(int)} * | SO_TIMEOUT * | {@link #setConnectionTimeout(int)} * |
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.
* * @param inStream The stream associated with an HttpMethod. */ public void setLastResponseInputStream(InputStream inStream) { lastResponseInputStream = inStream; } /** * 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 {@link 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.
* * @return An {@link InputStream} corresponding to the body of the last * response. */ public InputStream getLastResponseInputStream() { return lastResponseInputStream; } // --------------------------------------------------- Other Public Methods /** * Set my {@link Socket}'s timeout, via {@link 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! * * @param timeout the timeout value * @throws SocketException - if there is an error in the underlying * protocol, such as a TCP error. * @throws IllegalStateException if I am not connected */ public void setSoTimeout(int timeout) throws SocketException, IllegalStateException { LOG.debug("HttpConnection.setSoTimeout(" + timeout + ")"); soTimeout = timeout; if (socket != null) { socket.setSoTimeout(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. * @param timeout The timeout in milliseconds. 0 means timeout is not used. */ public void setConnectionTimeout(int timeout) { this.connectTimeout = timeout; } /** * Open this connection to the current host and port * (via a proxy if so configured). * The underlying socket is created from the {@link ProtocolSocketFactory}. * * @throws IOException when there are errors opening the connection */ public void open() throws IOException { LOG.trace("enter HttpConnection.open()"); assertNotOpen(); // ??? is this worth doing? try { if (null == socket) { final String host = (null == proxyHostName) ? hostName : proxyHostName; final int port = (null == proxyHostName) ? portNumber : proxyPortNumber; usingSecureSocket = isSecure() && !isProxied(); final ProtocolSocketFactory socketFactory = (isSecure() && !isProxied() ? protocolInUse.getSocketFactory() : new DefaultProtocolSocketFactory()); if (connectTimeout == 0) { socket = socketFactory.createSocket(host, port); } else { SocketTask task = new SocketTask() { public void doit() throws IOException { setSocket(socketFactory.createSocket(host, port)); } }; TimeoutController.execute(task, connectTimeout); socket = task.getSocket(); if (task.exception != null) { throw task.exception; } } } /* "Nagling has been broadly implemented across networks, including the Internet, and is generally performed by default - although it is sometimes considered to be undesirable in highly interactive environments, such as some client/server situations. In such cases, nagling may be turned off through use of the TCP_NODELAY sockets option." */ socket.setTcpNoDelay(soNodelay); socket.setSoTimeout(soTimeout); inputStream = socket.getInputStream(); outputStream = socket.getOutputStream(); isOpen = true; } catch (IOException e) { // Connection wasn't opened properly // so close everything out closeSocketAndStreams(); throw e; } catch (TimeoutController.TimeoutException e) { if (LOG.isWarnEnabled()) { LOG.warn( "The host " + hostName + ":" + portNumber + " (or proxy " + proxyHostName + ":" + proxyPortNumber + ") did not accept the connection within timeout of " + connectTimeout + " milliseconds"); } throw new ConnectionTimeoutException(); } } /** * 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 IllegalStateException if connection is not secure and proxied or * if the socket is already secure. * @throws IOException if an error occured creating the secure socket */ public void tunnelCreated() throws IllegalStateException, IOException { LOG.trace("enter HttpConnection.tunnelCreated()"); if (!isSecure() || !isProxied()) { throw new IllegalStateException( "Connection must be secure " + "and proxied to use this feature"); } if (usingSecureSocket) { throw new IllegalStateException("Already using a secure socket"); } SecureProtocolSocketFactory socketFactory = (SecureProtocolSocketFactory) protocolInUse.getSocketFactory(); socket = socketFactory.createSocket(socket, hostName, portNumber, true); inputStream = socket.getInputStream(); outputStream = socket.getOutputStream(); usingSecureSocket = true; tunnelEstablished = true; LOG.debug("Secure tunnel created"); } /** * Indicates if the connection is completely transparent from end to end. * * @return true if conncetion is not proxied or tunneled through a transparent * proxy; false otherwise. */ public boolean isTransparent() { return !isProxied() || tunnelEstablished; } /** * Return a {@link RequestOutputStream} suitable for writing (possibly * chunked) bytes to my {@link OutputStream}. * * @throws IllegalStateException if I am not connected * @throws IOException if an I/O problem occurs * @return a stream to write the request to */ public OutputStream getRequestOutputStream() throws IOException, IllegalStateException { LOG.trace("enter HttpConnection.getRequestOutputStream()"); assertOpen(); return outputStream; } /** * Return a {@link RequestOutputStream} suitable for writing (possibly * chunked) bytes to my {@link OutputStream}. * * @param useChunking when true the chunked transfer-encoding will * be used * @throws IllegalStateException if I am not connected * @throws IOException if an I/O problem occurs * @return a stream to write the request to * @deprecated Use new ChunkedOutputStream(httpConnecion.getRequestOutputStream()); */ public OutputStream getRequestOutputStream(boolean useChunking) throws IOException, IllegalStateException { LOG.trace("enter HttpConnection.getRequestOutputStream(boolean)"); assertOpen(); if (useChunking) { return new ChunkedOutputStream(outputStream); } else { return outputStream; } } /** * Return a {@link ResponseInputStream} suitable for reading (possibly * chunked) bytes from my {@link InputStream}. *
* If the given {@link HttpMethod} contains * a Transfer-Encoding: chunked header, * the returned stream will be configured * to read chunked bytes. * * @param method This argument is ignored. * @throws IllegalStateException if I am not connected * @throws IOException if an I/O problem occurs * @return a stream to read the response from * @deprecated Use getResponseInputStream() instead. */ public InputStream getResponseInputStream(HttpMethod method) throws IOException, IllegalStateException { LOG.trace("enter HttpConnection.getResponseInputStream(HttpMethod)"); return getResponseInputStream(); } /** * Return the response input stream * @return InputStream The response input stream. * @throws IOException If an IO problem occurs * @throws IllegalStateException If the connection isn't open. */ public InputStream getResponseInputStream() throws IOException, IllegalStateException { LOG.trace("enter HttpConnection.getResponseInputStream()"); assertOpen(); return inputStream; } /** * Tests if input data avaialble. * * @return boolean true if input data is availble, * false otherwise. * * @throws IOException If an IO problem occurs * @throws IllegalStateException If the connection isn't open. */ public boolean isResponseAvaliable() throws IOException { LOG.trace("enter HttpConnection.responseAvaliable()"); assertOpen(); return this.inputStream.available() > 0; } /** * Waits for the specified number of milliseconds for input data to become available * * @param timeout_ms Number of milliseconds to wait for input data. * * @return boolean true if input data is availble, * false otherwise. * * @throws IOException If an IO problem occurs * @throws IllegalStateException If the connection isn't open. */ public boolean waitForResponse(long timeout_ms) throws IOException, IllegalStateException { LOG.trace("enter HttpConnection.waitForResponse(int)"); if (timeout_ms < 0) { throw new IllegalArgumentException("Timeout value may not be negative"); } long overtime = System.currentTimeMillis() + timeout_ms; while (System.currentTimeMillis() < overtime) { if (isResponseAvaliable()) { return true; } } LOG.debug("Waiting for response timeout"); return false; } /** * Write the specified bytes to my output stream. * * @param data the data to be written * @throws HttpRecoverableException if a SocketException occurs * @throws IllegalStateException if not connected * @throws IOException if an I/O problem occurs * @see #write(byte[],int,int) */ public void write(byte[] data) throws IOException, IllegalStateException, HttpRecoverableException { LOG.trace("enter HttpConnection.write(byte[])"); this.write(data, 0, data.length); } /** * 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. * * @param data array containing the data to be written. * @param offset the start offset in the data. * @param length the number of bytes to write. * @throws HttpRecoverableException if a SocketException occurs * @throws IllegalStateException if not connected * @throws IOException if an I/O problem occurs */ public void write(byte[] data, int offset, int length) throws IOException, IllegalStateException, HttpRecoverableException { LOG.trace("enter HttpConnection.write(byte[], int, int)"); if (offset + length > data.length) { throw new HttpRecoverableException( "Unable to write:" + " offset=" + offset + " length=" + length + " data.length=" + data.length); } else if (data.length <= 0) { throw new HttpRecoverableException( "Unable to write:" + " data.length=" + data.length); } assertOpen(); if (WIRE_LOG.isDebugEnabled()) { String dataString = new String(data, offset, length, "ISO-8859-1"); WIRE_LOG.debug(">> \"" + dataString + "\" [\\r\\n]"); } try { outputStream.write(data, offset, length); } catch (SocketException se) { LOG.debug( "HttpConnection: Socket exception while writing data", se); throw new HttpRecoverableException(se.toString()); } catch (IOException ioe) { LOG.debug("HttpConnection: Exception while writing data", ioe); throw ioe; } } /** * Write the specified bytes, followed by "\r\n".getBytes() to my * output stream. * * @param data the bytes to be written * @throws HttpRecoverableException when socket exceptions occur writing data * @throws IllegalStateException if I am not connected * @throws IOException if an I/O problem occurs */ public void writeLine(byte[] data) throws IOException, IllegalStateException, HttpRecoverableException { LOG.trace("enter HttpConnection.writeLine(byte[])"); assertOpen(); if (WIRE_LOG.isDebugEnabled() && (data.length > 0)) { String dataString = HttpConstants.getContentString(data); WIRE_LOG.debug(">> \"" + dataString.trim() + "\" [\\r\\n]"); } try { outputStream.write(data); writeLine(); } catch (SocketException se) { LOG.info("SocketException while writing data to output", se); throw new HttpRecoverableException(se.toString()); } catch (IOException ioe) { LOG.info("IOException while writing data to output", ioe); throw ioe; } } /** * Write "\r\n".getBytes() to my output stream. * * @throws HttpRecoverableException when socket exceptions occur writing * data * @throws IllegalStateException if I am not connected * @throws IOException if an I/O problem occurs */ public void writeLine() throws IOException, IllegalStateException, HttpRecoverableException { LOG.trace("enter HttpConnection.writeLine()"); WIRE_LOG.debug(">> [\\r\\n]"); try { outputStream.write(CRLF); } catch (SocketException se) { LOG.warn("HttpConnection: Socket exception while writing data", se); throw new HttpRecoverableException(se.toString()); } catch (IOException ioe) { LOG.warn("HttpConnection: IO exception while writing data", ioe); throw ioe; } } /** * Write the specified String (as bytes) to my output stream. * * @param data the string to be written * @throws HttpRecoverableException when socket exceptions occur writing * data * @throws IllegalStateException if I am not connected * @throws IOException if an I/O problem occurs */ public void print(String data) throws IOException, IllegalStateException, HttpRecoverableException { LOG.trace("enter HttpConnection.print(String)"); write(HttpConstants.getBytes(data)); } /** * Write the specified String (as bytes), followed by * "\r\n".getBytes() to my output stream. * * @param data the data to be written * @throws HttpRecoverableException when socket exceptions occur writing * data * @throws IllegalStateException if I am not connected * @throws IOException if an I/O problem occurs */ public void printLine(String data) throws IOException, IllegalStateException, HttpRecoverableException { LOG.trace("enter HttpConnection.printLine(String)"); writeLine(HttpConstants.getBytes(data)); } /** * Write "\r\n".getBytes() to my output stream. * * @throws HttpRecoverableException when socket exceptions occur writing * data * @throws IllegalStateException if I am not connected * @throws IOException if an I/O problem occurs */ public void printLine() throws IOException, IllegalStateException, HttpRecoverableException { LOG.trace("enter HttpConnection.printLine()"); writeLine(); } /** * Read up to "\r\n" from my (unchunked) input stream. * If the stream ends before the line terminator is found, * the last part of the string will still be returned. * '\r' and '\n' are allowed to appear individually in the stream. * * @throws IllegalStateException if I am not connected * @throws IOException if an I/O problem occurs * @return a line from the response */ public String readLine() throws IOException, IllegalStateException { LOG.trace("enter HttpConnection.readLine()"); assertOpen(); return HttpParser.readLine(inputStream); } /** * Shutdown my {@link Socket}'s output, via {@link Socket#shutdownOutput}. */ public void shutdownOutput() { LOG.trace("enter HttpConnection.shutdownOutput()"); try { // Socket.shutdownOutput is a JDK 1.3 // method. We'll use reflection in case // we're running in an older VM Class[] paramsClasses = new Class[0]; Method shutdownOutput = socket.getClass().getMethod("shutdownOutput", paramsClasses); Object[] params = new Object[0]; shutdownOutput.invoke(socket, params); } catch (Exception ex) { LOG.debug("Unexpected Exception caught", ex); // Ignore, and hope everything goes right } // close output stream? } /** * Close my socket and streams. */ public void close() { LOG.trace("enter HttpConnection.close()"); closeSocketAndStreams(); } /** * Returns the httpConnectionManager. * @return HttpConnectionManager */ public HttpConnectionManager getHttpConnectionManager() { return httpConnectionManager; } /** * Sets the httpConnectionManager. * @param httpConnectionManager The httpConnectionManager to set */ public void setHttpConnectionManager(HttpConnectionManager httpConnectionManager) { this.httpConnectionManager = httpConnectionManager; } /** * Release the connection. */ public void releaseConnection() { LOG.trace("enter HttpConnection.releaseConnection()"); if (httpConnectionManager != null) { httpConnectionManager.releaseConnection(this); } } // ------------------------------------------------------ Protected Methods /** * Close everything out. */ protected void closeSocketAndStreams() { LOG.trace("enter HttpConnection.closeSockedAndStreams()"); // no longer care about previous responses... lastResponseInputStream = null; if (null != inputStream) { try { inputStream.close(); } catch (Exception ex) { LOG.debug("Exception caught when closing input", ex); // ignored } inputStream = null; } if (null != outputStream) { try { outputStream.close(); } catch (Exception ex) { LOG.debug("Exception caught when closing output", ex); // ignored } outputStream = null; } if (null != socket) { try { socket.close(); } catch (Exception ex) { LOG.debug("Exception caught when closing socket", ex); // ignored } socket = null; } isOpen = false; tunnelEstablished = false; usingSecureSocket = false; } /** * Throw an {@link IllegalStateException} if I am connected. * * @throws IllegalStateException if connected */ protected void assertNotOpen() throws IllegalStateException { if (isOpen) { throw new IllegalStateException("Connection is open"); } } /** * Throw an {@link IllegalStateException} if I am not connected. * * @throws IllegalStateException if not connected */ protected void assertOpen() throws IllegalStateException { if (!isOpen) { throw new IllegalStateException("Connection is not open"); } } // -- Timeout Exception /** * Signals that a timeout occured while opening the socket. */ public class ConnectionTimeoutException extends IOException { /** Create an instance */ public ConnectionTimeoutException() { } } /** * Helper class for wrapping socket based tasks. */ private abstract class SocketTask implements Runnable { /** The socket */ private Socket socket; /** The exception */ private IOException exception; /** * Set the socket. * @param newSocket The new socket. */ protected void setSocket(final Socket newSocket) { socket = newSocket; } /** * Return the socket. * @return Socket The socket. */ protected Socket getSocket() { return socket; } /** * Perform the logic. * @throws IOException If an IO problem occurs */ public abstract void doit() throws IOException; /** Execute the logic in this object and keep track of any exceptions. */ public void run() { try { doit(); } catch (IOException e) { exception = e; } } } // ------------------------------------------------------- Static Variable /** "\r\n", as bytes. */ private static final byte[] CRLF = new byte[] {(byte) 13, (byte) 10}; /** Log object for this class. */ private static final Log LOG = LogFactory.getLog(HttpConnection.class); /** Log for any wire messages. */ private static final Log WIRE_LOG = LogFactory.getLog("httpclient.wire"); // ----------------------------------------------------- Instance Variables /** My host. */ private String hostName = null; /** My port. */ private int portNumber = -1; /** My proxy host. */ private String proxyHostName = null; /** My proxy port. */ private int proxyPortNumber = -1; /** My client Socket. */ private Socket socket = null; /** My InputStream. */ private InputStream inputStream = null; /** My OutputStream. */ private OutputStream outputStream = null; /** An {@link InputStream} for the response to an individual request. */ private InputStream lastResponseInputStream = null; /** Whether or not I am connected. */ private boolean isOpen = false; /** the protocol being used */ private Protocol protocolInUse; /** SO_TIMEOUT socket value */ private int soTimeout = 0; /** TCP_NODELAY socket value */ private boolean soNodelay = true; /** Whether or not the _socket is a secure one. Note the difference to _ssl */ private boolean usingSecureSocket = false; /** Whether I am tunneling a proxy or not */ private boolean tunnelEstablished = false; /** Timeout until connection established (Socket created). 0 means no timeout. */ private int connectTimeout = 0; /** the connection manager that created this connection or null */ private HttpConnectionManager httpConnectionManager; }