Merge pull request joeferner#189 from jimlloyd/feature/promises-clarifications.r1

joeferner · joeferner · commit cecac70d7bd3 · 2015-01-15T14:54:14.000-05:00
Clarifications to Promises implementation (mostly documentation).
diff --git a/README.md b/README.md
@@ -156,38 +156,27 @@ Example:
 ```javascript
 var java = require("java");
 java.asyncOptions = {
-  promiseSuffix: 'Promise',
-  promisify: require('when/node').lift
+  promiseSuffix: "Promise",
+  promisify: require("when/node").lift
 };
 java.classpath.push("commons-lang3-3.1.jar");
 java.classpath.push("commons-io.jar");
 
+java.import("java.util.ArrayList"); // see NOTE below
+
 java.newInstancePromise("java.util.ArrayList")
     .then(function(list) { return list.addPromise("item1"); })
     .then(function(list) { return list.addPromise("item2"); })
     .catch(function(err) { /* handle error */ });
 ```
 
-* If you don't need promise-returning methods, simply leave java.asyncOptions unset.
+* If you don't want promise-returning methods, simply leave `java.asyncOptions` unset.
 * Sync and standard async methods are still generated as in previous releases. In the future we may provide the option to disable generation of standard async methods.
-* You are free to choose whatever non-empty suffix you want for the promise-returning methods, but you must specify a value.
-* asyncOptions.promisify must be a function that given a node.js style async function as input returns a function that returns a promise that is resolved (or rejected) when the async function has completed. Several Promises libraries provide such functions. This *should* just work, but at the moment one prominent promises library doesn't.
-* Note that it should be possible to mix use of two different Promises/A+ conforming libraries. You may be able to use one library for installing the asyncOptions.promisify function, and then use another library everywhere else in your application.
-
-#### Tested Promises Libraries
-
-##### [when](https://www.npmjs.com/package/when)
-We use this package in our unit tests, and it passes under all 9 cases of our [test matrix](https://travis-ci.org/joeferner/node-java).
-
-`promisify: require('when/node').lift`
-
-##### [bluebird](https://www.npmjs.com/package/bluebird)
-Does not work with node 0.8, but works with node 0.10 and 0.11.
-
-`promisify: require('bluebird').promisify`
+* `asyncOptions.promisify` must be a function that given a node.js style async function as input returns a function that returns a promise that is resolved (or rejected) when the async function has completed. Several Promises/A+ libraries provide such functions, but it may be necessary to provide a wrapper function. See `testHelpers.js` for an example.
+* You are free to choose whatever non-empty `promiseSuffix` you want for the promise-returning methods, but you must specify a value.
+* We've tested with five Promises/A+ implementations. See `testHelpers.js` for more information.
+* NOTE: Due to specifics of initialization order, the methods  `java.newInstancePromise`, `java.callMethodPromise`, and `java.callStaticMethodPromise` are not available until some other java method is called. You may need to call some other java method such as `java.import()` to finalize java initialization.
 
-##### [Q](https://www.npmjs.com/package/q)
-Unfortunately, the popular Q promises library currently does **NOT** work.
 
 # Release Notes
 
diff --git a/testHelpers.js b/testHelpers.js
@@ -6,21 +6,24 @@ java.classpath.push("test/");
 java.classpath.push("test/commons-lang3-3.1.jar");
 java.classpath.push("test8/");
 
+function promisifyQ(f) {
+  // Q doesn't provide a promisify function that works directly on a method.
+  // The .denodeify() (aka .nfbind()) function requires a bound function.
+  return function(/* arguments */) {
+    return require('q').nbind(f, this).apply(undefined, arguments);
+  }
+}
+
 java.asyncOptions = {
   promiseSuffix: 'Promise',
-  promisify: require('when/node').lift         // when works with all three node versions
-
-// PASSES in all three node versions: 0.8.28, 0.10.35, 0.11.14
-//   promisify: require('when/node').lift         // when works with all three node versions
-//   promisify: require('promise').denodeify      // promise works with all three node versions
-//   promisify: require('vow-node').promisify     // vow-node works with all three node versions
-
-// PASSES in Node 0.10, 0.11.   (incompatible with Node 0.8).
-//   promisify: require('bluebird').promisify     // bluebird requires node >=0.10
+  promisify: require('when/node').lift         // https://github.com/cujojs/when
 
-// FAILS:
-//   promisify: require('q').denodeify            // FAILS: Q triggers assertion failure in node_object_wrap.h, line 61
-//   promisify: require('p-promise').denodeify    // FAILS: P-promise does not implement catch().
+// We've tested with 5 different Promises/A+ implementations:
+//   promisify: require('bluebird').promisify     // https://github.com/petkaantonov/bluebird/
+//   promisify: require('promise').denodeify      // https://github.com/then/promise
+//   promisify: require('vow-node').promisify     // https://github.com/dfilatov/vow-node
+//   promisify: require('when/node').lift         // https://github.com/cujojs/when
+//   promisify: promisifyQ                        // https://github.com/kriskowal/q requires wrapper promisifyQ.
 };
 
 module.exports.java = java;
