Improves documentation for GeolocationPermissions class. Do not merge.
Also sets an explicit type for GeolocationPermissions.getOrigins.
This is a partial fix for bug http://b/issue?id=2271636
This has already been submitted to eclair-mr2.
Change-Id: I0c77eca94eb56d16c2a9a29a72eb221e4a7a52a6
diff --git a/api/current.xml b/api/current.xml
index 065176b..cf997ce 100644
--- a/api/current.xml
+++ b/api/current.xml
@@ -174063,7 +174063,7 @@
deprecated="not deprecated"
visibility="public"
>
-<parameter name="callback" type="android.webkit.ValueCallback<java.util.Set>">
+<parameter name="callback" type="android.webkit.ValueCallback<java.util.Set<java.lang.String>>">
</parameter>
</method>
</class>
diff --git a/core/java/android/webkit/GeolocationPermissions.java b/core/java/android/webkit/GeolocationPermissions.java
index 64a9d9b..d12d828 100755
--- a/core/java/android/webkit/GeolocationPermissions.java
+++ b/core/java/android/webkit/GeolocationPermissions.java
@@ -26,8 +26,22 @@
/**
- * Implements the Java side of GeolocationPermissions. Simply marshalls calls
- * from the UI thread to the WebKit thread.
+ * This class is used to get Geolocation permissions from, and set them on the
+ * WebView. For example, it could be used to allow a user to manage Geolocation
+ * permissions from a browser's UI.
+ *
+ * Permissions are managed on a per-origin basis, as required by the
+ * Geolocation spec - http://dev.w3.org/geo/api/spec-source.html. An origin
+ * specifies the scheme, host and port of particular frame. An origin is
+ * represented here as a string, using the output of
+ * WebCore::SecurityOrigin::toString.
+ *
+ * This class is the Java counterpart of the WebKit C++ GeolocationPermissions
+ * class. It simply marshalls calls from the UI thread to the WebKit thread.
+ *
+ * Within WebKit, Geolocation permissions may be applied either temporarily
+ * (for the duration of the page) or permanently. This class deals only with
+ * permanent permissions.
*/
public final class GeolocationPermissions {
/**
@@ -92,8 +106,8 @@
switch (msg.what) {
case RETURN_ORIGINS: {
Map values = (Map) msg.obj;
- Set origins = (Set) values.get(ORIGINS);
- ValueCallback<Set> callback = (ValueCallback<Set>) values.get(CALLBACK);
+ Set<String> origins = (Set<String>) values.get(ORIGINS);
+ ValueCallback<Set<String> > callback = (ValueCallback<Set<String> >) values.get(CALLBACK);
callback.onReceiveValue(origins);
} break;
case RETURN_ALLOWED: {
@@ -122,10 +136,9 @@
case GET_ORIGINS: {
getOriginsImpl();
ValueCallback callback = (ValueCallback) msg.obj;
- Set origins = new HashSet(mOrigins);
Map values = new HashMap<String, Object>();
values.put(CALLBACK, callback);
- values.put(ORIGINS, origins);
+ values.put(ORIGINS, mOrigins);
postUIMessage(Message.obtain(null, RETURN_ORIGINS, values));
} break;
case GET_ALLOWED: {
@@ -185,15 +198,17 @@
* Gets the set of origins for which Geolocation permissions are stored.
* Note that we represent the origins as strings. These are created using
* WebCore::SecurityOrigin::toString(). As long as all 'HTML 5 modules'
- * (Database, Geolocation etc) do so, it's safe to match up origins for the
- * purposes of displaying UI.
+ * (Database, Geolocation etc) do so, it's safe to match up origins based
+ * on this string.
+ *
+ * Callback is a ValueCallback object whose onReceiveValue method will be
+ * called asynchronously with the set of origins.
*/
- public void getOrigins(ValueCallback<Set> callback) {
+ public void getOrigins(ValueCallback<Set<String> > callback) {
if (callback != null) {
if (WebViewCore.THREAD_NAME.equals(Thread.currentThread().getName())) {
getOriginsImpl();
- Set origins = new HashSet(mOrigins);
- callback.onReceiveValue(origins);
+ callback.onReceiveValue(mOrigins);
} else {
postMessage(Message.obtain(null, GET_ORIGINS, callback));
}
@@ -210,6 +225,9 @@
/**
* Gets the permission state for the specified origin.
+ *
+ * Callback is a ValueCallback object whose onReceiveValue method will be
+ * called asynchronously with the permission state for the origin.
*/
public void getAllowed(String origin, ValueCallback<Boolean> callback) {
if (callback == null) {
@@ -231,7 +249,7 @@
}
/**
- * Helper method to get the permission state.
+ * Helper method to get the permission state for the specified origin.
*/
private void getAllowedImpl(String origin) {
// Called on the WebKit thread.
