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 
     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      */
     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      */
     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
    106     public void sync() {
    107         CookieManager.getInstance().flush();
    108     }
    109 
    110     /**
    111      * @deprecated Use {@link CookieManager#flush} instead.
    112      */
    113     @Deprecated
    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
    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
    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
    143     public void stopSync() {
    144     }
    145 
    146     static void setGetInstanceIsAllowed() {
    147         sGetInstanceAllowed = true;
    148     }
    149 
    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