How to use promise

Most of the interfaces of Cruzr provide synchronous and asynchronous calling methods. Developers can flexibly choose the calling method of the interface according to different scenarios.

Promise

Promise is a Class which provide synchronous and asynchronous interfaces. The listening is set throughPromise to implement the asynchronous calling of the interface. The getmethod can be used to implement synchronous calls to the interface. All the calling methods of Promise are shown as follows:

Methods	Descriptions
Promise.isPending()	If it is in the status of waiting for results
Promise.isResolved()	If it is in completed state
Promise.isCanceled()	If it is currently in cancel request state
Promise.isRejected()	If Promise's request failed.
Promise.cancel()	Cancel the request
Promise.cancelled(CancelledCallback callback)	Promise requests to cancel the callback
Promise.done(DoneCallback<? super D> callback)	Promise requests to complete the callback
Promise.fail(FailCallback<? super F> callback)	Promise requests to callback the result of the failure
Promise.always(AlwaysCallback<? super D, ? super F> callback)	Promise requests to finish the callback, no matter if it is successful, fails, or is cancelled.
Promise.get()	Get the request result synchronously. This method will block the execution.
Promise.getInterruptibly(long timeout, TimeUnit unit)	Get the request result synchronously. This method supports Promise to wait.
Promise.getFail()	Get the reason for the failure. This method will not block execution, a specific value will only be given after it fails.

For some interfaces with progress feedback, ProgressivePromise，a subclass of Promise ，can be used to set the listening progress callback.

Methods	Descriptions
ProgressivePromise.progress(ProgressCallback<? super P> callback)	Promise requests to callback the progress.

Note: All callbacks of Promise are on the main thread.

Asynchronous call

This means non-blocking call. Asynchronous calls complete the callback listening through the Promise object returned by the interface.

Single callback

Promise<UnderstandingResult, UnderstandingException> promise =
                speechManager.understand("what's the weather.");

promise.done(new DoneCallback<UnderstandingResult>() {
    @Override
    public void onDone(UnderstandingResult understandingResult) {
        // The result of the callback will be returned here
    }
});

Multiple callbacks

Some interfaces have progress feedback, and progress notifications can be received through ProgressivePromise.progress ().

ProgressivePromise<RecognitionResult, RecognitionException, RecognitionProgress>
                progressivePromise = speechManager.recognize();

progressivePromise.progress(new ProgressCallback<RecognitionProgress>() {
    @Override
    public void onProgress(RecognitionProgress recognitionProgress) {
        // The progress of the callback will be returned here
    }
}).done(new DoneCallback<RecognitionResult>() {
    @Override
    public void onDone(RecognitionResult recognitionResult) {
        // The result of the callback will be returned here
    }
}) ;

Cancel the execution

To cancel the request, just follow the cancel method of promise. The notification will be sent to CancelledCallback.

promise.cancel();

Exceptional handling

promise.fail(new FailCallback<UnderstandingException>() {
    @Override
    public void onFail(UnderstandingException e) {
        // Any exceptions in the callback will be notified here
    }
});

Synchronous call

Unlike asynchronous calls, operations such as failure and cancellation of synchronous calls will be notified in the form of exceptions. We still use the call of speech recognition as an example. The method is as follows:

 try {
     ProgressivePromise<RecognitionResult, RecognitionException, RecognitionProgress>
                progressivePromise = speechManager.recognize();

     RecognitionResult result = progressivePromise.get();// This will block the return of the result or an exception
    } catch (RecognitionException e) {
        e.printStackTrace();// [1]
    } catch (CancelledException e) {
        e.printStackTrace();// [2]
    }

[1] If the request failed, the corresponding exception will be returned.

[2] If the request is canceled, CancelledException will be returned.

Note: Synchronous call is a blocking method. Please avoid using it in the main thread, and you cannot get notifications of the progress.