Home | History | Annotate | Download | only in webkit 
      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 
     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      */
     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      */
     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
    111     public void sync() {
    112         CookieManager.getInstance().flush();
    113     }
    114 
    115     /**
    116      * @deprecated Use {@link CookieManager#flush} instead.
    117      */
    118     @Deprecated
    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
    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
    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
    148     public void stopSync() {
    149     }
    150 
    151     static void setGetInstanceIsAllowed() {
    152         sGetInstanceAllowed = true;
    153     }
    154 
    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