rwaldhoff 01/08/13 17:44:44
Modified: httpclient/src/java/org/apache/commons/httpclient Tag:
rlwrefactoring HttpConnection.java
Log:
javadoc
Revision Changes Path
No revision
No revision
1.1.2.5 +161 -4
jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/Attic/HttpConnection.java
Index: HttpConnection.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/Attic/HttpConnection.java,v
retrieving revision 1.1.2.4
retrieving revision 1.1.2.5
diff -u -r1.1.2.4 -r1.1.2.5
--- HttpConnection.java 2001/08/13 17:38:56 1.1.2.4
+++ HttpConnection.java 2001/08/14 00:44:43 1.1.2.5
@@ -1,7 +1,7 @@
/*
- * $Header:
/home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/Attic/HttpConnection.java,v
1.1.2.4 2001/08/13 17:38:56 rwaldhoff Exp $
- * $Revision: 1.1.2.4 $
- * $Date: 2001/08/13 17:38:56 $
+ * $Header:
/home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/Attic/HttpConnection.java,v
1.1.2.5 2001/08/14 00:44:43 rwaldhoff Exp $
+ * $Revision: 1.1.2.5 $
+ * $Date: 2001/08/14 00:44:43 $
* ====================================================================
* Copyright (C) The Apache Software Foundation. All rights reserved.
*
@@ -24,25 +24,54 @@
/**
+ * An abstraction of an HTTP {@link InputStream} and {@link OutputStream}
+ * pair, together with the relevant attributes.
+ *
* @author Rod Waldhoff
- * @version $Id: HttpConnection.java,v 1.1.2.4 2001/08/13 17:38:56 rwaldhoff Exp $
+ * @version $Id: HttpConnection.java,v 1.1.2.5 2001/08/14 00:44:43 rwaldhoff Exp $
*/
public class HttpConnection {
// ----------------------------------------------------------- Constructors
+ /**
+ * Constructor.
+ * @param host the host I should connect to
+ * @param port the port I should connect to
+ */
public HttpConnection(String host, int port) {
this(null,-1,host,port,false);
}
+ /**
+ * Constructor.
+ * @param host the host I should connect to
+ * @param port the port I should connect to
+ * @param secure when <tt>true</tt>, connect via HTTPS (SSL)
+ */
public HttpConnection(String host, int port, boolean secure) {
this(null,-1,host,port,secure);
}
+ /**
+ * Constructor.
+ * @param proxyHost the host I should proxy via
+ * @param proxyPort the port I should proxy via
+ * @param host the host I should connect to
+ * @param port the port I should connect to
+ */
public HttpConnection(String proxyHost, int proxyPort, String host, int port) {
this(proxyHost,proxyPort,host,port,false);
}
+ /**
+ * Fully-specified constructor.
+ * @param proxyHost the host I should proxy via
+ * @param proxyPort the port I should proxy via
+ * @param host the host I should connect to
+ * @param port the port I should connect to
+ * @param secure when <tt>true</tt>, connect via HTTPS (SSL)
+ */
public HttpConnection(String proxyHost, int proxyPort, String host, int port,
boolean secure) {
log.debug("HttpConnection <init>");
_proxyHost = proxyHost;
@@ -54,24 +83,46 @@
// ------------------------------------------ Attribute Setters and Getters
+ /**
+ * Return my host.
+ * @return my host.
+ */
public String getHost() {
return _host;
}
+ /**
+ * Set my host.
+ * @param the host I should connect to
+ * @throws IllegalStateException if I am already connected
+ */
public void setHost(String host) {
assertNotOpen();
_host = host;
}
+ /**
+ * Return my port.
+ * @return my port.
+ */
public int getPort() {
return _port;
}
+ /**
+ * Set my port.
+ * @param the port I should connect to
+ * @throws IllegalStateException if I am already connected
+ */
public void setPort(int port) {
assertNotOpen();
_port = port;
}
+ /**
+ * Return my proxy host.
+ * @return my proxy host.
+ */
public String getProxyHost() {
return _proxyHost;
}
@@ -81,6 +132,10 @@
_proxyHost = host;
}
+ /**
+ * Return my proxy port.
+ * @return my proxy port.
+ */
public int getProxyPort() {
return _proxyPort;
}
@@ -90,6 +145,12 @@
_proxyPort = port;
}
+ /**
+ * Return <tt>true</tt> if I will (or I am) connected over a
+ * secure (HTTPS/SSL) protocol.
+ * @return <tt>true</tt> if I will (or I am) connected over a
+ * secure (HTTPS/SSL) protocol.
+ */
public boolean isSecure() {
return _ssl;
}
@@ -99,32 +160,63 @@
_ssl = secure;
}
+ /**
+ * Return <tt>true</tt> if I am connected,
+ * <tt>false</tt> otherwise.
+ * @return <tt>true</tt> if I am connected
+ */
public boolean isOpen() {
return _open;
}
+ /**
+ * Return my {@link ConnectionInterceptor}, or <tt>null</tt>.
+ * @return my {@link ConnectionInterceptor}, or <tt>null</tt>.
+ */
public ConnectionInterceptor getConnectionInterceptor() {
return _connectionInterceptor;
}
+ /**
+ * Set my {@link ConnectionInterceptor}.
+ * @param intercept the interceptor
+ */
public void setConnectionInterceptor(ConnectionInterceptor intercept) {
_connectionInterceptor = intercept;
}
+ /**
+ * Return my {@link StreamInterceptor}, or <tt>null</tt>.
+ * @return my {@link StreamInterceptor}, or <tt>null</tt>.
+ */
public StreamInterceptor getStreamInterceptor() {
return _streamInterceptor;
}
+ /**
+ * Set my {@link StreamInterceptor}.
+ * @param intercept the interceptor
+ */
public void setStreamInterceptor(StreamInterceptor intercept) {
_streamInterceptor = intercept;
}
+ /**
+ * Return <tt>true</tt> if I am (or I will be)
+ * connected via a proxy, <tt>false</tt> otherwise.
+ * @return <tt>true</tt> if I am (or I will be)
+ * connected via a proxy, <tt>false</tt> otherwise.
+ */
public boolean isProxied() {
return (!(null == _proxyHost || 0 >= _proxyPort));
}
// --------------------------------------------------- Other Public Methods
+ /**
+ * Open this connection to the current host and port
+ * (via a proxy if so configured).
+ */
public void open() throws IOException {
log.debug("HttpConnection.open()");
assertNotOpen(); // ??? is this worth doing?
@@ -161,16 +253,41 @@
}
}
+ /**
+ * Return a {@link RequestOutputStream}
+ * suitable for writing (possibly chunked)
+ * bytes to my {@link OutputStream}.
+ *
+ * @throws IllegalStateException if I am not connected
+ */
public RequestOutputStream getRequestOutputStream() {
+ assertOpen();
RequestOutputStream out = new RequestOutputStream(_output);
out.setInterceptor(_streamInterceptor);
return out;
}
+ /**
+ * Return a {@link ResponseInputStream}
+ * suitable for reading (possibly chunked)
+ * bytes from my {@link InputStream}.
+ * <p>
+ * If the given {@link HttpMethod} contains
+ * a <tt>Transfer-Encoding: chunked</tt> header,
+ * the returned stream will be configured
+ * to read chunked bytes.
+ *
+ * @throws IllegalStateException if I am not connected
+ */
public ResponseInputStream getResponseInputStream(HttpMethod method) {
+ assertOpen();
return new ResponseInputStream(_input,method);
}
+ /**
+ * Write the specified bytes to my output stream.
+ * @throws IllegalStateException if I am not connected
+ */
public void write(byte[] data) throws IOException {
log.debug("HttpConnection.write(byte[])");
assertOpen();
@@ -190,6 +307,12 @@
}
}
+
+ /**
+ * Write the specified bytes, followed by
+ * <tt>"\r\n".getBytes()</tt> to my output stream.
+ * @throws IllegalStateException if I am not connected
+ */
public void writeLine(byte[] data) throws IOException {
log.debug("HttpConnection.writeLine(byte[])");
assertOpen();
@@ -203,6 +326,10 @@
writeLine();
}
+ /**
+ * Write <tt>"\r\n".getBytes()</tt> to my output stream.
+ * @throws IllegalStateException if I am not connected
+ */
public void writeLine() throws IOException {
log.debug("HttpConnection.writeLine()");
wireLog.info(">> \\r\\n");
@@ -212,18 +339,35 @@
}
}
+ /**
+ * Write the specified String (as bytes) to my output stream.
+ * @throws IllegalStateException if I am not connected
+ */
public void print(String data) throws IOException {
write(data.getBytes());
}
+ /**
+ * Write the specified String (as bytes), followed by
+ * <tt>"\r\n".getBytes()</tt> to my output stream.
+ * @throws IllegalStateException if I am not connected
+ */
public void printLine(String data) throws IOException {
writeLine(data.getBytes());
}
+ /**
+ * Write <tt>"\r\n".getBytes()</tt> to my output stream.
+ * @throws IllegalStateException if I am not connected
+ */
public void printLine() throws IOException {
writeLine();
}
+ /**
+ * Read up to <tt>"\r\n"</tt> from my (unchunked) input stream.
+ * @throws IllegalStateException if I am not connected
+ */
public String readLine() throws IOException {
log.debug("HttpConnection.readLine()");
assertOpen();
@@ -256,6 +400,10 @@
return (buf.toString());
}
+ /**
+ * Shutdown my {@link Socket}'s output, via
+ * {@link Socket#shutdownOutput}.
+ */
public void shutdownOutput() {
log.debug("HttpConnection.shutdownOutput()");
try {
@@ -273,6 +421,9 @@
// close output stream?
}
+ /**
+ * Close my socket and streams.
+ */
public void close() throws IOException {
log.debug("HttpConnection.close()");
closeSocketAndStreams();
@@ -313,12 +464,18 @@
_open = false;
}
+ /**
+ * Throw an {@link IllegalStateException} if I am connected.
+ */
protected void assertNotOpen() throws IllegalStateException {
if(_open) {
throw new IllegalStateException("Connection is open");
}
}
+ /**
+ * Throw an {@link IllegalStateException} if I am not connected.
+ */
protected void assertOpen() throws IllegalStateException {
if(!_open) {
throw new IllegalStateException("Connection is not open");
