1 /* 2 * Copyright (C) 2007 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 17 package android.webkit; 18 19 import android.content.Context; 20 21 22 /** 23 * The CookieSyncManager is used to synchronize the browser cookie store 24 * between RAM and permanent storage. To get the best performance, browser cookies are 25 * saved in RAM. A separate thread saves the cookies between, driven by a timer. 26 * <p> 27 * 28 * To use the CookieSyncManager, the host application has to call the following 29 * when the application starts: 30 * <p> 31 * 32 * <pre class="prettyprint">CookieSyncManager.createInstance(context)</pre><p> 33 * 34 * To set up for sync, the host application has to call<p> 35 * <pre class="prettyprint">CookieSyncManager.getInstance().startSync()</pre><p> 36 * 37 * in Activity.onResume(), and call 38 * <p> 39 * 40 * <pre class="prettyprint"> 41 * CookieSyncManager.getInstance().stopSync() 42 * </pre><p> 43 * 44 * in Activity.onPause().<p> 45 * 46 * To get instant sync instead of waiting for the timer to trigger, the host can 47 * call 48 * <p> 49 * <pre class="prettyprint">CookieSyncManager.getInstance().sync()</pre><p> 50 * 51 * The sync interval is 5 minutes, so you will want to force syncs 52 * manually anyway, for instance in {@link 53 * WebViewClient#onPageFinished}. Note that even sync() happens 54 * asynchronously, so don't do it just as your activity is shutting 55 * down. 56 * 57 * @deprecated The WebView now automatically syncs cookies as necessary. 58 * You no longer need to create or use the CookieSyncManager. 59 * To manually force a sync you can use the CookieManager 60 * method {@link CookieManager#flush} which is a synchronous 61 * replacement for {@link #sync}. 62 */ 63 @Deprecated 64 public final class CookieSyncManager extends WebSyncManager { 65 66 private static CookieSyncManager sRef; 67 private static boolean sGetInstanceAllowed = false; 68 CookieSyncManager()69 private CookieSyncManager() { 70 super(null, null); 71 } 72 73 /** 74 * Singleton access to a {@link CookieSyncManager}. An 75 * IllegalStateException will be thrown if 76 * {@link CookieSyncManager#createInstance(Context)} is not called before. 77 * 78 * @return CookieSyncManager 79 */ getInstance()80 public static synchronized CookieSyncManager getInstance() { 81 checkInstanceIsAllowed(); 82 if (sRef == null) { 83 sRef = new CookieSyncManager(); 84 } 85 return sRef; 86 } 87 88 /** 89 * Create a singleton CookieSyncManager within a context 90 * @param context 91 * @return CookieSyncManager 92 */ createInstance(Context context)93 public static synchronized CookieSyncManager createInstance(Context context) { 94 if (context == null) { 95 throw new IllegalArgumentException("Invalid context argument"); 96 } 97 setGetInstanceIsAllowed(); 98 return getInstance(); 99 } 100 101 /** 102 * sync() forces sync manager to sync now 103 * @deprecated Use {@link CookieManager#flush} instead. 104 */ 105 @Deprecated sync()106 public void sync() { 107 CookieManager.getInstance().flush(); 108 } 109 110 /** 111 * @deprecated Use {@link CookieManager#flush} instead. 112 */ 113 @Deprecated syncFromRamToFlash()114 protected void syncFromRamToFlash() { 115 CookieManager.getInstance().flush(); 116 } 117 118 /** 119 * resetSync() resets sync manager's timer. 120 * @deprecated Calling resetSync is no longer necessary as the WebView automatically 121 * syncs cookies. 122 */ 123 @Deprecated resetSync()124 public void resetSync() { 125 } 126 127 /** 128 * startSync() requests sync manager to start sync. 129 * @deprecated Calling startSync is no longer necessary as the WebView automatically 130 * syncs cookies. 131 */ 132 @Deprecated startSync()133 public void startSync() { 134 } 135 136 /** 137 * stopSync() requests sync manager to stop sync. remove any SYNC_MESSAGE in 138 * the queue to break the sync loop 139 * @deprecated Calling stopSync is no longer useful as the WebView 140 * automatically syncs cookies. 141 */ 142 @Deprecated stopSync()143 public void stopSync() { 144 } 145 setGetInstanceIsAllowed()146 static void setGetInstanceIsAllowed() { 147 sGetInstanceAllowed = true; 148 } 149 checkInstanceIsAllowed()150 private static void checkInstanceIsAllowed() { 151 // Prior to Android KK, calling createInstance() or constructing a WebView is 152 // a hard pre-condition for calling getInstance(). We retain that contract to aid 153 // developers targeting a range of SDK levels. 154 if (!sGetInstanceAllowed) { 155 throw new IllegalStateException( 156 "CookieSyncManager::createInstance() needs to be called " 157 + "before CookieSyncManager::getInstance()"); 158 } 159 } 160 } 161