You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by js...@apache.org on 2002/12/09 13:48:40 UTC
cvs commit: jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/cookie CookiePolicy.java CookieSpec.java CookieSpecBase.java NetscapeDraftSpec.java RFC2109Spec.java
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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>