Clean up JavaDoc for WebStorage

Bug: 5461416
Change-Id: Ice7a2ca1e346ae80f53b477d236ff8c20032cf2f

4 files changed, 160 insertions, 100 deletions

diff --git a/core/java/android/webkit/CallbackProxy.java b/core/java/android/webkit/CallbackProxy.java
index 800ebc8..4994cf1 100644
--- a/core/java/android/webkit/CallbackProxy.java
+++ b/core/java/android/webkit/CallbackProxy.java
@@ -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);
diff --git a/core/java/android/webkit/WebChromeClient.java b/core/java/android/webkit/WebChromeClient.java
index a6ef0ce..9c3a679 100644
--- a/core/java/android/webkit/WebChromeClient.java
+++ b/core/java/android/webkit/WebChromeClient.java
@@ -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,
-        WebStorage.QuotaUpdater quotaUpdater) {
+            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);
     }
 
     /**
diff --git a/core/java/android/webkit/WebStorage.java b/core/java/android/webkit/WebStorage.java
index 2300c2e..975e137 100644
--- a/core/java/android/webkit/WebStorage.java
+++ b/core/java/android/webkit/WebStorage.java
@@ -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() {
diff --git a/core/java/android/webkit/WebViewCore.java b/core/java/android/webkit/WebViewCore.java
index 15a2d48..715dc5b 100644
--- a/core/java/android/webkit/WebViewCore.java
+++ b/core/java/android/webkit/WebViewCore.java
@@ -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);
                     }
                 });
     }