Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clean up JavaDoc for WebStorage

Browse Source 
Bug: 5461416
Change-Id: Ice7a2ca1e346ae80f53b477d236ff8c20032cf2f
This commit is contained in:
Steve Block
2012-03-28 12:46:02 +01:00
parent b187d52f8a
commit 285ddfc8ab
4 changed files with 160 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
core/java/android/webkit/CallbackProxy.java
View File

@@ -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);

61
core/java/android/webkit/WebChromeClient.java
View File

@@ -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);
}
/**

107
core/java/android/webkit/WebStorage.java
View File

@@ -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() {

26
core/java/android/webkit/WebViewCore.java
View File

@@ -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);
}
});
}