am af9d60af: Merge "Address API feedback for PostMessage" into mnc-dev

* commit 'af9d60af0df4d1972a91bfbafd7d3a36424c4817':
  Address API feedback for PostMessage

api/current.txt

@@ -38801,7 +38801,6 @@ package android.webkit {
   }
 
   public abstract class WebMessagePort {
-    ctor public WebMessagePort();
     method public abstract void close();
     method public abstract void postMessage(android.webkit.WebMessage);
     method public abstract void setWebMessageCallback(android.webkit.WebMessagePort.WebMessageCallback);

core/java/android/webkit/WebMessagePort.java

@@ -16,12 +16,13 @@
 
 package android.webkit;
 
+import android.annotation.SystemApi;
 import android.os.Handler;
 
 /**
- * The Java representation of the HTML5 Message Port. See
- * https://html.spec.whatwg.org/multipage/comms.html#messageport
- * for definition of MessagePort in HTML5.
+ * The Java representation of the
+ * <a href="https://html.spec.whatwg.org/multipage/comms.html#messageport">
+ * HTML5 message ports.</a>
  *
  * A Message port represents one endpoint of a Message Channel. In Android
  * webview, there is no separate Message Channel object. When a message channel
@@ -32,6 +33,19 @@ import android.os.Handler;
  * When a message port is first created or received via transfer, it does not
  * have a WebMessageCallback to receive web messages. The messages are queued until
  * a WebMessageCallback is set.
+ *
+ * A message port should be closed when it is not used by the embedder application
+ * anymore. A closed port cannot be transferred or cannot be reopened to send
+ * messages. Close can be called multiple times.
+ *
+ * When a port is transferred to JS, it cannot be used to send or receive messages
+ * at the Java side anymore. Different from HTML5 Spec, a port cannot be transferred
+ * if one of these has ever happened: i. a message callback was set, ii. a message was
+ * posted on it. A transferred port cannot be closed by the application, since
+ * the ownership is also transferred.
+ *
+ * It is possible to transfer both ports of a channel to JS, for example for
+ * communication between subframes.
  */
 public abstract class WebMessagePort {
 
@@ -54,6 +68,13 @@ public abstract class WebMessagePort {
         public void onMessage(WebMessagePort port, WebMessage message) { }
     }
 
+    /**
+     * Constructor.
+     * @hide
+     */
+    @SystemApi
+    public WebMessagePort() { }
+
     /**
      * Post a WebMessage to the entangled port.
      *

core/java/android/webkit/WebView.java

@@ -1838,8 +1838,9 @@ public class WebView extends AbsoluteLayout
     /**
      * Creates a message channel to communicate with JS and returns the message
      * ports that represent the endpoints of this message channel. The HTML5 message
-     * channel functionality is described here:
-     * https://html.spec.whatwg.org/multipage/comms.html#messagechannel
+     * channel functionality is described
+     * <a href="https://html.spec.whatwg.org/multipage/comms.html#messagechannel">here
+     * </a>
      *
      * The returned message channels are entangled and already in started state.
      *
@@ -1853,11 +1854,14 @@ public class WebView extends AbsoluteLayout
     /**
      * Post a message to main frame. The embedded application can restrict the
      * messages to a certain target origin. See
-     *    https://html.spec.whatwg.org/multipage/comms.html#posting-messages
-     * for how target origin can be used.
+     * <a href="https://html.spec.whatwg.org/multipage/comms.html#posting-messages">
+     * HTML5 spec</a> for how target origin can be used.
      *
      * @param message the WebMessage
-     * @param targetOrigin the target origin.
+     * @param targetOrigin the target origin. This is the origin of the page
+     *          that is intended to receive the message. For best security
+     *          practices, the user should not specify a wildcard (*) when
+     *          specifying the origin.
      */
     public void postMessageToMainFrame(WebMessage message, Uri targetOrigin) {
         checkThread();