CookieManager.java revision 514c5ef8d5774d8820ed1bf90fe53af1606cf106
1/* 2 * Copyright (C) 2006 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.webkit; 18 19import android.annotation.SystemApi; 20import android.net.WebAddress; 21 22/** 23 * Manages the cookies used by an application's {@link WebView} instances. 24 * Cookies are manipulated according to RFC2109. 25 */ 26public abstract class CookieManager { 27 28 @Override 29 protected Object clone() throws CloneNotSupportedException { 30 throw new CloneNotSupportedException("doesn't implement Cloneable"); 31 } 32 33 /** 34 * Gets the singleton CookieManager instance. 35 * 36 * @return the singleton CookieManager instance 37 */ 38 public static synchronized CookieManager getInstance() { 39 return WebViewFactory.getProvider().getCookieManager(); 40 } 41 42 /** 43 * Sets whether the application's {@link WebView} instances should send and 44 * accept cookies. 45 * By default this is set to true and the WebView accepts cookies. 46 * <p> 47 * When this is true 48 * {@link CookieManager#setAcceptThirdPartyCookies setAcceptThirdPartyCookies} and 49 * {@link CookieManager#setAcceptFileSchemeCookies setAcceptFileSchemeCookies} 50 * can be used to control the policy for those specific types of cookie. 51 * 52 * @param accept whether {@link WebView} instances should send and accept 53 * cookies 54 */ 55 public abstract void setAcceptCookie(boolean accept); 56 57 /** 58 * Gets whether the application's {@link WebView} instances send and accept 59 * cookies. 60 * 61 * @return true if {@link WebView} instances send and accept cookies 62 */ 63 public abstract boolean acceptCookie(); 64 65 /** 66 * Sets whether the {@link WebView} should allow third party cookies to be set. 67 * Allowing third party cookies is a per WebView policy and can be set 68 * differently on different WebView instances. 69 * <p> 70 * Apps that target {@link android.os.Build.VERSION_CODES#KITKAT} or below 71 * default to allowing third party cookies. Apps targeting 72 * {@link android.os.Build.VERSION_CODES#LOLLIPOP} or later default to disallowing 73 * third party cookies. 74 * 75 * @param webview the {@link WebView} instance to set the cookie policy on 76 * @param accept whether the {@link WebView} instance should accept 77 * third party cookies 78 */ 79 public abstract void setAcceptThirdPartyCookies(WebView webview, boolean accept); 80 81 /** 82 * Gets whether the {@link WebView} should allow third party cookies to be set. 83 * 84 * @param webview the {@link WebView} instance to get the cookie policy for 85 * @return true if the {@link WebView} accepts third party cookies 86 */ 87 public abstract boolean acceptThirdPartyCookies(WebView webview); 88 89 /** 90 * Sets a cookie for the given URL. Any existing cookie with the same host, 91 * path and name will be replaced with the new cookie. The cookie being set 92 * will be ignored if it is expired. 93 * 94 * @param url the URL for which the cookie is to be set 95 * @param value the cookie as a string, using the format of the 'Set-Cookie' 96 * HTTP response header 97 */ 98 public abstract void setCookie(String url, String value); 99 100 /** 101 * Sets a cookie for the given URL. Any existing cookie with the same host, 102 * path and name will be replaced with the new cookie. The cookie being set 103 * will be ignored if it is expired. 104 * <p> 105 * This method is asynchronous. 106 * If a {@link ValueCallback} is provided, 107 * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current 108 * thread's {@link android.os.Looper} once the operation is complete. 109 * The value provided to the callback indicates whether the cookie was set successfully. 110 * You can pass {@code null} as the callback if you don't need to know when the operation 111 * completes or whether it succeeded, and in this case it is safe to call the method from a 112 * thread without a Looper. 113 * 114 * @param url the URL for which the cookie is to be set 115 * @param value the cookie as a string, using the format of the 'Set-Cookie' 116 * HTTP response header 117 * @param callback a callback to be executed when the cookie has been set 118 */ 119 public abstract void setCookie(String url, String value, ValueCallback<Boolean> callback); 120 121 /** 122 * Gets the cookies for the given URL. 123 * 124 * @param url the URL for which the cookies are requested 125 * @return value the cookies as a string, using the format of the 'Cookie' 126 * HTTP request header 127 */ 128 public abstract String getCookie(String url); 129 130 /** 131 * See {@link #getCookie(String)}. 132 * 133 * @param url the URL for which the cookies are requested 134 * @param privateBrowsing whether to use the private browsing cookie jar 135 * @return value the cookies as a string, using the format of the 'Cookie' 136 * HTTP request header 137 * @hide Used by Browser and by WebViewProvider implementations. 138 */ 139 @SystemApi 140 public abstract String getCookie(String url, boolean privateBrowsing); 141 142 /** 143 * Gets cookie(s) for a given uri so that it can be set to "cookie:" in http 144 * request header. 145 * 146 * @param uri the WebAddress for which the cookies are requested 147 * @return value the cookies as a string, using the format of the 'Cookie' 148 * HTTP request header 149 * @hide Used by RequestHandle and by WebViewProvider implementations. 150 */ 151 @SystemApi 152 public synchronized String getCookie(WebAddress uri) { 153 return getCookie(uri.toString()); 154 } 155 156 /** 157 * Removes all session cookies, which are cookies without an expiration 158 * date. 159 * @deprecated use {@link #removeSessionCookies(ValueCallback)} instead. 160 */ 161 @Deprecated 162 public abstract void removeSessionCookie(); 163 164 /** 165 * Removes all session cookies, which are cookies without an expiration 166 * date. 167 * <p> 168 * This method is asynchronous. 169 * If a {@link ValueCallback} is provided, 170 * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current 171 * thread's {@link android.os.Looper} once the operation is complete. 172 * The value provided to the callback indicates whether any cookies were removed. 173 * You can pass {@code null} as the callback if you don't need to know when the operation 174 * completes or whether any cookie were removed, and in this case it is safe to call the 175 * method from a thread without a Looper. 176 * @param callback a callback which is executed when the session cookies have been removed 177 */ 178 public abstract void removeSessionCookies(ValueCallback<Boolean> callback); 179 180 /** 181 * Removes all cookies. 182 * @deprecated Use {@link #removeAllCookies(ValueCallback)} instead. 183 */ 184 @Deprecated 185 public abstract void removeAllCookie(); 186 187 /** 188 * Removes all cookies. 189 * <p> 190 * This method is asynchronous. 191 * If a {@link ValueCallback} is provided, 192 * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current 193 * thread's {@link android.os.Looper} once the operation is complete. 194 * The value provided to the callback indicates whether any cookies were removed. 195 * You can pass {@code null} as the callback if you don't need to know when the operation 196 * completes or whether any cookies were removed, and in this case it is safe to call the 197 * method from a thread without a Looper. 198 * @param callback a callback which is executed when the cookies have been removed 199 */ 200 public abstract void removeAllCookies(ValueCallback<Boolean> callback); 201 202 /** 203 * Gets whether there are stored cookies. 204 * 205 * @return true if there are stored cookies 206 */ 207 public abstract boolean hasCookies(); 208 209 /** 210 * See {@link #hasCookies()}. 211 * 212 * @param privateBrowsing whether to use the private browsing cookie jar 213 * @hide Used by Browser and WebViewProvider implementations. 214 */ 215 @SystemApi 216 public abstract boolean hasCookies(boolean privateBrowsing); 217 218 /** 219 * Removes all expired cookies. 220 * @deprecated The WebView handles removing expired cookies automatically. 221 */ 222 @Deprecated 223 public abstract void removeExpiredCookie(); 224 225 /** 226 * Ensures all cookies currently accessible through the getCookie API are 227 * written to persistent storage. 228 * This call will block the caller until it is done and may perform I/O. 229 */ 230 public abstract void flush(); 231 232 /** 233 * Gets whether the application's {@link WebView} instances send and accept 234 * cookies for file scheme URLs. 235 * 236 * @return true if {@link WebView} instances send and accept cookies for 237 * file scheme URLs 238 */ 239 // Static for backward compatibility. 240 public static boolean allowFileSchemeCookies() { 241 return getInstance().allowFileSchemeCookiesImpl(); 242 } 243 244 /** 245 * Implements {@link #allowFileSchemeCookies()}. 246 * 247 * @hide Only for use by WebViewProvider implementations 248 */ 249 @SystemApi 250 protected abstract boolean allowFileSchemeCookiesImpl(); 251 252 /** 253 * Sets whether the application's {@link WebView} instances should send and 254 * accept cookies for file scheme URLs. 255 * Use of cookies with file scheme URLs is potentially insecure and turned 256 * off by default. 257 * Do not use this feature unless you can be sure that no unintentional 258 * sharing of cookie data can take place. 259 * <p> 260 * Note that calls to this method will have no effect if made after a 261 * {@link WebView} or CookieManager instance has been created. 262 */ 263 // Static for backward compatibility. 264 public static void setAcceptFileSchemeCookies(boolean accept) { 265 getInstance().setAcceptFileSchemeCookiesImpl(accept); 266 } 267 268 /** 269 * Implements {@link #setAcceptFileSchemeCookies(boolean)}. 270 * 271 * @hide Only for use by WebViewProvider implementations 272 */ 273 @SystemApi 274 protected abstract void setAcceptFileSchemeCookiesImpl(boolean accept); 275} 276