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

Commit 9c6b01a7 authored by Steve Block's avatar Steve Block Committed by Android (Google) Code Review
Browse files

Merge "Clean up JavaDoc for WebStorage"

parents 9f7296af 285ddfc8
Loading
Loading
Loading
Loading
+35 −31
Original line number Diff line number Diff line
@@ -513,18 +513,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;

@@ -532,15 +532,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;

@@ -1462,19 +1462,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;
        }

@@ -1482,9 +1484,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);
@@ -1493,24 +1495,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 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 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 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 class WebStorage {
    }

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

    /**
     * Message handler, WebCore side
     * @hide
     * Message handler, webcore side
     */
    public synchronized void createHandler() {
        if (mHandler == null) {
@@ -231,19 +252,22 @@ public 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 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 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 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 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 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 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 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
@@ -430,38 +430,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);
                    }
                });
    }