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 private static final Object sLock = new Object(); 69 CookieSyncManager()70 private CookieSyncManager() { 71 super(null, null); 72 } 73 74 /** 75 * Singleton access to a {@link CookieSyncManager}. An 76 * IllegalStateException will be thrown if 77 * {@link CookieSyncManager#createInstance(Context)} is not called before. 78 * 79 * @return CookieSyncManager 80 */ getInstance()81 public static CookieSyncManager getInstance() { 82 synchronized (sLock) { 83 checkInstanceIsAllowed(); 84 if (sRef == null) { 85 sRef = new CookieSyncManager(); 86 } 87 return sRef; 88 } 89 } 90 91 /** 92 * Create a singleton CookieSyncManager within a context 93 * @param context 94 * @return CookieSyncManager 95 */ createInstance(Context context)96 public static CookieSyncManager createInstance(Context context) { 97 synchronized (sLock) { 98 if (context == null) { 99 throw new IllegalArgumentException("Invalid context argument"); 100 } 101 setGetInstanceIsAllowed(); 102 return getInstance(); 103 } 104 } 105 106 /** 107 * sync() forces sync manager to sync now 108 * @deprecated Use {@link CookieManager#flush} instead. 109 */ 110 @Deprecated sync()111 public void sync() { 112 CookieManager.getInstance().flush(); 113 } 114 115 /** 116 * @deprecated Use {@link CookieManager#flush} instead. 117 */ 118 @Deprecated syncFromRamToFlash()119 protected void syncFromRamToFlash() { 120 CookieManager.getInstance().flush(); 121 } 122 123 /** 124 * resetSync() resets sync manager's timer. 125 * @deprecated Calling resetSync is no longer necessary as the WebView automatically 126 * syncs cookies. 127 */ 128 @Deprecated resetSync()129 public void resetSync() { 130 } 131 132 /** 133 * startSync() requests sync manager to start sync. 134 * @deprecated Calling startSync is no longer necessary as the WebView automatically 135 * syncs cookies. 136 */ 137 @Deprecated startSync()138 public void startSync() { 139 } 140 141 /** 142 * stopSync() requests sync manager to stop sync. remove any SYNC_MESSAGE in 143 * the queue to break the sync loop 144 * @deprecated Calling stopSync is no longer useful as the WebView 145 * automatically syncs cookies. 146 */ 147 @Deprecated stopSync()148 public void stopSync() { 149 } 150 setGetInstanceIsAllowed()151 static void setGetInstanceIsAllowed() { 152 sGetInstanceAllowed = true; 153 } 154 checkInstanceIsAllowed()155 private static void checkInstanceIsAllowed() { 156 // Prior to Android KK, calling createInstance() or constructing a WebView is 157 // a hard pre-condition for calling getInstance(). We retain that contract to aid 158 // developers targeting a range of SDK levels. 159 if (!sGetInstanceAllowed) { 160 throw new IllegalStateException( 161 "CookieSyncManager::createInstance() needs to be called " 162 + "before CookieSyncManager::getInstance()"); 163 } 164 } 165 } 166