You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by ol...@apache.org on 2003/11/01 22:13:56 UTC
cvs commit: jakarta-commons/httpclient/src/java/org/apache/commons/httpclient Cookie.java Header.java HttpConnection.java
olegk 2003/11/01 13:13:56
Modified: httpclient/src/java/org/apache/commons/httpclient Tag:
HTTPCLIENT_2_0_BRANCH 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
No revision
No revision
1.38.2.2 +99 -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.38.2.1
retrieving revision 1.38.2.2
diff -u -r1.38.2.1 -r1.38.2.2
--- Cookie.java 7 Jul 2003 19:11:00 -0000 1.38.2.1
+++ Cookie.java 1 Nov 2003 21:13:56 -0000 1.38.2.2
@@ -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:jericho@thinkfree.com">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 {@link 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 {@link Date}, or <tt>null</tt>
+ * Returns the expiration {@link 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 {@link Date}, or <tt>null</tt>.
+ * @return Expiration {@link 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.
+ * Returns a textual representation of the cookie.
+ *
+ * @return string .
*/
public String toExternalForm() {
return CookiePolicy.getSpecByVersion(
@@ -644,8 +656,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 {@link java.util.Comparator#compare(Object,Object)}
@@ -683,7 +693,7 @@
}
/**
- * Return a {@link String} representation of me.
+ * Return a textual representation of the cookie.
* @see #toExternalForm
*/
public String toString() {
@@ -817,16 +827,16 @@
// ----------------------------------------------------- Instance Variables
- /** My comment. */
+ /** Comment attribute. */
private String cookieComment;
- /** My domain. */
+ /** Domain attribute. */
private String cookieDomain;
- /** My expiration {@link Date}. */
+ /** Expiration {@link Date}. */
private Date cookieExpiryDate;
- /** My path. */
+ /** Path attribute. */
private String cookiePath;
/** My secure flag. */
1.10.2.1 +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.10
retrieving revision 1.10.2.1
diff -u -r1.10 -r1.10.2.1
--- Header.java 28 Jan 2003 04:40:20 -0000 1.10
+++ Header.java 1 Nov 2003 21:13:56 -0000 1.10.2.1
@@ -94,10 +94,9 @@
// --------------------------------------------------------- Public Methods
/**
- * Get a {@link String} representation of me, suitable
- * for use in an HTTP head.
+ * Returns a {@link 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 {@link String} representation of me.
+ * Returns a {@link 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
*/
public HeaderElement[] getValues() throws HttpException {
1.67.2.6 +132 -120 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.67.2.5
retrieving revision 1.67.2.6
diff -u -r1.67.2.5 -r1.67.2.6
--- HttpConnection.java 28 Oct 2003 01:56:10 -0000 1.67.2.5
+++ HttpConnection.java 1 Nov 2003 21:13:56 -0000 1.67.2.6
@@ -119,20 +119,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, port, false);
}
/**
- * Constructor.
+ * Creates a new HTTP connection for the given host and port.
+ * If secure attribute is set, use SSL to establish the connection.
*
- * @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 secure when <tt>true</tt>, connect via HTTPS (SSL)
*
* @deprecated use HttpConnection(String, int, Protocol)
@@ -145,10 +146,11 @@
}
/**
- * 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) {
@@ -156,11 +158,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) {
@@ -168,12 +171,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,
@@ -184,12 +188,14 @@
}
/**
- * Fully-specified constructor.
+ * Creates a new HTTP connection for the given host and port via
+ * the given proxy host and port. If secure attribute is set,
+ * use SSL to establish the connection.
*
* @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 port the port I should connect to
+ * @param host the host to connect to. Parameter value must be non-null.
+ * @param port the port to connect to
* @param secure when <tt>true</tt>, connect via HTTPS (SSL)
*
* @deprecated use HttpConnection(String, int, String, int, Protocol)
@@ -208,7 +214,7 @@
}
/**
- * Creates a new HttpConnection.
+ * Creates a new HTTP connection for the given host configuration.
*
* @param hostConfiguration the host/proxy/protocol to use
*/
@@ -223,13 +229,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(
@@ -258,19 +266,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) {
@@ -281,22 +289,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();
@@ -304,12 +313,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) {
@@ -320,10 +329,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();
@@ -331,19 +341,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();
@@ -351,19 +362,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();
@@ -371,29 +383,30 @@
}
/**
- * 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;
}
/**
- * Set whether or not I should connect over HTTPS (SSL).
+ * Defines whether the connection should be established over a
+ * secure protocol.
*
- * @param secure whether or not I should connect over HTTPS (SSL).
- * @throws IllegalStateException if I am already connected
+ * @param secure whether or not to connect over a secure protocol.
+ *
+ * @throws IllegalStateException if the connection is already open
*
* @deprecated use setProtocol(Protocol)
*
@@ -407,9 +420,11 @@
}
/**
- * Sets the protocol used by this connection.
+ * Sets the protocol used to establish the connection
*
- * @param protocol The new protocol.
+ * @param protocol The protocol to use.
+ *
+ * @throws IllegalStateException if the connection is already open
*/
public void setProtocol(Protocol protocol) {
assertNotOpen();
@@ -444,10 +459,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 && isStaleCheckingEnabled() && isStale()) {
@@ -543,11 +558,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));
@@ -587,7 +602,7 @@
// --------------------------------------------------- Other Public Methods
/**
- * Set my {@link Socket}'s timeout, via {@link Socket#setSoTimeout}. If the
+ * Sets the {@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.
* <p>
@@ -596,7 +611,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
*/
public void setSoTimeout(int timeout)
throws SocketException, IllegalStateException {
@@ -608,7 +622,7 @@
}
/**
- * Return my {@link Socket}'s timeout, via {@link Socket#setSoTimeout}, if the
+ * Returns the {@link Socket}'s timeout, via {@link Socket#getSoTimeout}, if the
* connection is already open. If no connection is open, return the value subsequent
* connection will use.
* <p>
@@ -636,16 +650,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 {@link 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) {
@@ -723,14 +738,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()");
@@ -785,10 +800,9 @@
}
/**
- * Return a {@link OutputStream} suitable for writing (possibly
- * chunked) bytes to my {@link OutputStream}.
+ * Returns an {@link 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
*/
@@ -804,12 +818,11 @@
}
/**
- * Return a {@link OutputStream} suitable for writing (possibly
- * chunked) bytes to my {@link OutputStream}.
+ * Returns an {@link OutputStream} suitable for writing the request.
*
* @param useChunking when <tt>true</tt> the chunked transfer-encoding will
* be used
- * @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
* @deprecated Use new ChunkedOutputStream(httpConnecion.getRequestOutputStream());
@@ -826,8 +839,7 @@
}
/**
- * Return a {@link InputStream} suitable for reading (possibly
- * chunked) bytes from my {@link InputStream}.
+ * Return a {@link InputStream} suitable for reading the response.
* <p>
* If the given {@link HttpMethod} contains
* a <tt>Transfer-Encoding: chunked</tt> header,
@@ -835,7 +847,7 @@
* to read chunked bytes.
*
* @param method This argument is ignored.
- * @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 read the response from
* @deprecated Use getResponseInputStream() instead.
@@ -847,7 +859,7 @@
}
/**
- * Return the response input stream
+ * Return a {@link 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.
@@ -863,7 +875,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
@@ -923,7 +935,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
@@ -938,8 +950,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
@@ -984,12 +996,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)
@@ -1000,11 +1012,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()
@@ -1014,12 +1026,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)
@@ -1029,13 +1041,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)
@@ -1045,11 +1057,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()
@@ -1059,11 +1071,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
*/
@@ -1075,7 +1087,7 @@
}
/**
- * Shutdown my {@link Socket}'s output, via Socket.shutdownOutput()
+ * Attempts to shutdown the {@link Socket}'s output, via Socket.shutdownOutput()
* when running on JVM 1.3 or higher.
*/
public void shutdownOutput() {
@@ -1098,7 +1110,7 @@
}
/**
- * Close my socket and streams.
+ * Closes the socket and streams.
*/
public void close() {
LOG.trace("enter HttpConnection.close()");
@@ -1137,7 +1149,7 @@
// ------------------------------------------------------ Protected Methods
/**
- * Close everything out.
+ * Closes everything out.
*/
protected void closeSocketAndStreams() {
LOG.trace("enter HttpConnection.closeSockedAndStreams()");
@@ -1184,7 +1196,7 @@
}
/**
- * Throw an {@link IllegalStateException} if I am connected.
+ * Throws an {@link IllegalStateException} if the connection is already open.
*
* @throws IllegalStateException if connected
*/
@@ -1195,7 +1207,7 @@
}
/**
- * Throw an {@link IllegalStateException} if I am not connected.
+ * Throws an {@link IllegalStateException} if the connection is not open.
*
* @throws IllegalStateException if not connected
*/
@@ -1412,7 +1424,7 @@
/** An {@link 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 +1439,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;
/** Whether or not isStale() is used by isOpen() */
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org