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 public final class CookieSyncManager extends WebSyncManager {
     59 
     60     private static CookieSyncManager sRef;
     61 
     62     private static boolean sGetInstanceAllowed = false;
     63 
     64     private CookieSyncManager() {
     65         super("CookieSyncManager");
     66     }
     67 
     68     /**
     69      * Singleton access to a {@link CookieSyncManager}. An
     70      * IllegalStateException will be thrown if
     71      * {@link CookieSyncManager#createInstance(Context)} is not called before.
     72      *
     73      * @return CookieSyncManager
     74      */
     75     public static synchronized CookieSyncManager getInstance() {
     76         checkInstanceIsAllowed();
     77         if (sRef == null) {
     78             sRef = new CookieSyncManager();
     79         }
     80         return sRef;
     81     }
     82 
     83     /**
     84      * Create a singleton CookieSyncManager within a context
     85      * @param context
     86      * @return CookieSyncManager
     87      */
     88     public static synchronized CookieSyncManager createInstance(Context context) {
     89         if (context == null) {
     90             throw new IllegalArgumentException("Invalid context argument");
     91         }
     92 
     93         setGetInstanceIsAllowed();
     94         return getInstance();
     95     }
     96 
     97     protected void syncFromRamToFlash() {
     98         if (DebugFlags.COOKIE_SYNC_MANAGER) {
     99             Log.v(LOGTAG, "CookieSyncManager::syncFromRamToFlash STARTS");
    100         }
    101 
    102         CookieManager manager = CookieManager.getInstance();
    103 
    104         if (!manager.acceptCookie()) {
    105             return;
    106         }
    107 
    108         manager.flushCookieStore();
    109 
    110         if (DebugFlags.COOKIE_SYNC_MANAGER) {
    111             Log.v(LOGTAG, "CookieSyncManager::syncFromRamToFlash DONE");
    112         }
    113     }
    114 
    115     static void setGetInstanceIsAllowed() {
    116         sGetInstanceAllowed = true;
    117     }
    118 
    119     private static void checkInstanceIsAllowed() {
    120         // Prior to Android KK, calling createInstance() or constructing a WebView is
    121         // a hard pre-condition for calling getInstance(). We retain that contract to aid
    122         // developers targeting a range of SDK levels.
    123         if (!sGetInstanceAllowed) {
    124             throw new IllegalStateException(
    125                     "CookieSyncManager::createInstance() needs to be called "
    126                             + "before CookieSyncManager::getInstance()");
    127         }
    128     }
    129 }
    130