commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject cvs commit: jakarta-commons/httpclient/src/java/org/apache/commons/httpclient Cookie.java Header.java HttpConnection.java
Date Sat, 01 Nov 2003 21:13:56 GMT
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


Mime
View raw message