CookieManager.java revision 955d8d69ea6caabce1461dc25b339b9bf9dc61a6
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.net.WebAddress; 20 21/** 22 * Manages the cookies used by an application's {@link WebView} instances. 23 * Cookies are manipulated according to RFC2109. 24 */ 25public class CookieManager { 26 /** 27 * @hide Only for use by WebViewProvider implementations 28 */ 29 protected CookieManager() { 30 } 31 32 @Override 33 protected Object clone() throws CloneNotSupportedException { 34 throw new CloneNotSupportedException("doesn't implement Cloneable"); 35 } 36 37 /** 38 * Gets the singleton CookieManager instance. If this method is used 39 * before the application instantiates a {@link WebView} instance, 40 * {@link CookieSyncManager#createInstance CookieSyncManager.createInstance(Context)} 41 * must be called first. 42 * 43 * @return the singleton CookieManager instance 44 */ 45 public static synchronized CookieManager getInstance() { 46 return WebViewFactory.getProvider().getCookieManager(); 47 } 48 49 /** 50 * Sets whether the application's {@link WebView} instances should send and 51 * accept cookies. 52 * By default this is set to true and the WebView accepts cookies. 53 * <p> 54 * When this is true 55 * {@link CookieManager#setAcceptThirdPartyCookies setAcceptThirdPartyCookies} and 56 * {@link CookieManager#setAcceptFileSchemeCookies setAcceptFileSchemeCookies} 57 * can be used to control the policy for those specific types of cookie. 58 * 59 * @param accept whether {@link WebView} instances should send and accept 60 * cookies 61 */ 62 public synchronized void setAcceptCookie(boolean accept) { 63 throw new MustOverrideException(); 64 } 65 66 /** 67 * Gets whether the application's {@link WebView} instances send and accept 68 * cookies. 69 * 70 * @return true if {@link WebView} instances send and accept cookies 71 */ 72 public synchronized boolean acceptCookie() { 73 throw new MustOverrideException(); 74 } 75 76 /** 77 * Sets whether the {@link WebView} should allow third party cookies to be set. 78 * Allowing third party cookies is a per WebView policy and can be set 79 * differently on different WebView instances. 80 * <p> 81 * Apps that target {@link android.os.Build.VERSION_CODES#KITKAT} or below 82 * default to allowing third party cookies. Apps targeting 83 * {@link android.os.Build.VERSION_CODES#LOLLIPOP} or later default to disallowing 84 * third party cookies. 85 * 86 * @param webview the {@link WebView} instance to set the cookie policy on 87 * @param accept whether the {@link WebView} instance should accept 88 * third party cookies 89 */ 90 public void setAcceptThirdPartyCookies(WebView webview, boolean accept) { 91 throw new MustOverrideException(); 92 } 93 94 /** 95 * Gets whether the {@link WebView} should allow third party cookies to be set. 96 * 97 * @param webview the {@link WebView} instance to get the cookie policy for 98 * @return true if the {@link WebView} accepts third party cookies 99 */ 100 public boolean acceptThirdPartyCookies(WebView webview) { 101 throw new MustOverrideException(); 102 } 103 104 /** 105 * Sets a cookie for the given URL. Any existing cookie with the same host, 106 * path and name will be replaced with the new cookie. The cookie being set 107 * will be ignored if it is expired. 108 * 109 * @param url the URL for which the cookie is to be set 110 * @param value the cookie as a string, using the format of the 'Set-Cookie' 111 * HTTP response header 112 */ 113 public void setCookie(String url, String value) { 114 throw new MustOverrideException(); 115 } 116 117 /** 118 * Sets a cookie for the given URL. Any existing cookie with the same host, 119 * path and name will be replaced with the new cookie. The cookie being set 120 * will be ignored if it is expired. 121 * <p> 122 * This method is asynchronous. 123 * If a {@link ValueCallback} is provided, 124 * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current 125 * thread's {@link android.os.Looper} once the operation is complete. 126 * The value provided to the callback indicates whether the cookie was set successfully. 127 * You can pass {@code null} as the callback if you don't need to know when the operation 128 * completes or whether it succeeded, and in this case it is safe to call the method from a 129 * thread without a Looper. 130 * 131 * @param url the URL for which the cookie is to be set 132 * @param value the cookie as a string, using the format of the 'Set-Cookie' 133 * HTTP response header 134 * @param callback a callback to be executed when the cookie has been set 135 */ 136 public void setCookie(String url, String value, ValueCallback<Boolean> callback) { 137 throw new MustOverrideException(); 138 } 139 140 /** 141 * Gets the cookies for the given URL. 142 * 143 * @param url the URL for which the cookies are requested 144 * @return value the cookies as a string, using the format of the 'Cookie' 145 * HTTP request header 146 */ 147 public String getCookie(String url) { 148 throw new MustOverrideException(); 149 } 150 151 /** 152 * See {@link #getCookie(String)}. 153 * 154 * @param url the URL for which the cookies are requested 155 * @param privateBrowsing whether to use the private browsing cookie jar 156 * @return value the cookies as a string, using the format of the 'Cookie' 157 * HTTP request header 158 * @hide Used by Browser, no intention to publish. 159 */ 160 public String getCookie(String url, boolean privateBrowsing) { 161 throw new MustOverrideException(); 162 } 163 164 /** 165 * Gets cookie(s) for a given uri so that it can be set to "cookie:" in http 166 * request header. 167 * 168 * @param uri the WebAddress for which the cookies are requested 169 * @return value the cookies as a string, using the format of the 'Cookie' 170 * HTTP request header 171 * @hide Used by RequestHandle, no intention to publish. 172 */ 173 public synchronized String getCookie(WebAddress uri) { 174 throw new MustOverrideException(); 175 } 176 177 /** 178 * Removes all session cookies, which are cookies without an expiration 179 * date. 180 * @deprecated use {@link #removeSessionCookies(ValueCallback)} instead. 181 */ 182 public void removeSessionCookie() { 183 throw new MustOverrideException(); 184 } 185 186 /** 187 * Removes all session cookies, which are cookies without an expiration 188 * date. 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 cookie 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 session cookies have been removed 199 */ 200 public void removeSessionCookies(ValueCallback<Boolean> callback) { 201 throw new MustOverrideException(); 202 } 203 204 /** 205 * Removes all cookies. 206 * @deprecated Use {@link #removeAllCookies(ValueCallback)} instead. 207 */ 208 @Deprecated 209 public void removeAllCookie() { 210 throw new MustOverrideException(); 211 } 212 213 /** 214 * Removes all cookies. 215 * <p> 216 * This method is asynchronous. 217 * If a {@link ValueCallback} is provided, 218 * {@link ValueCallback#onReceiveValue(T) onReceiveValue()} will be called on the current 219 * thread's {@link android.os.Looper} once the operation is complete. 220 * The value provided to the callback indicates whether any cookies were removed. 221 * You can pass {@code null} as the callback if you don't need to know when the operation 222 * completes or whether any cookies were removed, and in this case it is safe to call the 223 * method from a thread without a Looper. 224 * @param callback a callback which is executed when the cookies have been removed 225 */ 226 public void removeAllCookies(ValueCallback<Boolean> callback) { 227 throw new MustOverrideException(); 228 } 229 230 /** 231 * Gets whether there are stored cookies. 232 * 233 * @return true if there are stored cookies 234 */ 235 public synchronized boolean hasCookies() { 236 throw new MustOverrideException(); 237 } 238 239 /** 240 * See {@link #hasCookies()}. 241 * 242 * @param privateBrowsing whether to use the private browsing cookie jar 243 * @hide Used by Browser, no intention to publish. 244 */ 245 public synchronized boolean hasCookies(boolean privateBrowsing) { 246 throw new MustOverrideException(); 247 } 248 249 /** 250 * Removes all expired cookies. 251 * @deprecated The WebView handles removing expired cookies automatically. 252 */ 253 @Deprecated 254 public void removeExpiredCookie() { 255 throw new MustOverrideException(); 256 } 257 258 /** 259 * Ensures all cookies currently accessible through the getCookie API are 260 * written to persistent storage. 261 * This call will block the caller until it is done and may perform I/O. 262 */ 263 public void flush() { 264 flushCookieStore(); 265 } 266 267 /** 268 * Flushes all cookies managed by the Chrome HTTP stack to flash. 269 * 270 * @hide Package level api, called from CookieSyncManager 271 */ 272 protected void flushCookieStore() { 273 } 274 275 /** 276 * Gets whether the application's {@link WebView} instances send and accept 277 * cookies for file scheme URLs. 278 * 279 * @return true if {@link WebView} instances send and accept cookies for 280 * file scheme URLs 281 */ 282 // Static for backward compatibility. 283 public static boolean allowFileSchemeCookies() { 284 return getInstance().allowFileSchemeCookiesImpl(); 285 } 286 287 /** 288 * Implements {@link #allowFileSchemeCookies()}. 289 * 290 * @hide Only for use by WebViewProvider implementations 291 */ 292 protected boolean allowFileSchemeCookiesImpl() { 293 throw new MustOverrideException(); 294 } 295 296 /** 297 * Sets whether the application's {@link WebView} instances should send and 298 * accept cookies for file scheme URLs. 299 * Use of cookies with file scheme URLs is potentially insecure and turned 300 * off by default. 301 * Do not use this feature unless you can be sure that no unintentional 302 * sharing of cookie data can take place. 303 * <p> 304 * Note that calls to this method will have no effect if made after a 305 * {@link WebView} or CookieManager instance has been created. 306 */ 307 // Static for backward compatibility. 308 public static void setAcceptFileSchemeCookies(boolean accept) { 309 getInstance().setAcceptFileSchemeCookiesImpl(accept); 310 } 311 312 /** 313 * Implements {@link #setAcceptFileSchemeCookies(boolean)}. 314 * 315 * @hide Only for use by WebViewProvider implementations 316 */ 317 protected void setAcceptFileSchemeCookiesImpl(boolean accept) { 318 throw new MustOverrideException(); 319 } 320} 321