Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 285ddfc8 authored by Steve Block's avatar Steve Block
Browse files

Clean up JavaDoc for WebStorage

Bug: 5461416
Change-Id: Ice7a2ca1e346ae80f53b477d236ff8c20032cf2f
parent b187d52f
Loading
Loading
Loading
Loading
+35 −31
Original line number Diff line number Diff line
@@ -479,18 +479,18 @@ class CallbackProxy extends Handler {
                    String databaseIdentifier =
                            (String) map.get("databaseIdentifier");
                    String url = (String) map.get("url");
                    long currentQuota =
                            ((Long) map.get("currentQuota")).longValue();
                    long totalUsedQuota =
                            ((Long) map.get("totalUsedQuota")).longValue();
                    long estimatedSize =
                            ((Long) map.get("estimatedSize")).longValue();
                    long quota =
                            ((Long) map.get("quota")).longValue();
                    long totalQuota =
                            ((Long) map.get("totalQuota")).longValue();
                    long estimatedDatabaseSize =
                            ((Long) map.get("estimatedDatabaseSize")).longValue();
                    WebStorage.QuotaUpdater quotaUpdater =
                        (WebStorage.QuotaUpdater) map.get("quotaUpdater");

                    mWebChromeClient.onExceededDatabaseQuota(url,
                            databaseIdentifier, currentQuota, estimatedSize,
                            totalUsedQuota, quotaUpdater);
                            databaseIdentifier, quota, estimatedDatabaseSize,
                            totalQuota, quotaUpdater);
                }
                break;

@@ -498,15 +498,15 @@ class CallbackProxy extends Handler {
                if (mWebChromeClient != null) {
                    HashMap<String, Object> map =
                            (HashMap<String, Object>) msg.obj;
                    long spaceNeeded =
                            ((Long) map.get("spaceNeeded")).longValue();
                    long totalUsedQuota =
                        ((Long) map.get("totalUsedQuota")).longValue();
                    long requiredStorage =
                            ((Long) map.get("requiredStorage")).longValue();
                    long quota =
                        ((Long) map.get("quota")).longValue();
                    WebStorage.QuotaUpdater quotaUpdater =
                        (WebStorage.QuotaUpdater) map.get("quotaUpdater");

                    mWebChromeClient.onReachedMaxAppCacheSize(spaceNeeded,
                            totalUsedQuota, quotaUpdater);
                    mWebChromeClient.onReachedMaxAppCacheSize(requiredStorage,
                            quota, quotaUpdater);
                }
                break;

@@ -1422,19 +1422,21 @@ class CallbackProxy extends Handler {
     * @param url The URL that caused the quota overflow.
     * @param databaseIdentifier The identifier of the database that the
     *     transaction that caused the overflow was running on.
     * @param currentQuota The current quota the origin is allowed.
     * @param estimatedSize The estimated size of the database.
     * @param totalUsedQuota is the sum of all origins' quota.
     * @param quota The current quota the origin is allowed.
     * @param estimatedDatabaseSize The estimated size of the database.
     * @param totalQuota is the sum of all origins' quota.
     * @param quotaUpdater An instance of a class encapsulating a callback
     *     to WebViewCore to run when the decision to allow or deny more
     *     quota has been made.
     */
    public void onExceededDatabaseQuota(
            String url, String databaseIdentifier, long currentQuota,
            long estimatedSize, long totalUsedQuota,
            String url, String databaseIdentifier, long quota,
            long estimatedDatabaseSize, long totalQuota,
            WebStorage.QuotaUpdater quotaUpdater) {
        if (mWebChromeClient == null) {
            quotaUpdater.updateQuota(currentQuota);
            // Native-side logic prevents the quota being updated to a smaller
            // value.
            quotaUpdater.updateQuota(quota);
            return;
        }

@@ -1442,9 +1444,9 @@ class CallbackProxy extends Handler {
        HashMap<String, Object> map = new HashMap();
        map.put("databaseIdentifier", databaseIdentifier);
        map.put("url", url);
        map.put("currentQuota", currentQuota);
        map.put("estimatedSize", estimatedSize);
        map.put("totalUsedQuota", totalUsedQuota);
        map.put("quota", quota);
        map.put("estimatedDatabaseSize", estimatedDatabaseSize);
        map.put("totalQuota", totalQuota);
        map.put("quotaUpdater", quotaUpdater);
        exceededQuota.obj = map;
        sendMessage(exceededQuota);
@@ -1453,24 +1455,26 @@ class CallbackProxy extends Handler {
    /**
     * Called by WebViewCore to inform the Java side that the appcache has
     * exceeded its max size.
     * @param spaceNeeded is the amount of disk space that would be needed
     * in order for the last appcache operation to succeed.
     * @param totalUsedQuota is the sum of all origins' quota.
     * @param requiredStorage is the amount of storage, in bytes, that would be
     * needed in order for the last appcache operation to succeed.
     * @param quota is the current quota (for all origins).
     * @param quotaUpdater An instance of a class encapsulating a callback
     * to WebViewCore to run when the decision to allow or deny a bigger
     * app cache size has been made.
     */
    public void onReachedMaxAppCacheSize(long spaceNeeded,
            long totalUsedQuota, WebStorage.QuotaUpdater quotaUpdater) {
    public void onReachedMaxAppCacheSize(long requiredStorage,
            long quota, WebStorage.QuotaUpdater quotaUpdater) {
        if (mWebChromeClient == null) {
            quotaUpdater.updateQuota(0);
            // Native-side logic prevents the quota being updated to a smaller
            // value.
            quotaUpdater.updateQuota(quota);
            return;
        }

        Message msg = obtainMessage(REACHED_APPCACHE_MAXSIZE);
        HashMap<String, Object> map = new HashMap();
        map.put("spaceNeeded", spaceNeeded);
        map.put("totalUsedQuota", totalUsedQuota);
        map.put("requiredStorage", requiredStorage);
        map.put("quota", quota);
        map.put("quotaUpdater", quotaUpdater);
        msg.obj = map;
        sendMessage(msg);
+39 −22
Original line number Diff line number Diff line
@@ -216,37 +216,54 @@ public class WebChromeClient {
    }

   /**
    * Tell the client that the database quota for the origin has been exceeded.
    * @param url The URL that triggered the notification
    * @param databaseIdentifier The identifier of the database that caused the
    *     quota overflow.
    * @param currentQuota The current quota for the origin.
    * @param estimatedSize The estimated size of the database.
    * @param totalUsedQuota is the sum of all origins' quota.
    * @param quotaUpdater A callback to inform the WebCore thread that a new
    *     quota is available. This callback must always be executed at some
    *     point to ensure that the sleeping WebCore thread is woken up.
    * Tell the client that the quota has been exceeded for the Web SQL Database
    * API for a particular origin and request a new quota. The client must
    * respond by invoking the
    * {@link WebStorage.QuotaUpdater#updateQuota(long) updateQuota(long)}
    * method of the supplied {@link WebStorage.QuotaUpdater} instance. The
    * minimum value that can be set for the new quota is the current quota. The
    * default implementation responds with the current quota, so the quota will
    * not be increased.
    * @param url The URL of the page that triggered the notification
    * @param databaseIdentifier The identifier of the database where the quota
    *                           was exceeded.
    * @param quota The quota for the origin, in bytes
    * @param estimatedDatabaseSize The estimated size of the offending
    *                              database, in bytes
    * @param totalQuota The total quota for all origins, in bytes
    * @param quotaUpdater An instance of {@link WebStorage.QuotaUpdater} which
    *                     must be used to inform the WebView of the new quota.
    */
    // Note that the callback must always be executed at some point to ensure
    // that the sleeping WebCore thread is woken up.
    public void onExceededDatabaseQuota(String url, String databaseIdentifier,
        long currentQuota, long estimatedSize, long totalUsedQuota,
            long quota, long estimatedDatabaseSize, long totalQuota,
            WebStorage.QuotaUpdater quotaUpdater) {
        // This default implementation passes the current quota back to WebCore.
        // WebCore will interpret this that new quota was declined.
        quotaUpdater.updateQuota(currentQuota);
        quotaUpdater.updateQuota(quota);
    }

   /**
    * Tell the client that the Application Cache has exceeded its max size.
    * @param spaceNeeded is the amount of disk space that would be needed
    * in order for the last appcache operation to succeed.
    * @param totalUsedQuota is the sum of all origins' quota.
    * @param quotaUpdater A callback to inform the WebCore thread that a new
    * app cache size is available. This callback must always be executed at
    * some point to ensure that the sleeping WebCore thread is woken up.
    * Tell the client that the quota has been reached for the Application Cache
    * API and request a new quota. The client must respond by invoking the
    * {@link WebStorage.QuotaUpdater#updateQuota(long) updateQuota(long)}
    * method of the supplied {@link WebStorage.QuotaUpdater} instance. The
    * minimum value that can be set for the new quota is the current quota. The
    * default implementation responds with the current quota, so the quota will
    * not be increased.
    * @param requiredStorage The amount of storage required by the Application
    *                        Cache operation that triggered this notification,
    *                        in bytes.
    * @param quota The quota, in bytes
    * @param quotaUpdater An instance of {@link WebStorage.QuotaUpdater} which
    *                     must be used to inform the WebView of the new quota.
    */
    public void onReachedMaxAppCacheSize(long spaceNeeded, long totalUsedQuota,
    // Note that the callback must always be executed at some point to ensure
    // that the sleeping WebCore thread is woken up.
    public void onReachedMaxAppCacheSize(long requiredStorage, long quota,
            WebStorage.QuotaUpdater quotaUpdater) {
        quotaUpdater.updateQuota(0);
        quotaUpdater.updateQuota(quota);
    }

    /**
+73 −34
Original line number Diff line number Diff line
@@ -25,19 +25,34 @@ import java.util.Map;
import java.util.Set;

/**
 * Functionality for manipulating the webstorage databases.
 * 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 Web SQL Database API provides storage which is private to a given
 * origin, where an origin comprises the host, scheme and port of a URI.
 * Similarly, use of the Application Cache API can be attributed to an origin.
 * This class provides access to the storage use and quotas for these APIs for
 * a given origin. Origins are represented using {@link WebStorage.Origin}.
 */
public final class WebStorage {

    /**
     * Encapsulates a callback function to be executed when a new quota is made
     * available. We primarily want this to allow us to call back the sleeping
     * WebCore thread from outside the WebViewCore class (as the native call
     * is private). It is imperative that this the setDatabaseQuota method is
     * executed once a decision to either allow or deny new quota is made,
     * otherwise the WebCore thread will remain asleep.
     * 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}.
     */
    // We primarily want this to allow us to call back the sleeping WebCore
    // thread from outside the WebViewCore class (as the native call is
    // private). It is imperative that the setDatabaseQuota method is
    // executed after a decision to either allow or deny new quota is made,
    // otherwise the WebCore thread will remain asleep.
    public interface QuotaUpdater {
        /**
         * Provide a new quota, specified in bytes.
         * @param newQuota The new quota, in bytes
         */
        public void updateQuota(long newQuota);
    };

@@ -70,7 +85,9 @@ public final class WebStorage {
    private Handler mUIHandler = null;

    /**
     * Class containing the HTML5 database quota and usage for an origin.
     * This class encapsulates information about the amount of storage
     * currently used by an origin for the JavaScript storage APIs.
     * See {@link WebStorage} for details.
     */
    public static class Origin {
        private String mOrigin = null;
@@ -93,28 +110,32 @@ public final class WebStorage {
        }

        /**
         * 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.
         * @return The origin string.
         * Get 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;
        }

        /**
         * Returns the quota for this origin's HTML5 database.
         * @return The quota in bytes.
         * Get 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;
        }

        /**
         * Returns the usage for this origin's HTML5 database.
         * @return The usage in bytes.
         * Get 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;
@@ -122,8 +143,8 @@ public final class WebStorage {
    }

    /**
     * @hide
     * Message handler, UI side
     * @hide
     */
    public void createUIHandler() {
        if (mUIHandler == null) {
@@ -156,8 +177,8 @@ public final class WebStorage {
    }

    /**
     * Message handler, WebCore side
     * @hide
     * Message handler, webcore side
     */
    public synchronized void createHandler() {
        if (mHandler == null) {
@@ -231,19 +252,22 @@ public final class WebStorage {

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

    /**
     * Returns a list of origins having a database. The Map is of type
     * Map<String, Origin>.
     * Get 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) {
        if (callback != null) {
@@ -269,7 +293,11 @@ public final class WebStorage {
    }

    /**
     * Returns the use for a given origin
     * Get 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) {
        if (callback == null) {
@@ -292,7 +320,11 @@ public final class WebStorage {
    }

    /**
     * Returns the quota for a given origin
     * Get 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) {
        if (callback == null) {
@@ -315,7 +347,10 @@ public final class WebStorage {
    }

    /**
     * Set the quota for a given origin
     * Set 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.
     */
    public void setQuotaForOrigin(String origin, long quota) {
        if (origin != null) {
@@ -329,7 +364,9 @@ public final class WebStorage {
    }

    /**
     * Delete a given origin
     * Clear 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) {
        if (origin != null) {
@@ -343,7 +380,9 @@ public final class WebStorage {
    }

    /**
     * Delete all databases
     * Clear 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() {
        if (WebViewCore.THREAD_NAME.equals(Thread.currentThread().getName())) {
@@ -381,8 +420,8 @@ public final class WebStorage {
    }

    /**
     * Get the global instance of WebStorage.
     * @return A single instance of WebStorage.
     * Get the singleton instance of this class.
     * @return The singleton {@link WebStorage} instance.
     */
    public static WebStorage getInstance() {
      if (sWebStorage == null) {
@@ -404,7 +443,7 @@ public final class WebStorage {
    }

    /**
     * Run on the webcore thread
     * Run on the WebCore thread
     * set the local values with the current ones
     */
    private void syncValues() {
+13 −13
Original line number Diff line number Diff line
@@ -428,38 +428,38 @@ public final class WebViewCore {
     * Notify the browser that the origin has exceeded it's database quota.
     * @param url The URL that caused the overflow.
     * @param databaseIdentifier The identifier of the database.
     * @param currentQuota The current quota for the origin.
     * @param estimatedSize The estimated size of the database.
     * @param quota The current quota for the origin.
     * @param estimatedDatabaseSize The estimated size of the database.
     */
    protected void exceededDatabaseQuota(String url,
                                         String databaseIdentifier,
                                         long currentQuota,
                                         long estimatedSize) {
                                         long quota,
                                         long estimatedDatabaseSize) {
        // Inform the callback proxy of the quota overflow. Send an object
        // that encapsulates a call to the nativeSetDatabaseQuota method to
        // awaken the sleeping webcore thread when a decision from the
        // client to allow or deny quota is available.
        mCallbackProxy.onExceededDatabaseQuota(url, databaseIdentifier,
                currentQuota, estimatedSize, getUsedQuota(),
                quota, estimatedDatabaseSize, getUsedQuota(),
                new WebStorage.QuotaUpdater() {
                        @Override
                        public void updateQuota(long quota) {
                            nativeSetNewStorageLimit(mNativeClass, quota);
                        public void updateQuota(long newQuota) {
                            nativeSetNewStorageLimit(mNativeClass, newQuota);
                        }
                });
    }

    /**
     * Notify the browser that the appcache has exceeded its max size.
     * @param spaceNeeded is the amount of disk space that would be needed
     * in order for the last appcache operation to succeed.
     * @param requiredStorage is the amount of storage, in bytes, that would be
     * needed in order for the last appcache operation to succeed.
     */
    protected void reachedMaxAppCacheSize(long spaceNeeded) {
        mCallbackProxy.onReachedMaxAppCacheSize(spaceNeeded, getUsedQuota(),
    protected void reachedMaxAppCacheSize(long requiredStorage) {
        mCallbackProxy.onReachedMaxAppCacheSize(requiredStorage, getUsedQuota(),
                new WebStorage.QuotaUpdater() {
                    @Override
                    public void updateQuota(long quota) {
                        nativeSetNewStorageLimit(mNativeClass, quota);
                    public void updateQuota(long newQuota) {
                        nativeSetNewStorageLimit(mNativeClass, newQuota);
                    }
                });
    }