https://source.android.com/ 
/*
 * 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 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 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. 
/**
 * 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 WebChromeClient.onExceededDatabaseQuota and WebChromeClient.onReachedMaxAppCacheSize. 
Deprecated:This class is obsolete and no longer used.
/**
     * 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.

Params:
  • newQuota – the new quota, in bytes
/**
         * 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 WebStorage for details. 
/**
     * 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
/** @hide */
        @SystemApi
        protected Origin(String origin, long quota, long usage) {
            mOrigin = origin;
            mQuota = quota;
            mUsage = usage;
        }

        
Gets the string representation of this origin.

Returns:the string representation of this origin
/**
         * 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.

Returns:the quota, in bytes
/**
         * 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.

Returns:the total amount of storage, in bytes
/**
         * 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 ValueCallback. The origins are provided as a map, of type Map<String, WebStorage.Origin>, from the string representation of the origin to a Origin object. 
/**
     * 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 ValueCallback. 
/**
     * 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 ValueCallback. Note that a quota is not enforced on a per-origin basis for the Application Cache API. 
/**
     * 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.
/**
     * 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.

/**
     * 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.

/**
     * 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.

Returns:the singleton WebStorage instance
/**
     * 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 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
/**
     * 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() {}
}