Merge "Merge "WebView: clarify CookieManager docs" am: 5844882671 am: d2243be46a" into rvc-qpr-dev-plus-aosp

core/java/android/webkit/CookieManager.java

@@ -98,9 +98,17 @@ public abstract class CookieManager {
     public abstract boolean acceptThirdPartyCookies(WebView webview);
 
     /**
-     * Sets a cookie for the given URL. Any existing cookie with the same host,
+     * Sets a single cookie (key-value pair) for the given URL. Any existing cookie with the same
-     * path and name will be replaced with the new cookie. The cookie being set
+     * host, path and name will be replaced with the new cookie. The cookie being set
-     * will be ignored if it is expired.
+     * will be ignored if it is expired. To set multiple cookies, your application should invoke
+     * this method multiple times.
+     *
+     * <p>The {@code value} parameter must follow the format of the {@code Set-Cookie} HTTP
+     * response header defined by
+     * <a href="https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03">RFC6265bis</a>.
+     * This is a key-value pair of the form {@code "key=value"}, optionally followed by a list of
+     * cookie attributes delimited with semicolons (ex. {@code "key=value; Max-Age=123"}). Please
+     * consult the RFC specification for a list of valid attributes.
      *
      * <p class="note"><b>Note:</b> if specifying a {@code value} containing the {@code "Secure"}
      * attribute, {@code url} must use the {@code "https://"} scheme.
@@ -112,13 +120,20 @@ public abstract class CookieManager {
     public abstract void setCookie(String url, String value);
 
     /**
-     * Sets a cookie for the given URL. Any existing cookie with the same host,
+     * Sets a single cookie (key-value pair) for the given URL. Any existing cookie with the same
-     * path and name will be replaced with the new cookie. The cookie being set
+     * host, path and name will be replaced with the new cookie. The cookie being set
-     * will be ignored if it is expired.
+     * will be ignored if it is expired. To set multiple cookies, your application should invoke
-     * <p>
+     * this method multiple times.
-     * This method is asynchronous.
+     *
-     * If a {@link ValueCallback} is provided,
+     * <p>The {@code value} parameter must follow the format of the {@code Set-Cookie} HTTP
-     * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current
+     * response header defined by
+     * <a href="https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03">RFC6265bis</a>.
+     * This is a key-value pair of the form {@code "key=value"}, optionally followed by a list of
+     * cookie attributes delimited with semicolons (ex. {@code "key=value; Max-Age=123"}). Please
+     * consult the RFC specification for a list of valid attributes.
+     *
+     * <p>This method is asynchronous. If a {@link ValueCallback} is provided,
+     * {@link ValueCallback#onReceiveValue} will be called on the current
      * thread's {@link android.os.Looper} once the operation is complete.
      * The value provided to the callback indicates whether the cookie was set successfully.
      * You can pass {@code null} as the callback if you don't need to know when the operation
@@ -137,7 +152,10 @@ public abstract class CookieManager {
             callback);
 
     /**
-     * Gets the cookies for the given URL.
+     * Gets all the cookies for the given URL. This may return multiple key-value pairs if multiple
+     * cookies are associated with this URL, in which case each cookie will be delimited by {@code
+     * "; "} characters (semicolon followed by a space). Each key-value pair will be of the form
+     * {@code "key=value"}.
      *
      * @param url the URL for which the cookies are requested
      * @return value the cookies as a string, using the format of the 'Cookie'