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