Skip to content

Clarifications to Promises implementation (mostly documentation). #189

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
joeferner merged 1 commit into from
Jan 15, 2015
Merged

Clarifications to Promises implementation (mostly documentation). #189

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 9 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
27 changes: 15 additions & 12 deletions testHelpers.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;