From 3a9cdb4485af52521eb20a143c6462102634ee56 Mon Sep 17 00:00:00 2001 From: Nate Fischer Date: Mon, 1 Feb 2021 18:09:23 -0800 Subject: [PATCH] WebView: clarify CookieManager docs No change to logic, only documentation change. This adds some clarifications to getCookie()/setCookie(): * getCookie() returns multiple cookies, setCookie() accepts only one * This briefly describes getCookie()'s output format because it's fairly simple * This summarizes setCookie()'s input format and provides an example, but directs the reader to the RFC spec for a full description * Minor formatting changes, including editing a javadoc link which doesn't currently render correctly in kotlin docs (for ValueCallback#onReceiveValue) Fixes: 175471135 Test: m offline-sdk-docs -j4 Change-Id: Id9052fa03584caae5ffc92ed1f6c4d2641d900ce --- core/java/android/webkit/CookieManager.java | 40 +++++++++++++++------ 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/core/java/android/webkit/CookieManager.java b/core/java/android/webkit/CookieManager.java index 023d9ff28f41b..20230e770bf5b 100644 --- a/core/java/android/webkit/CookieManager.java +++ b/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, - * path and name will be replaced with the new cookie. The cookie being set - * will be ignored if it is expired. + * Sets a single cookie (key-value pair) for the given URL. Any existing cookie with the same + * host, path and name will be replaced with the new cookie. The cookie being set + * will be ignored if it is expired. To set multiple cookies, your application should invoke + * this method multiple times. + * + *

The {@code value} parameter must follow the format of the {@code Set-Cookie} HTTP + * response header defined by + * RFC6265bis. + * 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. * *

Note: 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, - * path and name will be replaced with the new cookie. The cookie being set - * will be ignored if it is expired. - *

- * This method is asynchronous. - * If a {@link ValueCallback} is provided, - * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current + * Sets a single cookie (key-value pair) for the given URL. Any existing cookie with the same + * host, path and name will be replaced with the new cookie. The cookie being set + * will be ignored if it is expired. To set multiple cookies, your application should invoke + * this method multiple times. + * + *

The {@code value} parameter must follow the format of the {@code Set-Cookie} HTTP + * response header defined by + * RFC6265bis. + * 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. + * + *

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'