Clean up JavaDoc for GeolocationPermissions
Much of the current JavaDoc for GeolocationPermissions exposes implementation
details which are of no interest to a Java developer. Move these comments out
of the JavaDoc and clean up the text.
Bug: 5461416
Change-Id: I95a68fe15016fadc729d8d857fd69b2c927a5ea9
diff --git a/core/java/android/webkit/GeolocationPermissions.java b/core/java/android/webkit/GeolocationPermissions.java
index 5d54180..d7b6adb 100755
--- a/core/java/android/webkit/GeolocationPermissions.java
+++ b/core/java/android/webkit/GeolocationPermissions.java
@@ -27,30 +27,47 @@
/**
- * 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.
+ * This class is used to manage permissions for the WebView's Geolocation
+ * JavaScript API.
*
- * 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.
+ * Geolocation permissions are applied to an origin, which consists of the
+ * host, scheme and port of a URI. In order for web content to use the
+ * Geolocation API, permission must be granted for that content's origin.
*
- * This class is the Java counterpart of the WebKit C++ GeolocationPermissions
- * class. It simply marshalls calls from the UI thread to the WebKit thread.
+ * This class stores Geolocation permissions. An origin's permission state can
+ * be either allowed or denied. This class uses Strings to represent
+ * an origin.
*
- * Within WebKit, Geolocation permissions may be applied either temporarily
- * (for the duration of the page) or permanently. This class deals only with
- * permanent permissions.
+ * When an origin attempts to use the Geolocation API, but no permission state
+ * is currently set for that origin,
+ * {@link WebChromeClient#onGeolocationPermissionsShowPrompt(String,GeolocationPermissions.Callback) WebChromeClient.onGeolocationPermissionsShowPrompt()}
+ * is called. This allows the permission state to be set for that origin.
+ *
+ * The methods of this class can be used to modify and interrogate the stored
+ * Geolocation permissions at any time.
*/
+// 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 {
/**
- * Callback interface used by the browser to report a Geolocation permission
- * state set by the user in response to a permissions prompt.
+ * A callback interface used by the host application to set the Geolocation
+ * permission state for an origin.
*/
public interface Callback {
- public void invoke(String origin, boolean allow, boolean remember);
+ /**
+ * Set the Geolocation permission state for the supplied origin.
+ * @param origin The origin for which permissions are set.
+ * @param allow Whether or not the origin should be allowed to use the
+ * Geolocation API.
+ * @param retain Whether the permission should be retained beyond the
+ * lifetime of a page currently being displayed by a
+ * WebView.
+ */
+ public void invoke(String origin, boolean allow, boolean retain);
};
// Log tag
@@ -82,7 +99,8 @@
private static final String ALLOWED = "allowed";
/**
- * Gets the singleton instance of the class.
+ * Get the singleton instance of this class.
+ * @return The singleton {@link GeolocationPermissions} instance.
*/
public static GeolocationPermissions getInstance() {
if (sInstance == null) {
@@ -196,15 +214,18 @@
}
/**
- * 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 based
- * on this string.
- *
- * Callback is a ValueCallback object whose onReceiveValue method will be
- * called asynchronously with the set of origins.
+ * Get the set of origins for which Geolocation permissions are stored.
+ * @param callback A {@link ValueCallback} to receive the result of this
+ * request. This object's
+ * {@link ValueCallback#onReceiveValue(T) onReceiveValue()}
+ * method will be invoked asynchronously with a set of
+ * Strings containing the 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 based
+ // on this string.
public void getOrigins(ValueCallback<Set<String> > callback) {
if (callback != null) {
if (WebViewCore.THREAD_NAME.equals(Thread.currentThread().getName())) {
@@ -217,10 +238,14 @@
}
/**
- * 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.
+ * Get the Geolocation permission state for the specified origin.
+ * @param origin The origin for which Geolocation permission is requested.
+ * @param callback A {@link ValueCallback} to receive the result of this
+ * request. This object's
+ * {@link ValueCallback#onReceiveValue(T) onReceiveValue()}
+ * method will be invoked asynchronously with a boolean
+ * indicating whether or not the origin can use the
+ * Geolocation API.
*/
public void getAllowed(String origin, ValueCallback<Boolean> callback) {
if (callback == null) {
@@ -242,27 +267,31 @@
}
/**
- * Clears the permission state for the specified origin. This method may be
- * called before the WebKit thread has intialized the message handler.
- * Messages will be queued until this time.
+ * Clear the Geolocation permission state for the specified origin.
+ * @param origin The origin for which Geolocation permissions are cleared.
*/
+ // This method may be called before the WebKit
+ // thread has intialized the message handler. Messages will be queued until
+ // this time.
public void clear(String origin) {
// Called on the UI thread.
postMessage(Message.obtain(null, CLEAR, origin));
}
/**
- * Allows the specified origin. This method may be called before the WebKit
- * thread has intialized the message handler. Messages will be queued until
- * this time.
+ * Allow the specified origin to use the Geolocation API.
+ * @param origin The origin for which Geolocation API use is allowed.
*/
+ // This method may be called before the WebKit
+ // thread has intialized the message handler. Messages will be queued until
+ // this time.
public void allow(String origin) {
// Called on the UI thread.
postMessage(Message.obtain(null, ALLOW, origin));
}
/**
- * Clears the permission state for all origins.
+ * Clear the Geolocation permission state for all origins.
*/
public void clearAll() {
// Called on the UI thread.
diff --git a/core/java/android/webkit/ValueCallback.java b/core/java/android/webkit/ValueCallback.java
index 1a167e8..5c7d97f 100644
--- a/core/java/android/webkit/ValueCallback.java
+++ b/core/java/android/webkit/ValueCallback.java
@@ -17,11 +17,12 @@
package android.webkit;
/**
- * A callback interface used to returns values asynchronously
+ * A callback interface used to provide values asynchronously.
*/
public interface ValueCallback<T> {
/**
- * Invoked when we have the result
+ * Invoked when the value is available.
+ * @param value The value.
*/
public void onReceiveValue(T value);
};
diff --git a/core/java/android/webkit/WebChromeClient.java b/core/java/android/webkit/WebChromeClient.java
index 3d129f7..a6ef0ce 100644
--- a/core/java/android/webkit/WebChromeClient.java
+++ b/core/java/android/webkit/WebChromeClient.java
@@ -250,14 +250,24 @@
}
/**
- * Instructs the client to show a prompt to ask the user to set the
- * Geolocation permission state for the specified origin.
+ * Notify the host application that web content from the specified origin
+ * is attempting to use the Geolocation API, but no permission state is
+ * currently set for that origin. The host application should invoke the
+ * specified callback with the desired permission state. See
+ * {@link GeolocationPermissions} for details.
+ * @param origin The origin of the web content attempting to use the
+ * Geolocation API.
+ * @param callback The callback to use to set the permission state for the
+ * origin.
*/
public void onGeolocationPermissionsShowPrompt(String origin,
GeolocationPermissions.Callback callback) {}
/**
- * Instructs the client to hide the Geolocation permissions prompt.
+ * Notify the host application that a request for Geolocation permissions,
+ * made with a previous call to
+ * {@link #onGeolocationPermissionsShowPrompt(String,GeolocationPermissions.Callback) onGeolocationPermissionsShowPrompt()}
+ * has been canceled. Any related UI should therefore be hidden.
*/
public void onGeolocationPermissionsHidePrompt() {}