Bug 995820 - Add more docs for JavascriptBridge
authorJim Chen <nchen@mozilla.com>
Tue, 15 Apr 2014 10:54:00 -0700
changeset 197244 90a54293fd84129c15127ac31ef952f2f178b9ad
parent 197243 a6ed5860261f4ab6eafdf42eeb1fb10b42b7707d
child 197245 b73ad6f8bf2618b8e9b077e1839c3c30f4d1aae6
push id3624
push userasasaki@mozilla.com
push dateMon, 09 Jun 2014 21:49:01 +0000
treeherdermozilla-beta@b1a5da15899a [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
bugs995820
milestone31.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 995820 - Add more docs for JavascriptBridge
mobile/android/base/tests/helpers/JavascriptBridge.java
--- a/mobile/android/base/tests/helpers/JavascriptBridge.java
+++ b/mobile/android/base/tests/helpers/JavascriptBridge.java
@@ -13,19 +13,51 @@ import org.json.JSONArray;
 import org.json.JSONException;
 import org.json.JSONObject;
 
 import org.mozilla.gecko.Actions;
 import org.mozilla.gecko.Actions.EventExpecter;
 import org.mozilla.gecko.Assert;
 import org.mozilla.gecko.tests.UITestContext;
 
-
 /**
- * Javascript bridge allows calls to and from Javascript.
+ * Javascript bridge allows calls to and from JavaScript.
+ *
+ * To establish communication, create an instance of JavascriptBridge in Java and pass in
+ * an object that will receive calls from JavaScript. For example:
+ *
+ *  {@code final JavascriptBridge js = new JavascriptBridge(javaObj);}
+ *
+ * Next, create an instance of JavaBridge in JavaScript and pass in another object
+ * that will receive calls from Java. For example:
+ *
+ *  {@code let java = new JavaBridge(jsObj);}
+ *
+ * Once a link is established, calls can be made using the methods syncCall and asyncCall.
+ * syncCall waits for the call to finish before returning. For example:
+ *
+ *  {@code js.syncCall("abc", 1, 2, 3);} will synchronously call the JavaScript method
+ *    jsObj.abc and pass in arguments 1, 2, and 3.
+ *
+ *  {@code java.asyncCall("def", 4, 5, 6);} will asynchronously call the Java method
+ *    javaObj.def and pass in arguments 4, 5, and 6.
+ *
+ * Supported argument types include int, double, boolean, String, and JSONObject. Note
+ * that only implicit conversion is done, meaning if a floating point argument is passed
+ * from JavaScript to Java, the call will fail if the Java method has an int argument.
+ *
+ * Because JavascriptBridge and JavaBridge use one underlying communication channel,
+ * creating multiple instances of them will not create independent links.
+ *
+ * Note also that because Robocop tests finish as soon as the Java test method returns,
+ * the last call to JavaScript from Java must be a synchronous call. Otherwise, the test
+ * will finish before the JavaScript method is run. Calls to Java from JavaScript do not
+ * have this requirement. Because of these considerations, calls from Java to JavaScript
+ * are usually synchronous and calls from JavaScript to Java are usually asynchronous.
+ * See testJavascriptBridge.java for examples.
  */
 public final class JavascriptBridge {
 
     private static enum MessageStatus {
         QUEUE_EMPTY, // Did not process a message; queue was empty.
         PROCESSED,   // A message other than sync was processed.
         REPLIED,     // A sync message was processed.
         SAVED,       // An async message was saved; see processMessage().