/* * 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}, from the string * representation of the origin to a {@link WebStorage.Origin} object. */ public void getOrigins(ValueCallback 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 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 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() {} }