Promise

A lightweight promise library for Java 6+ for method-count restricted environments.

Inspired by https://github.com/linkedin/parseq.

~32 KB jar.
Zero dependencies.
Java 6+ & Android 2.3+.
Non-opinionated schedulers.
Async or synchronous execution.
Cancellation as a first-class concept.
firstCompletedOf(), whenAll(), zip().

Downloads

Maven

<dependency>
  <groupId>com.github.jparkie</groupId>
  <artifactId>promise</artifactId>
  <version>1.0.3</version>
</dependency>

Gradle

compile 'com.github.jparkie:promise:1.0.3'

Optional Classes

For 1.0.3, 65 of 147 counted methods are required methods. Thus, this library only takes 0.1% of the 64K method DEX limit for Android application without Multidex.

As a lightweight promise library, the following packages can be omitted:

Usages

Refer to https://github.com/jparkie/Promise/tree/master/src/test/java/com/github/jparkie/promise for more.

Creating Promises

final Promise<String> lazyPromise = Promises.promise();
final Promise<String> valuePromise = Promises.value("Hello World.");
final Promise<String> errorPromise = Promises.error(new NoSuchElementException());
final Promise<String> eagerPromise = Promises.create(
        Schedulers.newSimpleScheduler(),
        new Action<String>() {
            @Override
            public void call(Promise<String> promise) {
                promise.set("Hello World.");
            }

            @Override
            public void cancel() {
                System.out.println("Cancelled.");
            }
        });

Resolving Promises

final Promise<String> promise = Promises.promise();
// Method 1:
promise.set("Hello World.");
// Method 2:
promise.setError(new NoSuchElementException());

Awaiting on Promises

final Promise<String> promise = Promises.promise();

promise.set("Hello World.");

try {
    promise.await();
    // Console Output: Hello World.
    System.out.println(promise.get());
} catch (InterruptedException e) {
    e.printStackTrace();
}

Listening to Promises

final Promise<String> promise = Promises.promise();
promise.then(Schedulers.newSimpleScheduler(), new Action<String>() {
    @Override
    public void call(Promise<String> promise) {
        if (promise.isSuccessful()) {
            // Console Output: Hello World.
            System.out.println(promise.get());
        } else {
            promise.getError().printStackTrace();
        }
    }

    @Override
    public void cancel() {
        System.out.println("Cancelled.");
    }
});

promise.set("Hello World.");

Transforming Promises

final Promise<String> promise = Promises.promise();
final Promise<String> transformedPromise = promise
        .then(Schedulers.newSimpleScheduler(), new Function<String, String>() {
            @Override
            public Promise<String> call(Promise<String> promise) {
                return Promises.value("Transform 1.");
            }
        })
        .then(Schedulers.newSimpleScheduler(), new Function<String, String>() {
            @Override
            public Promise<String> call(Promise<String> promise) {
                return Promises.value("Transform 2.");
            }
        })
        .then(Schedulers.newSimpleScheduler(), new Function<String, String>() {
            @Override
            public Promise<String> call(Promise<String> promise) {
                return Promises.value("Transform 3.");
            }
        });

promise.set("Hello World.");

try {
    transformedPromise.await();
    // Console Output: Transform 3.
    System.out.println(promise.get());
} catch (InterruptedException e) {
    e.printStackTrace();
}

Cancelling Promises

final Promise<String> promise = Promises.promise();
promise.then(Schedulers.newSimpleScheduler(), new Action<String>() {
    @Override
    public void call(Promise<String> promise) {
        if (promise.isSuccessful()) {
            System.out.println(promise.get());
        } else {
            promise.getError().printStackTrace();
        }
    }

    @Override
    public void cancel() {
        System.out.println("Cancelled.");
    }
});

promise.cancel();

// The then() Action<String> is never called.

Extras

The following functions are included in the ExtraPromises class. Refer to the following for more information about their semantics: https://github.com/jparkie/Promise/blob/master/src/main/java/com/github/jparkie/promise/extras/ExtraPromises.java.

firstCompletedOf()

final Promise<String> firstPromise = Promises.promise();
final Promise<String> secondPromise = Promises.promise();
final Promise<String> thirdPromise = Promises.promise();
final Promise<String> firstCompletedOfPromise = ExtraPromises.firstCompletedOf(
        Schedulers.newSimpleScheduler(),
        firstPromise,
        secondPromise,
        thirdPromise);

whenAll()

final Promise<String> firstPromise = Promises.promise();
final Promise<Integer> secondPromise = Promises.promise();
final Promise<Boolean> thirdPromise = Promises.promise();
final Promise<Void> whenAllPromise = ExtraPromises.whenAll(
        Schedulers.newSimpleScheduler(),
        firstPromise,
        secondPromise,
        thirdPromise);

zip()

final Promise<String> leftPromise = Promises.promise();
final Promise<Integer> rightPromise = Promises.promise();
final Promise<Pair<String, Integer>> zipPromise = ExtraPromises.zip(
        Schedulers.newSimpleScheduler(),
        leftPromise,
        rightPromise);

Build

$ git clone https://github.com/jparkie/Promise.git
$ cd Promise/
$ ./gradlew build