olegk 2003/11/01 13:17:25
Modified: httpclient/src/java/org/apache/commons/httpclient
Cookie.java Header.java HttpConnection.java
Log:
Javadoc cleanup
java/org/apache/commons/httpclient/Cookie.java
java/org/apache/commons/httpclient/Header.java
java/org/apache/commons/httpclient/HttpConnection.java
Contributed by Oleg Kalnichevski
Revision Changes Path
1.41 +102 -89
jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/Cookie.java
Index: Cookie.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/Cookie.java,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -r1.40 -r1.41
--- Cookie.java 20 Oct 2003 22:17:11 -0000 1.40
+++ Cookie.java 1 Nov 2003 21:17:25 -0000 1.41
@@ -76,7 +76,11 @@
/**
- * <p>An HTTP "magic-cookie", as specified in RFC 2109.</p>
+ * <p>
+ * HTTP "magic-cookie" represents a piece of state information
+ * that the HTTP agent and the target server can exchange to maintain
+ * a session.
+ * </p>
*
* @author B.C. Holmes
* @author <a href="mailto:[EMAIL PROTECTED]">Park, Sung-Gu</a>
@@ -97,9 +101,7 @@
// ----------------------------------------------------------- Constructors
/**
- * Create a cookie. Default constructor
- *
- * The new cookie is assigned
+ * Default constructor. Creates a blank cookie
*/
public Cookie() {
@@ -107,28 +109,32 @@
}
/**
- * Create a cookie.
+ * Creates a cookie with the given name, value and domain attribute.
*
* @param name the cookie name
* @param value the cookie value
- * @param domain the host this cookie will be sent to
+ * @param domain the domain this cookie can be sent to
*/
public Cookie(String domain, String name, String value) {
this(domain, name, value, null, null, false);
}
/**
- * Create a cookie.
+ * Creates a cookie with the given name, value, domain attribute,
+ * path attribute, expiration attribute, and secure attribute
*
* @param name the cookie name
* @param value the cookie value
- * @param domain the host this cookie will be sent to
- * @param path the path prefix for which this cookie will be sent
+ * @param domain the domain this cookie can be sent to
+ * @param path the path prefix for which this cookie can be sent
* @param expires the [EMAIL PROTECTED] Date} at which this cookie expires,
* or <tt>null</tt> if the cookie expires at the end
* of the session
- * @param secure if true this cookie will only be sent over secure
+ * @param secure if true this cookie can only be sent over secure
* connections
+ * @throws IllegalArgumentException If cookie name is null or blank,
+ * cookie name contains a blank, or cookie name starts with character $
+ *
*/
public Cookie(String domain, String name, String value,
String path, Date expires, boolean secure) {
@@ -154,16 +160,17 @@
}
/**
- * Create a cookie.
+ * Creates a cookie with the given name, value, domain attribute,
+ * path attribute, maximum age attribute, and secure attribute
*
* @param name the cookie name
* @param value the cookie value
- * @param domain the host this cookie will be sent to
- * @param path the path prefix for which this cookie will be sent
+ * @param domain the domain this cookie can be sent to
+ * @param path the path prefix for which this cookie can be sent
* @param maxAge the number of seconds for which this cookie is valid.
* maxAge is expected to be a non-negative number.
* <tt>-1</tt> signifies that the cookie should never expire.
- * @param secure if <tt>true</tt> this cookie will only be sent over secure
+ * @param secure if <tt>true</tt> this cookie can only be sent over secure
* connections
*/
public Cookie(String domain, String name, String value, String path,
@@ -181,6 +188,8 @@
/**
* Returns the comment describing the purpose of this cookie, or
* <tt>null</tt> if no such comment has been defined.
+ *
+ * @return comment
*
* @see #setComment(String)
*/
@@ -191,7 +200,9 @@
/**
* If a user agent (web browser) presents this cookie to a user, the
* cookie's purpose will be described using this comment.
- *
+ *
+ * @param comment
+ *
* @see #getComment()
*/
public void setComment(String comment) {
@@ -199,12 +210,12 @@
}
/**
- * Returns my expiration [EMAIL PROTECTED] Date}, or <tt>null</tt>
+ * Returns the expiration [EMAIL PROTECTED] Date} of the cookie, or
<tt>null</tt>
* if none exists.
* <p><strong>Note:</strong> the object returned by this method is
* considered immutable. Changing it (e.g. using setTime()) could result
* in undefined behaviour. Do so at your peril. </p>
- * @return my expiration [EMAIL PROTECTED] Date}, or <tt>null</tt>.
+ * @return Expiration [EMAIL PROTECTED] Date}, or <tt>null</tt>.
*
* @see #setExpiryDate(java.util.Date)
*
@@ -214,18 +225,7 @@
}
/**
- * Expiration setter.
- * <p>
- * Netscape's original proposal defined an Expires header that took
- * a date value in a fixed-length variant format in place of Max-Age:
- * <br>
- * <tt>Wdy, DD-Mon-YY HH:MM:SS GMT</tt>
- * <br>
- * Note that the Expires date format contains embedded spaces, and that
- * "old" cookies did not have quotes around values. Clients that
- * implement to this specification should be aware of "old" cookies and
- * Expires.
- * </p>
+ * Sets expiration date.
* <p><strong>Note:</strong> the object returned by this method is considered
* immutable. Changing it (e.g. using setTime()) could result in undefined
* behaviour. Do so at your peril.</p>
@@ -241,10 +241,10 @@
/**
- * Returns <tt>false</tt> if I should be discarded at the end
+ * Returns <tt>false</tt> if the cookie should be discarded at the end
* of the "session"; <tt>true</tt> otherwise.
*
- * @return <tt>false</tt> if I should be discarded at the end
+ * @return <tt>false</tt> if the cookie should be discarded at the end
* of the "session"; <tt>true</tt> otherwise
*/
public boolean isPersistent() {
@@ -253,7 +253,9 @@
/**
- * Returns my domain.
+ * Returns domain attribute of the cookie.
+ *
+ * @return the value of the domain attribute
*
* @see #setDomain(java.lang.String)
*/
@@ -262,14 +264,9 @@
}
/**
- * Sets my domain.
- * <p>
- * I should be presented only to hosts satisfying this domain
- * name pattern. Read RFC 2109 for specific details of the syntax.
- * Briefly, a domain name name begins with a dot (".foo.com") and means
- * that hosts in that DNS zone ("www.foo.com", but not "a.b.foo.com")
- * should see the cookie. By default, cookies are only returned to
- * the host which saved them.
+ * Sets the domain attribute.
+ *
+ * @param domain The value of the domain attribute
*
* @see #getDomain
*/
@@ -285,7 +282,10 @@
/**
- * @return my path.
+ * Returns the path attribute of the cookie
+ *
+ * @return The value of the path attribute.
+ *
* @see #setPath(java.lang.String)
*/
public String getPath() {
@@ -293,12 +293,9 @@
}
/**
- * Sets my path.
- * <p>
- * I should be presented only with requests beginning with this path.
- * See RFC 2109 for a specification of the default behaviour. Basically, URLs
- * in the same "directory" as the one which set the cookie, and in
subdirectories,
- * can all see the cookie unless a different path is set.</p>
+ * Sets the path attribute.
+ *
+ * @param path The value of the path attribute
*
* @see #getPath
*
@@ -316,13 +313,15 @@
}
/**
- * Set my secure flag.
+ * Sets the secure attribute of the cookie.
* <p>
* When <tt>true</tt> the cookie should only be sent
* using a secure protocol (https). This should only be set when
* the cookie's originating server used a secure protocol to set the
* cookie's value.
*
+ * @param secure The value of the secure attribute
+ *
* @see #getSecure()
*/
public void setSecure (boolean secure) {
@@ -330,8 +329,10 @@
}
/**
+ * Returns the version of the cookie specification to which this
+ * cookie conforms.
*
- * @return the version of the HTTP cookie specification that I use.
+ * @return the version of the cookie.
*
* @see #setVersion(int)
*
@@ -341,21 +342,21 @@
}
/**
- * Set the version of the HTTP cookie specification I report.
- * <p>
- * The current implementation only sends version 1 cookies.
- * (See RFC 2109 for details.)</p>
+ * Sets the version of the cookie specification to which this
+ * cookie conforms.
*
+ * @param version the version of the cookie.
+ *
* @see #getVersion
- *
*/
public void setVersion(int version) {
cookieVersion = version;
}
/**
- * Return true if this cookie has expired.
- * @return <tt>true</tt> if I have expired.
+ * Returns true if this cookie has expired.
+ *
+ * @return <tt>true</tt> if the cookie has expired.
*/
public boolean isExpired() {
return (cookieExpiryDate != null
@@ -363,9 +364,11 @@
}
/**
- * Return true if this cookie has expired according to the time passed in.
+ * Returns true if this cookie has expired according to the time passed in.
+ *
* @param now The current time.
- * @return <tt>true</tt> if I have expired.
+ *
+ * @return <tt>true</tt> if the cookie expired.
*/
public boolean isExpired(Date now) {
return (cookieExpiryDate != null
@@ -375,25 +378,29 @@
/**
* Indicates whether the cookie had a path specified in a
- * Path attribute in the set-cookie header. This value
- * is important for generating the cookie header because
- * RFC 2109 sec. 4.3.4 says that the cookie header should only
- * include a $Path attribute if the cookie's path was specified
- * in the set-cookie header.
+ * path attribute of the <tt>Set-Cookie</tt> header. This value
+ * is important for generating the <tt>Cookie</tt> header because
+ * some cookie specifications require that the <tt>Cookie</tt> header
+ * should only include a path attribute if the cookie's path
+ * was specified in the <tt>Set-Cookie</tt> header.
*
+ * @param value <tt>true</tt> if the cookie's path was explicitly
+ * set, <tt>false</tt> otherwise.
+ *
* @see #isPathAttributeSpecified
- * @param value True if the cookie's path came from a Path attribute.
*/
public void setPathAttributeSpecified(boolean value) {
hasPathAttribute = value;
}
/**
- * Returns true if cookie's path was set via a Path attribute in the
- * set-cookie header.
+ * Returns <tt>true</tt> if cookie's path was set via a path attribute
+ * in the <tt>Set-Cookie</tt> header.
*
+ * @return value <tt>true</tt> if the cookie's path was explicitly
+ * set, <tt>false</tt> otherwise.
+ *
* @see #setPathAttributeSpecified
- * @return True if cookie's path was specified in the set-cookie header.
*/
public boolean isPathAttributeSpecified() {
return hasPathAttribute;
@@ -401,25 +408,29 @@
/**
* Indicates whether the cookie had a domain specified in a
- * Domain attribute in the set-cookie header. This value
- * is important for generating the cookie header because
- * RFC 2109 sec. 4.3.4 says that the cookie header should only
- * include a $Domain attribute if the cookie's domain was specified
- * in the set-cookie header.
+ * domain attribute of the <tt>Set-Cookie</tt> header. This value
+ * is important for generating the <tt>Cookie</tt> header because
+ * some cookie specifications require that the <tt>Cookie</tt> header
+ * should only include a domain attribute if the cookie's domain
+ * was specified in the <tt>Set-Cookie</tt> header.
+ *
+ * @param value <tt>true</tt> if the cookie's domain was explicitly
+ * set, <tt>false</tt> otherwise.
*
* @see #isDomainAttributeSpecified
- * @param value True if the cookie's domain came from a Domain attribute.
*/
public void setDomainAttributeSpecified(boolean value) {
hasDomainAttribute = value;
}
/**
- * Returns true if cookie's domain was set via a Domain attribute in the
- * set-cookie header.
+ * Returns <tt>true</tt> if cookie's domain was set via a domain
+ * attribute in the <tt>Set-Cookie</tt> header.
+ *
+ * @return value <tt>true</tt> if the cookie's domain was explicitly
+ * set, <tt>false</tt> otherwise.
*
* @see #setDomainAttributeSpecified
- * @return True if cookie's domain was specified in the set-cookie header.
*/
public boolean isDomainAttributeSpecified() {
return hasDomainAttribute;
@@ -464,8 +475,9 @@
/**
- * Return a string suitable for sending in a Cookie header.
- * @return a string suitable for sending in a Cookie header.
+ * Return a textual representation of the cookie.
+ *
+ * @return string.
*/
public String toExternalForm() {
CookieSpec spec = null;
@@ -483,8 +495,6 @@
* <p>This method is implemented so a cookie can be used as a comparator for
* a SortedSet of cookies. Specifically it's used above in the
* createCookieHeader method.</p>
- * <p>The compare only compares the path of the cookie, see section 4.3.4
- * of RFC2109</p>
* @param o1 The first object to be compared
* @param o2 The second object to be compared
* @return See [EMAIL PROTECTED] java.util.Comparator#compare(Object,Object)}
@@ -522,7 +532,10 @@
}
/**
- * Return a [EMAIL PROTECTED] String} representation of me.
+ * Return a textual representation of the cookie.
+ *
+ * @return string.
+ *
* @see #toExternalForm
*/
public String toString() {
@@ -531,16 +544,16 @@
// ----------------------------------------------------- Instance Variables
- /** My comment. */
+ /** Comment attribute. */
private String cookieComment;
- /** My domain. */
+ /** Domain attribute. */
private String cookieDomain;
- /** My expiration [EMAIL PROTECTED] Date}. */
+ /** Expiration [EMAIL PROTECTED] Date}. */
private Date cookieExpiryDate;
- /** My path. */
+ /** Path attribute. */
private String cookiePath;
/** My secure flag. */
1.12 +9 -11
jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/Header.java
Index: Header.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/Header.java,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- Header.java 13 Jul 2003 13:54:50 -0000 1.11
+++ Header.java 1 Nov 2003 21:17:25 -0000 1.12
@@ -94,10 +94,9 @@
// --------------------------------------------------------- Public Methods
/**
- * Get a [EMAIL PROTECTED] String} representation of me, suitable
- * for use in an HTTP head.
+ * Returns a [EMAIL PROTECTED] String} representation of the header.
*
- * @return string value for a HTTP HEAD
+ * @return stringHEAD
*/
public String toExternalForm() {
return ((null == getName() ? "" : getName())
@@ -107,10 +106,9 @@
}
/**
- * Returns a [EMAIL PROTECTED] String} representation of me.
+ * Returns a [EMAIL PROTECTED] String} representation of the header.
*
- * @see #toExternalForm
- * @return String representation
+ * @return stringHEAD
*/
public String toString() {
return toExternalForm();
@@ -121,7 +119,7 @@
* constructed from my value.
*
* @see HeaderElement#parse
- * @throws HttpException When ? occurs
+ * @throws HttpException if the header cannot be parsed
* @return an array of header elements
*
* @deprecated Use #getElements
1.78 +115 -106
jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpConnection.java
Index: HttpConnection.java
===================================================================
RCS file:
/home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/HttpConnection.java,v
retrieving revision 1.77
retrieving revision 1.78
diff -u -r1.77 -r1.78
--- HttpConnection.java 28 Oct 2003 01:58:17 -0000 1.77
+++ HttpConnection.java 1 Nov 2003 21:17:25 -0000 1.78
@@ -128,20 +128,21 @@
// ----------------------------------------------------------- Constructors
/**
- * Constructor.
+ * Creates a new HTTP connection for the given host and port.
*
- * @param host the host I should connect to
- * @param port the port I should connect to
+ * @param host the host to connect to
+ * @param port the port to connect to
*/
public HttpConnection(String host, int port) {
this(null, -1, host, null, port, Protocol.getProtocol("http"));
}
/**
- * Constructor.
+ * Creates a new HTTP connection for the given host and port
+ * using the given protocol.
*
- * @param host the host I should connect to
- * @param port the port I should connect to
+ * @param host the host to connect to
+ * @param port the port to connect to
* @param protocol the protocol to use
*/
public HttpConnection(String host, int port, Protocol protocol) {
@@ -149,11 +150,12 @@
}
/**
- * Constructor.
+ * Creates a new HTTP connection for the given host with the virtual
+ * alias and port using given protocol.
*
- * @param host the host I should connect to
- * @param virtualHost the virtual host I will be sending requests to
- * @param port the port I should connect to
+ * @param host the host to connect to
+ * @param virtualHost the virtual host requests will be sent to
+ * @param port the port to connect to
* @param protocol the protocol to use
*/
public HttpConnection(String host, String virtualHost, int port, Protocol
protocol) {
@@ -161,12 +163,13 @@
}
/**
- * Constructor.
+ * Creates a new HTTP connection for the given host and port via the
+ * given proxy host and port using the default protocol.
*
- * @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 proxyHost the host to proxy via
+ * @param proxyPort the port to proxy via
+ * @param host the host to connect to
+ * @param port the port to connect to
*/
public HttpConnection(
String proxyHost,
@@ -177,7 +180,7 @@
}
/**
- * Creates a new HttpConnection.
+ * Creates a new HTTP connection for the given host configuration.
*
* @param hostConfiguration the host/proxy/protocol to use
*/
@@ -192,13 +195,15 @@
}
/**
- * Create an instance
- *
- * @param proxyHost the host I should proxy via
- * @param proxyPort the port I should proxy via
- * @param host the host I should connect to. Parameter value must be non-null.
- * @param virtualHost the virtual host I will be sending requests to
- * @param port the port I should connect to
+ * 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.
+ *
+ * @param proxyHost the host to proxy via
+ * @param proxyPort the port to proxy via
+ * @param host the host to connect to. Parameter value must be non-null.
+ * @param virtualHost the virtual host requests will be sent to
+ * @param port the port to connect to
* @param protocol The protocol to use. Parameter value must be non-null.
*/
public HttpConnection(
@@ -227,19 +232,19 @@
// ------------------------------------------ Attribute Setters and Getters
/**
- * Return my host name.
+ * Returns the host.
*
- * @return my host.
+ * @return the host.
*/
public String getHost() {
return hostName;
}
/**
- * Set my host name.
+ * Sets the host to connect to.
*
- * @param host the host I should connect to. Parameter value must be non-null.
- * @throws IllegalStateException if I am already connected
+ * @param host the host to connect to. Parameter value must be non-null.
+ * @throws IllegalStateException if the connection is already open
*/
public void setHost(String host) throws IllegalStateException {
if (host == null) {
@@ -250,22 +255,23 @@
}
/**
- * Return my virtual host name.
+ * Returns the target virtual host.
*
- * @return my virtual host.
+ * @return the virtual host.
*/
public String getVirtualHost() {
return virtualName;
}
/**
- * Set my virtual host name.
+ * Sets the virtual host to target.
*
* @param 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 <tt> null</tt> if virtual host name is not
* to be used
- * @throws IllegalStateException if I am already connected
+ *
+ * @throws IllegalStateException if the connection is already open
*/
public void setVirtualHost(String host) throws IllegalStateException {
assertNotOpen();
@@ -273,12 +279,12 @@
}
/**
- * Return my port.
+ * Returns the port of the host.
*
* If the port is -1 (or less than 0) the default port for
* the current protocol is returned.
*
- * @return my port.
+ * @return the port.
*/
public int getPort() {
if (portNumber < 0) {
@@ -289,10 +295,11 @@
}
/**
- * Set my port.
+ * Sets the port to connect to.
*
- * @param port the port I should connect to
- * @throws IllegalStateException if I am already connected
+ * @param port the port to connect to
+ *
+ * @throws IllegalStateException if the connection is already open
*/
public void setPort(int port) throws IllegalStateException {
assertNotOpen();
@@ -300,19 +307,20 @@
}
/**
- * Return my proxy host.
+ * Returns the proxy host.
*
- * @return my proxy host.
+ * @return the proxy host.
*/
public String getProxyHost() {
return proxyHostName;
}
/**
- * Set the host I should proxy through.
+ * Sets the host to proxy through.
*
- * @param host the host I should proxy through.
- * @throws IllegalStateException if I am already connected
+ * @param host the host to proxy through.
+ *
+ * @throws IllegalStateException if the connection is already open
*/
public void setProxyHost(String host) throws IllegalStateException {
assertNotOpen();
@@ -320,19 +328,20 @@
}
/**
- * Return my proxy port.
+ * Returns the port of the proxy host.
*
- * @return my proxy port.
+ * @return the proxy port.
*/
public int getProxyPort() {
return proxyPortNumber;
}
/**
- * Set the port I should proxy through.
+ * Sets the port of the host to proxy through.
*
- * @param port the host I should proxy through.
- * @throws IllegalStateException if I am already connected
+ * @param port the port of the host to proxy through.
+ *
+ * @throws IllegalStateException if the connection is already open
*/
public void setProxyPort(int port) throws IllegalStateException {
assertNotOpen();
@@ -340,28 +349,29 @@
}
/**
- * Return <tt>true</tt> if I will (or I am) connected over a
- * secure (HTTPS/SSL) protocol.
+ * Returns <tt>true</tt> if the connection is established over
+ * a secure protocol.
*
- * @return <tt>true</tt> if I will (or I am) connected over a
- * secure (HTTPS/SSL) protocol.
+ * @return <tt>true</tt> if connected over a secure protocol.
*/
public boolean isSecure() {
return protocolInUse.isSecure();
}
/**
- * Get the protocol.
- * @return HTTPS if secure, HTTP otherwise
+ * Returns the protocol used to establish the connection.
+ * @return The protocol
*/
public Protocol getProtocol() {
return protocolInUse;
}
/**
- * Sets the protocol used by this connection.
+ * Sets the protocol used to establish the connection
+ *
+ * @param protocol The protocol to use.
*
- * @param protocol The new protocol.
+ * @throws IllegalStateException if the connection is already open
*/
public void setProtocol(Protocol protocol) {
assertNotOpen();
@@ -396,10 +406,10 @@
}
/**
- * Return <tt>true</tt> if I am connected,
+ * Returns <tt>true</tt> if the connection is open,
* <tt>false</tt> otherwise.
*
- * @return <tt>true</tt> if I am connected
+ * @return <tt>true</tt> if the connection is open
*/
public boolean isOpen() {
if (used && this.params.isStaleCheckingEnabled() && isStale()) {
@@ -501,11 +511,11 @@
}
/**
- * Return <tt>true</tt> if I am (or I will be)
- * connected via a proxy, <tt>false</tt> otherwise.
+ * Returns <tt>true</tt> if the connection is established 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.
+ * @return <tt>true</tt> if a proxy is used to establish the connection,
+ * <tt>false</tt> otherwise.
*/
public boolean isProxied() {
return (!(null == proxyHostName || 0 >= proxyPortNumber));
@@ -570,7 +580,7 @@
}
/**
- * Set my [EMAIL PROTECTED] Socket}'s timeout, via [EMAIL PROTECTED]
Socket#setSoTimeout}. If the
+ * Set the [EMAIL PROTECTED] Socket}'s timeout, via [EMAIL PROTECTED]
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.
* <p>
@@ -579,7 +589,6 @@
* @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
*
* @deprecated Use [EMAIL PROTECTED] HttpConnectionParams#setSoTimeout(int)},
* [EMAIL PROTECTED] HttpConnection#getParams()}.
@@ -600,7 +609,7 @@
* @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
+ * @throws IllegalStateException if not connected
*/
public void setSocketTimeout(int timeout)
throws SocketException, IllegalStateException {
@@ -611,7 +620,7 @@
}
/**
- * Return my [EMAIL PROTECTED] Socket}'s timeout, via [EMAIL PROTECTED]
Socket#setSoTimeout}, if the
+ * Returns the [EMAIL PROTECTED] Socket}'s timeout, via [EMAIL PROTECTED]
Socket#getSoTimeout}, if the
* connection is already open. If no connection is open, return the value
subsequent
* connection will use.
* <p>
@@ -640,16 +649,17 @@
}
/**
- * Open this connection to the current host and port
- * (via a proxy if so configured).
+ * Establishes a connection to the specified host and port
+ * (via a proxy if specified).
* The underlying socket is created from the [EMAIL PROTECTED]
ProtocolSocketFactory}.
*
- * @throws IOException when there are errors opening the connection
+ * @throws IOException if an attempt to establish the connection results in an
+ * I/O error.
*/
public void open() throws IOException {
LOG.trace("enter HttpConnection.open()");
- assertNotOpen(); // ??? is this worth doing?
+ assertNotOpen();
try {
if (null == socket) {
@@ -741,14 +751,14 @@
}
/**
- * 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.
+ * 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.
- * @throws IOException if an error occured creating the secure socket
+ * @throws IOException if an attempt to establish the secure tunnel results in
an
+ * I/O error.
*/
public void tunnelCreated() throws IllegalStateException, IOException {
LOG.trace("enter HttpConnection.tunnelCreated()");
@@ -808,10 +818,9 @@
}
/**
- * Return a [EMAIL PROTECTED] OutputStream} suitable for writing (possibly
- * chunked) bytes to my [EMAIL PROTECTED] OutputStream}.
+ * Returns an [EMAIL PROTECTED] OutputStream} suitable for writing the request.
*
- * @throws IllegalStateException if I am not connected
+ * @throws IllegalStateException if the connection is not open
* @throws IOException if an I/O problem occurs
* @return a stream to write the request to
*/
@@ -827,7 +836,7 @@
}
/**
- * Return the response input stream
+ * Return a [EMAIL PROTECTED] InputStream} suitable for reading the response.
* @return InputStream The response input stream.
* @throws IOException If an IO problem occurs
* @throws IllegalStateException If the connection isn't open.
@@ -843,7 +852,7 @@
* Tests if input data avaialble. This method returns immediately
* and does not perform any read operations on the input socket
*
- * @return boolean <tt>true</tt> if input data is availble,
+ * @return boolean <tt>true</tt> if input data is available,
* <tt>false</tt> otherwise.
*
* @throws IOException If an IO problem occurs
@@ -903,7 +912,7 @@
}
/**
- * Write the specified bytes to my output stream.
+ * Writes the specified bytes to the output stream.
*
* @param data the data to be written
* @throws HttpRecoverableException if a SocketException occurs
@@ -918,8 +927,8 @@
}
/**
- * Write <i>length</i> bytes in <i>data</i> starting at
- * <i>offset</i> to my output stream.
+ * Writes <i>length</i> bytes in <i>data</i> starting at
+ * <i>offset</i> to the output stream.
*
* The general contract for
* write(b, off, len) is that some of the bytes in the array b are written
@@ -964,12 +973,12 @@
}
/**
- * Write the specified bytes, followed by <tt>"\r\n".getBytes()</tt> to my
+ * Writes the specified bytes, followed by <tt>"\r\n".getBytes()</tt> to the
* 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 IllegalStateException if the connection is not open
* @throws IOException if an I/O problem occurs
*/
public void writeLine(byte[] data)
@@ -980,11 +989,11 @@
}
/**
- * Write <tt>"\r\n".getBytes()</tt> to my output stream.
+ * Writes <tt>"\r\n".getBytes()</tt> to the output stream.
*
* @throws HttpRecoverableException when socket exceptions occur writing
* data
- * @throws IllegalStateException if I am not connected
+ * @throws IllegalStateException if the connection is not open
* @throws IOException if an I/O problem occurs
*/
public void writeLine()
@@ -994,12 +1003,12 @@
}
/**
- * Write the specified String (as bytes) to my output stream.
+ * Writes the specified String (as bytes) to the 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 IllegalStateException if the connection is not open
* @throws IOException if an I/O problem occurs
*/
public void print(String data)
@@ -1009,13 +1018,13 @@
}
/**
- * Write the specified String (as bytes), followed by
- * <tt>"\r\n".getBytes()</tt> to my output stream.
+ * Writes the specified String (as bytes), followed by
+ * <tt>"\r\n".getBytes()</tt> to the 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 IllegalStateException if the connection is not open
* @throws IOException if an I/O problem occurs
*/
public void printLine(String data)
@@ -1025,11 +1034,11 @@
}
/**
- * Write <tt>"\r\n".getBytes()</tt> to my output stream.
+ * Writes <tt>"\r\n".getBytes()</tt> to the output stream.
*
* @throws HttpRecoverableException when socket exceptions occur writing
* data
- * @throws IllegalStateException if I am not connected
+ * @throws IllegalStateException if the connection is not open
* @throws IOException if an I/O problem occurs
*/
public void printLine()
@@ -1039,11 +1048,11 @@
}
/**
- * Read up to <tt>"\n"</tt> from my (unchunked) input stream.
+ * Reads up to <tt>"\n"</tt> 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.
*
- * @throws IllegalStateException if I am not connected
+ * @throws IllegalStateException if the connection is not open
* @throws IOException if an I/O problem occurs
* @return a line from the response
*/
@@ -1055,7 +1064,7 @@
}
/**
- * Shutdown my [EMAIL PROTECTED] Socket}'s output, via Socket.shutdownOutput()
+ * Attempts to shutdown the [EMAIL PROTECTED] Socket}'s output, via
Socket.shutdownOutput()
* when running on JVM 1.3 or higher.
*/
public void shutdownOutput() {
@@ -1078,7 +1087,7 @@
}
/**
- * Close my socket and streams.
+ * Closes the socket and streams.
*/
public void close() {
LOG.trace("enter HttpConnection.close()");
@@ -1137,7 +1146,7 @@
// ------------------------------------------------------ Protected Methods
/**
- * Close everything out.
+ * Closes everything out.
*/
protected void closeSocketAndStreams() {
LOG.trace("enter HttpConnection.closeSockedAndStreams()");
@@ -1184,7 +1193,7 @@
}
/**
- * Throw an [EMAIL PROTECTED] IllegalStateException} if I am connected.
+ * Throws an [EMAIL PROTECTED] IllegalStateException} if the connection is
already open.
*
* @throws IllegalStateException if connected
*/
@@ -1195,7 +1204,7 @@
}
/**
- * Throw an [EMAIL PROTECTED] IllegalStateException} if I am not connected.
+ * Throws an [EMAIL PROTECTED] IllegalStateException} if the connection is not
open.
*
* @throws IllegalStateException if not connected
*/
@@ -1411,7 +1420,7 @@
/** An [EMAIL PROTECTED] InputStream} for the response to an individual
request. */
private InputStream lastResponseInputStream = null;
- /** Whether or not I am connected. */
+ /** Whether or not the connection is connected. */
protected boolean isOpen = false;
/** the protocol being used */
@@ -1427,7 +1436,7 @@
/** Whether or not the socket is a secure one. */
private boolean usingSecureSocket = false;
- /** Whether I am tunneling a proxy or not */
+ /** Whether the connection is open via a secure tunnel or not */
private boolean tunnelEstablished = false;
/** the connection manager that created this connection or null */
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
