Clean up JavaDoc for WebStorage
Bug: 5461416
Change-Id: Ice7a2ca1e346ae80f53b477d236ff8c20032cf2f
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 @@
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 @@
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 @@
* @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 @@
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 @@
/**
* 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 @@
}
/**
- * 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.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 @@
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 @@
}
/**
- * 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 @@
}
/**
- * @hide
* Message handler, UI side
+ * @hide
*/
public void createUIHandler() {
if (mUIHandler == null) {
@@ -156,8 +177,8 @@
}
/**
+ * Message handler, WebCore side
* @hide
- * Message handler, webcore side
*/
public synchronized void createHandler() {
if (mHandler == null) {
@@ -231,19 +252,22 @@
/*
* 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
* 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);
}
});
}