commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jsde...@apache.org
Subject cvs commit: jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie CookiePolicy.java CookieSpec.java CookieSpecBase.java NetscapeDraftSpec.java RFC2109Spec.java
Date Mon, 09 Dec 2002 12:48:40 GMT
jsdever     2002/12/09 04:48:40

  Modified:    httpclient/src/java/org/apache/commons/httpclient/cookie
                        CookiePolicy.java CookieSpec.java
                        CookieSpecBase.java NetscapeDraftSpec.java
                        RFC2109Spec.java
  Log:
  Cookie javadoc improvements.
  
  Contributed by: Oleg Kalnichevski
  
  Revision  Changes    Path
  1.2       +19 -23    jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie/CookiePolicy.java
  
  Index: CookiePolicy.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie/CookiePolicy.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- CookiePolicy.java	8 Dec 2002 06:09:46 -0000	1.1
  +++ CookiePolicy.java	9 Dec 2002 12:48:40 -0000	1.2
  @@ -58,26 +58,20 @@
   package org.apache.commons.httpclient.cookie;
   
   /**
  - * <p>
  - *  Cookie management policy class. The cookie policy provides corresponding cookie 
  + * <p>Cookie management policy class. The cookie policy provides corresponding cookie

    *  management interfrace for a given type or version of cookie. 
  - * </p>
  - * <p>
  - *  RFC 2109 specification is used per default. Other supported specification can be 
  + * <p>RFC 2109 specification is used per default. Other supported specification can
be 
    *  chosen when appropriate or set default when desired
  - * </p>
  - * <p>
  - *  The following specifications are provided:
  - *  <tt>COMPATIBILITY</tt>: compatible with the common cookie management practices

  + * <p>The following specifications are provided:
  + *  <ul>
  + *   <li><tt>COMPATIBILITY</tt>: compatible with the common cookie management
practices 
    *  (even if they are not 100% standards compliant
  - *  <tt>NETSCAPE_DRAFT</tt>: Netscape cookie draft compliant
  - *  <tt>RFC2109</tt>: RFC2109 compliant (default)
  - * </p>
  - * <p>
  - *  Default policy can be set on JVM start-up through the system property 
  - *  "apache.commons.httpclient.cookiespec". Recognized values: 
  - *  COMPATIBILITY, NETSCAPE_DRAFT, RFC2109.
  - * </p>
  + *   <li><tt>NETSCAPE_DRAFT</tt>: Netscape cookie draft compliant
  + *   <li><tt>RFC2109</tt>: RFC2109 compliant (default)
  + *  </ul>
  + * <p>Default policy can be set on JVM start-up through the system property 
  + *  <tt>"apache.commons.httpclient.cookiespec"</tt>. Recognized values: 
  + *  <tt>COMPATIBILITY</tt>, <tt>NETSCAPE_DRAFT</tt>, <tt>RFC2109</tt>.
    * 
    * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
    *
  @@ -124,7 +118,7 @@
       }
   
       /**
  -     * @return default cookie policy (COMPATIBILITY | NETSCAPE_DRAFT | RFC2109)
  +     * @return default cookie policy <tt>(COMPATIBILITY | NETSCAPE_DRAFT | RFC2109)</tt>
        */
       
       public static int getDefaultPolicy()
  @@ -134,7 +128,7 @@
       
   
       /**
  -     * @param new default cookie policy (COMPATIBILITY | NETSCAPE_DRAFT | RFC2109)
  +     * @param new default cookie policy <tt>(COMPATIBILITY | NETSCAPE_DRAFT | RFC2109)</tt>
        */
       
       public static void setDefaultPolicy(int policy)
  @@ -145,7 +139,7 @@
   
       /**
        * @return cookie specification interface for the given policy
  -     * (COMPATIBILITY | NETSCAPE_DRAFT | RFC2109)
  +     * <tt>(COMPATIBILITY | NETSCAPE_DRAFT | RFC2109)</tt>
        */
       
       public static CookieSpec getSpecByPolicy(int policy)
  @@ -179,10 +173,12 @@
        * cookies with the given version 
        * 
        * Supported versions:
  -     * <tt>version 0</tt> corresponds to the NETSCAPE_DRAFT
  -     * <tt>version 1</tt> corresponds to the RFC2109
  -     * Any unsupported cookie version number corresponds to 
  +     * <ul>
  +     *  <li><tt>version 0</tt> corresponds to the NETSCAPE_DRAFT
  +     *  <li><tt>version 1</tt> corresponds to the RFC2109
  +     *  <li>Any unsupported cookie version number corresponds to 
        * the current default cookie specification
  +     * <ul>
        */
       
       public static CookieSpec getSpecByVersion(int ver)
  
  
  
  1.2       +24 -24    jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie/CookieSpec.java
  
  Index: CookieSpec.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie/CookieSpec.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- CookieSpec.java	8 Dec 2002 06:09:46 -0000	1.1
  +++ CookieSpec.java	9 Dec 2002 12:48:40 -0000	1.2
  @@ -61,13 +61,13 @@
   import org.apache.commons.httpclient.Cookie;
   
   /**
  - * <p>
  - * Cookie management specification must define
  - * - rules of parsing "Set-Cookie" header
  - * - rules of validation of parsed cookies
  - * - formatting of "Cookie" header 
  + * <P>Cookie management specification must define
  + * <ul>
  + *   <li> rules of parsing "Set-Cookie" header
  + *   <li> rules of validation of parsed cookies
  + *   <li>  formatting of "Cookie" header 
  + * </ul>
    * for a given host, port and path of origin
  - * </p>
    * 
    * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
    *
  @@ -82,7 +82,7 @@
       public static final char   PATH_DELIM_CHAR = PATH_DELIM.charAt(0);
   
       /**
  -      * Parses the Set-Cookie value into an array of <tt>Cookie</tt>s {@link
Cookie}.
  +      * Parse the <tt>"Set-Cookie"</tt> header value into an array of {@link
Cookie}s.
         *
         * @param host the host from which the <tt>Set-Cookie</tt> value was received
         * @param port the port from which the <tt>Set-Cookie</tt> value was received
  @@ -98,14 +98,14 @@
         throws MalformedCookieException;
   
       /**
  -      * Parses the Set-Cookie header into an array of <tt>Cookie</tt>s {@link
Cookie}.
  +      * Parse the <tt>"Set-Cookie"</tt> {@link Header} into an array of {@link
Cookie}s.
         *
         * @param host the host from which the <tt>Set-Cookie</tt> header was
received
         * @param port the port from which the <tt>Set-Cookie</tt> header was
received
         * @param path the path from which the <tt>Set-Cookie</tt> header was
received
         * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt>
header was received over secure conection
         * @param header the <tt>Set-Cookie</tt> received from the server
  -      * @return an array of <tt>Cookie</tt>s parsed from the Set-Cookie header
  +      * @return an array of <tt>Cookie</tt>s parsed from the <tt>"Set-Cookie"</tt>
header
         * @throws MalformedCookieException if an exception occurs during parsing
         * @throws java.lang.IllegalArgumentException if an input parameter is illegal
         */
  @@ -114,12 +114,12 @@
         throws MalformedCookieException;
   
       /**
  -      * Performs cookie {@link Cookie} validation accoding to the cookie specification
  +      * Perform {@link Cookie} validation accoding to validation rules defined by the cookie
specification
         *
         * @param host the host from which the {@link Cookie} was received
         * @param port the port from which the {@link Cookie} was received
         * @param path the path from which the {@link Cookie} was received
  -      * @param secure <tt>true</tt> when the {@link Cookie} was received over
HTTPS
  +      * @param secure <tt>true</tt> when the {@link Cookie} was received using
a secure connection
         * @throws MalformedCookieException if an exception occurs during validation
         * @throws java.lang.IllegalArgumentException if an input parameter is illegal
         */
  @@ -131,17 +131,17 @@
        * Return <tt>true</tt> if the cookie should be submitted with a request
with
        * given attributes, <tt>false</tt> otherwise.
        * @param host the host to which the request is being submitted
  -     * @param port the port to which the request is being submitted (currenlty ignored)
  +     * @param port the port to which the request is being submitted
        * @param path the path to which the request is being submitted
        * @param secure <tt>true</tt> if the request is using a secure connection
  -     * @param cookie to be matched
  +     * @param {@link Cookie} to be matched
        * @return true if the cookie matches the criterium
        */
   
       public boolean match(String host, int port, String path, boolean secure, final Cookie
cookie);
   
       /**
  -     * Returns an array of <tt>Cookie</tt>s that should be submitted with a
request with
  +     * Return an array of {@link Cookie}s that should be submitted with a request with
        * given attributes, <tt>false</tt> otherwise.
        * @param host the host to which the request is being submitted
        * @param port the port to which the request is being submitted (currenlty ignored)
  @@ -154,17 +154,17 @@
       public Cookie[] match(String host, int port, String path, boolean secure, final Cookie
cookies[]);
   
       /**
  -     * Return a string suitable for sending in a Cookie header
  -     * @param cookie {@link Cookie} to be formatted as string
  -     * @return a string suitable for sending in a Cookie header.
  +     * Return a string suitable for sending in a <tt>"Cookie"</tt> header
  +     * @param a {@link Cookie} to be formatted as string
  +     * @return a string suitable for sending in a <tt>"Cookie"</tt> header.
        */
   
       public String formatCookie(Cookie cookie);
   
       /**
  -     * Creates a <tt>Cookie</tt> header value containing all cookies in <i>cookies</i>
  -     * suitable for sending in a Cookie header
  -     * @param an array of <tt>Cookie</tt>s to be formatted
  +     * Create a <tt>"Cookie"</tt> header value containing all {@link Cookie}s
in <i>cookies</i>
  +     * suitable for sending in a <tt>"Cookie"</tt> header
  +     * @param an array of {@link Cookie}s to be formatted
        * @return a string suitable for sending in a Cookie header.
        * @throws java.lang.IllegalArgumentException if an input parameter is illegal
        */
  @@ -172,16 +172,16 @@
       public String formatCookies(Cookie[] cookies);
       
       /**
  -     * Creates a <tt>Cookie</tt> header containing all cookies in <i>cookies</i>,
  -     * @param an array of <tt>Cookie</tt>s to be formatted as a <tt>Cookie</tt>
header
  -     * @return a Cookie header.
  +     * Create a <tt>"Cookie"</tt> {@link Header} containing all {@link Cookie}s
in <i>cookies</i>.
  +     * @param an array of {@link Cookie}s to be formatted as a <tt>"Cookie"</tt>
header
  +     * @return a <tt>"Cookie"</tt> {@link Header}.
        * @throws java.lang.IllegalArgumentException if an input parameter is illegal
        */
   
       public Header formatCookieHeader(Cookie[] cookies);
   
       /**
  -     * Creates a <tt>Cookie</tt> header containing the <i>cookie</i>,
  +     * Create a <tt>"Cookie"</tt> {@link Header} containing the {@link Cookie}.
        * @param <tt>Cookie</tt>s to be formatted as a <tt>Cookie</tt>
header
        * @return a Cookie header.
        * @throws java.lang.IllegalArgumentException if an input parameter is illegal
  
  
  
  1.2       +21 -21    jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie/CookieSpecBase.java
  
  Index: CookieSpecBase.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie/CookieSpecBase.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- CookieSpecBase.java	8 Dec 2002 06:09:46 -0000	1.1
  +++ CookieSpecBase.java	9 Dec 2002 12:48:40 -0000	1.2
  @@ -76,9 +76,8 @@
   import org.apache.commons.logging.LogFactory;
   
   /**
  - * <p>
  - * Cookie management functions shared by all specifications
  - * </p>
  + * 
  + * Cookie management functions shared by all specification.
    *
    * @author  B.C. Holmes
    * @author <a href="mailto:jericho@thinkfree.com">Park, Sung-Gu</a>
  @@ -319,8 +318,7 @@
   
   
       /**
  -      * Parses the Set-Cookie {@link Header} into an array of
  -      * <tt>Cookie</tt>s.
  +      * Parse the <tt>"Set-Cookie"</tt> {@link Header} into an array of {@link
Cookie}s.
         *
         * <P>The syntax for the Set-Cookie response header is:
         *
  @@ -343,7 +341,7 @@
         * @param path the path from which the <tt>Set-Cookie</tt> header was
received
         * @param secure <tt>true</tt> when the <tt>Set-Cookie</tt>
header was received over secure conection
         * @param header the <tt>Set-Cookie</tt> received from the server
  -      * @return an array of <tt>Cookie</tt>s parsed from the Set-Cookie header
  +      * @return an array of <tt>Cookie</tt>s parsed from the <tt>"Set-Cookie"</tt>
header
         * @throws MalformedCookieException if an exception occurs during parsing
         * @throws java.lang.IllegalArgumentException if an input parameter is illegal
         */
  @@ -360,12 +358,12 @@
   
       
       /**
  -      * Performs most fundamental cookie {@link Cookie} validation
  +      * Performs most common {@link Cookie} validation
         *
         * @param host the host from which the {@link Cookie} was received
         * @param port the port from which the {@link Cookie} was received
         * @param path the path from which the {@link Cookie} was received
  -      * @param secure <tt>true</tt> when the {@link Cookie} was received over
HTTPS
  +      * @param secure <tt>true</tt> when the {@link Cookie} was received using
a secure connection
         * @throws MalformedCookieException if an exception occurs during validation
         * @throws java.lang.IllegalArgumentException if an input parameter is illegal
         */
  @@ -434,9 +432,11 @@
        * Return <tt>true</tt> if the cookie should be submitted with a request
with
        * given attributes, <tt>false</tt> otherwise.
        * @param host the host to which the request is being submitted
  -     * @param port the port to which the request is being submitted (currenlty ignored)
  +     * @param port the port to which the request is being submitted (ignored)
        * @param path the path to which the request is being submitted
  -     * @param secure <tt>true</tt> if the request is using a secure protocol
  +     * @param secure <tt>true</tt> if the request is using a secure connection
  +     * @param {@link Cookie} to be matched
  +     * @return true if the cookie matches the criterium
        */
   
       public boolean match(String host, int port, String path, boolean secure, final Cookie
cookie) 
  @@ -511,7 +511,7 @@
   
   
       /**
  -     * Returns an array of <tt>Cookie</tt>s that should be submitted with a
request with
  +     * Return an array of {@link Cookie}s that should be submitted with a request with
        * given attributes, <tt>false</tt> otherwise.
        * @param host the host to which the request is being submitted
        * @param port the port to which the request is being submitted (currenlty ignored)
  @@ -590,9 +590,9 @@
       }
   
       /**
  -     * Return a string suitable for sending in a Cookie header
  -     * @param cookie {@link Cookie} to be formatted as string
  -     * @return a string suitable for sending in a Cookie header.
  +     * Return a string suitable for sending in a <tt>"Cookie"</tt> header
  +     * @param a {@link Cookie} to be formatted as string
  +     * @return a string suitable for sending in a <tt>"Cookie"</tt> header.
        */
   
       public String formatCookie(Cookie cookie)
  @@ -608,9 +608,9 @@
       }
   
       /**
  -     * Creates a <tt>Cookie</tt> header value containing all cookies in <i>cookies</i>
  -     * suitable for sending in a Cookie header
  -     * @param an array of <tt>Cookie</tt>s to be formatted
  +     * Create a <tt>"Cookie"</tt> header value containing all {@link Cookie}s
in <i>cookies</i>
  +     * suitable for sending in a <tt>"Cookie"</tt> header
  +     * @param an array of {@link Cookie}s to be formatted
        * @return a string suitable for sending in a Cookie header.
        * @throws java.lang.IllegalArgumentException if an input parameter is illegal
        */
  @@ -642,9 +642,9 @@
   
   
       /**
  -     * Creates a <tt>Cookie</tt> header containing all cookies in <i>cookies</i>,
  -     * @param an array of <tt>Cookie</tt>s to be formatted as a <tt>Cookie</tt>
header
  -     * @return a Cookie header.
  +     * Create a <tt>"Cookie"</tt> {@link Header} containing all {@link Cookie}s
in <i>cookies</i>.
  +     * @param an array of {@link Cookie}s to be formatted as a <tt>"Cookie"</tt>
header
  +     * @return a <tt>"Cookie"</tt> {@link Header}.
        * @throws java.lang.IllegalArgumentException if an input parameter is illegal
        */
   
  @@ -656,7 +656,7 @@
   
   
       /**
  -     * Creates a <tt>Cookie</tt> header containing the <i>cookie</i>,
  +     * Create a <tt>"Cookie"</tt> {@link Header} containing the {@link Cookie}.
        * @param <tt>Cookie</tt>s to be formatted as a <tt>Cookie</tt>
header
        * @return a Cookie header.
        * @throws java.lang.IllegalArgumentException if an input parameter is illegal
  
  
  
  1.2       +3 -5      jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie/NetscapeDraftSpec.java
  
  Index: NetscapeDraftSpec.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie/NetscapeDraftSpec.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- NetscapeDraftSpec.java	8 Dec 2002 06:09:46 -0000	1.1
  +++ NetscapeDraftSpec.java	9 Dec 2002 12:48:40 -0000	1.2
  @@ -61,9 +61,7 @@
   import org.apache.commons.httpclient.Cookie;
   
   /**
  - * <p>
  - * Netscape draft specific cookie management functions
  - * </p>
  + * <P>Netscape cookie draft specific cookie management functions
    *
    * @author  B.C. Holmes
    * @author <a href="mailto:jericho@thinkfree.com">Park, Sung-Gu</a>
  @@ -90,12 +88,12 @@
   
   
       /**
  -      * Performs Netscape draft spesific cookie {@link Cookie} validation
  +      * Performs Netscape draft compliant {@link Cookie} validation
         *
         * @param host the host from which the {@link Cookie} was received
         * @param port the port from which the {@link Cookie} was received
         * @param path the path from which the {@link Cookie} was received
  -      * @param secure <tt>true</tt> when the {@link Cookie} was received over
HTTPS
  +      * @param secure <tt>true</tt> when the {@link Cookie} was received using
a secure connection
         * @throws MalformedCookieException if an exception occurs during validation
         * @throws java.lang.IllegalArgumentException if an input parameter is illegal
         */
  
  
  
  1.2       +18 -10    jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie/RFC2109Spec.java
  
  Index: RFC2109Spec.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie/RFC2109Spec.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- RFC2109Spec.java	8 Dec 2002 06:09:46 -0000	1.1
  +++ RFC2109Spec.java	9 Dec 2002 12:48:40 -0000	1.2
  @@ -61,9 +61,7 @@
   import org.apache.commons.httpclient.Cookie;
   
   /**
  - * <p>
  - * RFC 2109 specific cookie management functions
  - * </p>
  + * <p>RFC 2109 specific cookie management functions
    *
    * @author  B.C. Holmes
    * @author <a href="mailto:jericho@thinkfree.com">Park, Sung-Gu</a>
  @@ -88,6 +86,16 @@
           super();
       }
   
  +    /**
  +      * Performs RFC 2109 compliant {@link Cookie} validation
  +      *
  +      * @param host the host from which the {@link Cookie} was received
  +      * @param port the port from which the {@link Cookie} was received
  +      * @param path the path from which the {@link Cookie} was received
  +      * @param secure <tt>true</tt> when the {@link Cookie} was received using
a secure connection
  +      * @throws MalformedCookieException if an exception occurs during validation
  +      * @throws java.lang.IllegalArgumentException if an input parameter is illegal
  +      */
   
       public void validate(String host, int port, String path, boolean secure, final Cookie
cookie) throws MalformedCookieException
       {
  @@ -120,9 +128,9 @@
   
   
       /**
  -     * Return a string suitable for sending in a Cookie header
  -     * @param cookie {@link Cookie} to be formatted as string
  -     * @return a string suitable for sending in a Cookie header.
  +     * Return a string suitable for sending in a <tt>"Cookie"</tt> header as
defined in RFC 2109
  +     * @param a {@link Cookie} to be formatted as string
  +     * @return a string suitable for sending in a <tt>"Cookie"</tt> header.
        */
   
       public String formatCookie(Cookie cookie)
  @@ -152,9 +160,9 @@
   
   
       /**
  -     * Creates a RFC 2109 compliant <tt>Cookie</tt> header value containing
all cookies 
  -     * in <i>cookies</i> suitable for sending in a Cookie header
  -     * @param an array of <tt>Cookie</tt>s to be formatted
  +     * Create a RFC 2109 compliant <tt>"Cookie"</tt> header value containing
all 
  +     * {@link Cookie}s in <i>cookies</i> suitable for sending in a <tt>"Cookie"</tt>
header
  +     * @param an array of {@link Cookie}s to be formatted
        * @return a string suitable for sending in a Cookie header.
        * @throws java.lang.IllegalArgumentException if an input parameter is illegal
        */
  @@ -183,7 +191,7 @@
       
       
       /**
  -     * Creates a <tt>Cookie</tt> header containing the <i>cookie</i>,
  +     * Create a RFC 2109 compliant <tt>"Cookie"</tt> {@link Header} containing
the {@link Cookie}.
        * @param <tt>Cookie</tt>s to be formatted as a <tt>Cookie</tt>
header
        * @return a Cookie header.
        * @throws java.lang.IllegalArgumentException if an input parameter is illegal
  
  
  

--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message