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:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]">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:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>