content: /*
   * Copyright (C) 2009 The Android Open Source Project
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package android.webkit;
  
  import android.annotation.SystemApi;
  
  import java.util.Map;
  
  /**
   * This class is used to manage the JavaScript storage APIs provided by the
   * {@link WebView}. It manages the Application Cache API, the Web SQL Database
   * API and the HTML5 Web Storage API.
   *
   * The Application Cache API provides a mechanism to create and maintain an
   * application cache to power offline Web applications. Use of the Application
   * Cache API can be attributed to an origin {@link WebStorage.Origin}, however
   * it is not possible to set per-origin quotas. Note that there can be only
   * one application cache per application.
   *
   * The Web SQL Database API provides storage which is private to a given origin.
   * Similar to the Application Cache, use of the Web SQL Database can be attributed
   * to an origin. It is also possible to set per-origin quotas.
   */
  public class WebStorage {
  
      /**
       * Encapsulates a callback function which is used to provide a new quota
       * for a JavaScript storage API.
       * See
       * {@link WebChromeClient#onExceededDatabaseQuota} and
       * {@link WebChromeClient#onReachedMaxAppCacheSize}.
       * @deprecated This class is obsolete and no longer used.
       */
      @Deprecated
      public interface QuotaUpdater {
          /**
           * Provides a new quota, specified in bytes.
           *
           * @param newQuota the new quota, in bytes
           */
          public void updateQuota(long newQuota);
      };
  
      /**
       * This class encapsulates information about the amount of storage
       * currently used by an origin for the JavaScript storage APIs.
       * An origin comprises the host, scheme and port of a URI.
       * See {@link WebStorage} for details.
       */
      public static class Origin {
          private String mOrigin = null;
          private long mQuota = 0;
          private long mUsage = 0;
  
          /** @hide */
          @SystemApi
          protected Origin(String origin, long quota, long usage) {
              mOrigin = origin;
              mQuota = quota;
              mUsage = usage;
          }
  
          /**
           * Gets the string representation of this origin.
           *
           * @return the string representation of this origin
           */
          // An origin string is created using WebCore::SecurityOrigin::toString().
          // Note that WebCore::SecurityOrigin uses 0 (which is not printed) for
          // the port if the port is the default for the protocol. Eg
          // http://www.google.com and http://www.google.com:80 both record a port
          // of 0 and hence toString() == 'http://www.google.com' for both.
          public String getOrigin() {
              return mOrigin;
          }
  
          /**
           * Gets the quota for this origin, for the Web SQL Database API, in
           * bytes. If this origin does not use the Web SQL Database API, this
           * quota will be set to zero.
           *
           * @return the quota, in bytes
           */
          public long getQuota() {
              return mQuota;
          }
  
          /**
           * Gets the total amount of storage currently being used by this origin,
           * for all JavaScript storage APIs, in bytes.
           *
           * @return the total amount of storage, in bytes
           */
          public long getUsage() {
              return mUsage;
          }
      }
  
      /*
       * When calling getOrigins(), getUsageForOrigin() and getQuotaForOrigin(),
       * we need to get the values from WebCore, but we cannot block while doing so
       * as we used to do, as this could result in a full deadlock (other WebCore
       * messages received while we are still blocked here, see http://b/2127737).
       *
       * We have to do everything asynchronously, by providing a callback function.
       * We post a message on the WebCore thread (mHandler) that will get the result
       * from WebCore, and we post it back on the UI thread (using mUIHandler).
       * We can then use the callback function to return the value.
       */
  
      /**
       * Gets the origins currently using either the Application Cache or Web SQL
       * Database APIs. This method operates asynchronously, with the result
       * being provided via a {@link ValueCallback}. The origins are provided as
       * a map, of type {@code Map<String, WebStorage.Origin>}, from the string
       * representation of the origin to a {@link WebStorage.Origin} object.
       */
      public void getOrigins(ValueCallback<Map> callback) {
          // Must be a no-op for backward compatibility: see the hidden constructor for reason.
      }
  
      /**
       * Gets the amount of storage currently being used by both the Application
       * Cache and Web SQL Database APIs by the given origin. The amount is given
       * in bytes and the origin is specified using its string representation.
       * This method operates asynchronously, with the result being provided via
       * a {@link ValueCallback}.
       */
      public void getUsageForOrigin(String origin, ValueCallback<Long> callback) {
          // Must be a no-op for backward compatibility: see the hidden constructor for reason.
      }
  
      /**
       * Gets the storage quota for the Web SQL Database API for the given origin.
       * The quota is given in bytes and the origin is specified using its string
       * representation. This method operates asynchronously, with the result
       * being provided via a {@link ValueCallback}. Note that a quota is not
       * enforced on a per-origin basis for the Application Cache API.
       */
      public void getQuotaForOrigin(String origin, ValueCallback<Long> callback) {
          // Must be a no-op for backward compatibility: see the hidden constructor for reason.
      }
  
      /**
       * Sets the storage quota for the Web SQL Database API for the given origin.
       * The quota is specified in bytes and the origin is specified using its string
       * representation. Note that a quota is not enforced on a per-origin basis
       * for the Application Cache API.
       * @deprecated Controlling quota per-origin will not be supported in future.
       */
      @Deprecated
      public void setQuotaForOrigin(String origin, long quota) {
          // Must be a no-op for backward compatibility: see the hidden constructor for reason.
      }
  
      /**
       * Clears the storage currently being used by both the Application Cache and
       * Web SQL Database APIs by the given origin. The origin is specified using
       * its string representation.
       */
      public void deleteOrigin(String origin) {
          // Must be a no-op for backward compatibility: see the hidden constructor for reason.
      }
  
      /**
       * Clears all storage currently being used by the JavaScript storage APIs.
       * This includes the Application Cache, Web SQL Database and the HTML5 Web
       * Storage APIs.
       */
      public void deleteAllData() {
          // Must be a no-op for backward compatibility: see the hidden constructor for reason.
      }
  
      /**
       * Gets the singleton instance of this class.
       *
       * @return the singleton {@link WebStorage} instance
       */
      public static WebStorage getInstance() {
        return WebViewFactory.getProvider().getWebStorage();
      }
  
      /**
       * This class should not be instantiated directly, applications must only use
       * {@link #getInstance()} to obtain the instance.
       * Note this constructor was erroneously public and published in SDK levels prior to 16, but
       * applications using it would receive a non-functional instance of this class (there was no
       * way to call createHandler() and createUIHandler(), so it would not work).
       * @hide
       */
      @SystemApi
      public WebStorage() {}
  }
  