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