Merge changes I0c77eca9,Ibd184157,I81947f67 into eclair

* changes:
  Rename WebChromeClient.addMessageToConsole to WebChromeClient.onConsoleMessage. Do not merge.
  Update JavaDoc for CacheManger.CacheResult, WebChromeClient.getDefaultVideoPoster and WebChromeClient.getVideoLoadingProgressView. Do not merge.
  Improves documentation for GeolocationPermissions class. Do not merge.

6 files changed, 68 insertions, 40 deletions

diff --git a/api/current.xml b/api/current.xml
index 065176b..a60c3a1 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&lt;java.util.Set&gt;">
+<parameter name="callback" type="android.webkit.ValueCallback&lt;java.util.Set&lt;java.lang.String&gt;&gt;">
 </parameter>
 </method>
 </class>
@@ -175159,8 +175159,8 @@
  visibility="public"
 >
 </constructor>
-<method name="addMessageToConsole"
- return="void"
+<method name="getDefaultVideoPoster"
+ return="android.graphics.Bitmap"
  abstract="false"
  native="false"
  synchronized="false"
@@ -175169,15 +175169,9 @@
  deprecated="not deprecated"
  visibility="public"
 >
-<parameter name="message" type="java.lang.String">
-</parameter>
-<parameter name="lineNumber" type="int">
-</parameter>
-<parameter name="sourceID" type="java.lang.String">
-</parameter>
 </method>
-<method name="getDefaultVideoPoster"
- return="android.graphics.Bitmap"
+<method name="getVideoLoadingProgressView"
+ return="android.view.View"
  abstract="false"
  native="false"
  synchronized="false"
@@ -175187,8 +175181,8 @@
  visibility="public"
 >
 </method>
-<method name="getVideoLoadingProgressView"
- return="android.view.View"
+<method name="getVisitedHistory"
+ return="void"
  abstract="false"
  native="false"
  synchronized="false"
@@ -175197,8 +175191,10 @@
  deprecated="not deprecated"
  visibility="public"
 >
+<parameter name="callback" type="android.webkit.ValueCallback&lt;java.lang.String[]&gt;">
+</parameter>
 </method>
-<method name="getVisitedHistory"
+<method name="onCloseWindow"
  return="void"
  abstract="false"
  native="false"
@@ -175208,10 +175204,10 @@
  deprecated="not deprecated"
  visibility="public"
 >
-<parameter name="callback" type="android.webkit.ValueCallback&lt;java.lang.String[]&gt;">
+<parameter name="window" type="android.webkit.WebView">
 </parameter>
 </method>
-<method name="onCloseWindow"
+<method name="onConsoleMessage"
  return="void"
  abstract="false"
  native="false"
@@ -175221,7 +175217,11 @@
  deprecated="not deprecated"
  visibility="public"
 >
-<parameter name="window" type="android.webkit.WebView">
+<parameter name="message" type="java.lang.String">
+</parameter>
+<parameter name="lineNumber" type="int">
+</parameter>
+<parameter name="sourceID" type="java.lang.String">
 </parameter>
 </method>
 <method name="onCreateWindow"
diff --git a/core/java/android/webkit/CacheManager.java b/core/java/android/webkit/CacheManager.java
index 75028de..c74092e 100644
--- a/core/java/android/webkit/CacheManager.java
+++ b/core/java/android/webkit/CacheManager.java
@@ -74,6 +74,11 @@ public final class CacheManager {
     // Flag to clear the cache when the CacheManager is initialized
     private static boolean mClearCacheOnInit = false;
 
+    /**
+     * This class represents a resource retrieved from the HTTP cache.
+     * Instances of this class can be obtained by invoking the
+     * CacheManager.getCacheFile() method.
+     */
     public static class CacheResult {
         // these fields are saved to the database
         int httpStatusCode;
diff --git a/core/java/android/webkit/CallbackProxy.java b/core/java/android/webkit/CallbackProxy.java
index f760b61..e9afcb6 100644
--- a/core/java/android/webkit/CallbackProxy.java
+++ b/core/java/android/webkit/CallbackProxy.java
@@ -652,7 +652,7 @@ class CallbackProxy extends Handler {
                 String message = msg.getData().getString("message");
                 String sourceID = msg.getData().getString("sourceID");
                 int lineNumber = msg.getData().getInt("lineNumber");
-                mWebChromeClient.addMessageToConsole(message, lineNumber, sourceID);
+                mWebChromeClient.onConsoleMessage(message, lineNumber, sourceID);
                 break;
 
             case GET_VISITED_HISTORY:
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 @@ import java.util.Set;
 
 
 /**
- * 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 @@ public final class GeolocationPermissions {
                     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 @@ public final class GeolocationPermissions {
                         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 @@ public final class GeolocationPermissions {
      * 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 @@ public final class GeolocationPermissions {
 
     /**
      * 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 @@ public final class GeolocationPermissions {
     }
 
     /**
-     * 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.
diff --git a/core/java/android/webkit/WebChromeClient.java b/core/java/android/webkit/WebChromeClient.java
index 92676aa..8ca4142 100644
--- a/core/java/android/webkit/WebChromeClient.java
+++ b/core/java/android/webkit/WebChromeClient.java
@@ -256,29 +256,34 @@ public class WebChromeClient {
     }
 
     /**
-     * Add a JavaScript error message to the console. Clients should override
-     * this to process the log message as they see fit.
+     * Report a JavaScript error message to the host application. The ChromeClient
+     * should override this to process the log message as they see fit.
      * @param message The error message to report.
      * @param lineNumber The line number of the error.
      * @param sourceID The name of the source file that caused the error.
      */
-    public void addMessageToConsole(String message, int lineNumber, String sourceID) {}
+    public void onConsoleMessage(String message, int lineNumber, String sourceID) {}
 
     /**
-     * Ask the host application for an icon to represent a <video> element.
-     * This icon will be used if the Web page did not specify a poster attribute.
+     * When not playing, video elements are represented by a 'poster' image. The
+     * image to use can be specified by the poster attribute of the video tag in
+     * HTML. If the attribute is absent, then a default poster will be used. This
+     * method allows the ChromeClient to provide that default image.
      *
-     * @return Bitmap The icon or null if no such icon is available.
+     * @return Bitmap The image to use as a default poster, or null if no such image is
+     * available.
      */
     public Bitmap getDefaultVideoPoster() {
         return null;
     }
 
     /**
-     * Ask the host application for a custom progress view to show while
-     * a <video> is loading.
+     * When the user starts to playback a video element, it may take time for enough
+     * data to be buffered before the first frames can be rendered. While this buffering
+     * is taking place, the ChromeClient can use this function to provide a View to be
+     * displayed. For example, the ChromeClient could show a spinner animation.
      *
-     * @return View The progress view.
+     * @return View The View to be displayed whilst the video is loading.
      */
     public View getVideoLoadingProgressView() {
         return null;
diff --git a/tests/DumpRenderTree/src/com/android/dumprendertree/TestShellActivity.java b/tests/DumpRenderTree/src/com/android/dumprendertree/TestShellActivity.java
index c084f8c..aeb55b4 100644
--- a/tests/DumpRenderTree/src/com/android/dumprendertree/TestShellActivity.java
+++ b/tests/DumpRenderTree/src/com/android/dumprendertree/TestShellActivity.java
@@ -638,7 +638,7 @@ public class TestShellActivity extends Activity implements LayoutTestController
         }
 
         @Override
-        public void addMessageToConsole(String message, int lineNumber,
+        public void onConsoleMessage(String message, int lineNumber,
                 String sourceID) {
             if (mConsoleMessages == null) {
                 mConsoleMessages = new StringBuffer();