Clean up JavaDoc for WebStorage

Bug: 5461416
Change-Id: Ice7a2ca1e346ae80f53b477d236ff8c20032cf2f

Author: Steve Block

core/java/android/webkit/CallbackProxy.java

@@ -479,34 +479,34 @@ public void handleMessage(Message msg) {
                     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;
 
             case REACHED_APPCACHE_MAXSIZE:
                 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,29 +1422,31 @@ public boolean onJsBeforeUnload(String url, String message) {
      * @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;
         }
 
         Message exceededQuota = obtainMessage(EXCEEDED_DATABASE_QUOTA);
         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 @@ public void onExceededDatabaseQuota(
     /**
      * 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);

core/java/android/webkit/WebChromeClient.java

@@ -216,37 +216,54 @@ public boolean onJsBeforeUnload(WebView view, String url, String message,
     }
 
    /**
-    * 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);
     }
 
     /**