Promise的应用

Cruzr 大部分接口都提供了同步调用方式与异步调用方式，开发者可以根据不同场景灵活选用接口的调用方式。

Promise

Promise 是Cruzr 处理同步异步的一种方式，通过 Promise 设置监听实现接口异步调用，同时，通过 get 方法可以实现接口的同步方式。 Promise 的所有方法如下所示：

方法	说明
Promise.isPending()	当前是否处于等待结果状态
Promise.isResolved()	当前是否处于已经完成状态
Promise.isCanceled()	当前是否处于取消请求状态
Promise.isRejected()	当前是否处于请求失败状态
Promise.cancel()	取消请求
Promise.cancelled(CancelledCallback callback)	设置请求取消回调
Promise.done(DoneCallback<? super D> callback)	设置请求完成结果回调
Promise.fail(FailCallback<? super F> callback)	设置请求失败结果回调
Promise.always(AlwaysCallback<? super D, ? super F> callback)	设置请求结束回调，不论是否成功、失败或者取消
Promise.get()	同步获取请求结果，该方法会阻塞执行
Promise.getInterruptibly(long timeout, TimeUnit unit)	同步获取请求结果, 支持设置等待时间
Promise.getFail()	获取失败原因，该方法不会阻塞，只有失败后才会有具体值

对于部分有进度反馈的接口，Promise 子类 ProgressivePromise 提供了设置监听进度回调

方法	说明
ProgressivePromise.progress(ProgressCallback<? super P> callback)	设置请求进度回调

注：Promise所有回调均在主线程

异步调用

即非阻塞调用，异步调用通过接口返回的 Promise 对象设置回调监听完成。

单次回调

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

promise.done(new DoneCallback<UnderstandingResult>() {
    @Override
    public void onDone(UnderstandingResult understandingResult) {
        // 调用结果会返回到此处
    }
});

多次回调

部分接口带有进度反馈，可以通过 ProgressivePromise.progress()接收进度通知。

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

progressivePromise.progress(new ProgressCallback<RecognitionProgress>() {
    @Override
    public void onProgress(RecognitionProgress recognitionProgress) {
        // 调用过程会多次通知进度到此处
    }
}).done(new DoneCallback<RecognitionResult>() {
    @Override
    public void onDone(RecognitionResult recognitionResult) {
        // 调用结果会返回到此处
    }
}) ;

取消执行

取消请求只需要 promise 的 cancel方法即可， 并且会通知到 CancelledCallback

promise.cancel();

处理异常

promise.fail(new FailCallback<UnderstandingException>() {
    @Override
    public void onFail(UnderstandingException e) {
        // 调用异常会通知到此处
    }
});

同步调用

同步调用同样是通过 Promise 完成，与异步调用不同，同步调用的失败以及取消等操作将会以异常的形式通知，同样以调用语音识别为例，方法如下:

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

     RecognitionResult result = progressivePromise.get();// 此处会阻塞到结果返回或者异常
    } catch (RecognitionException e) {
        e.printStackTrace();// [1]
    } catch (CancelledException e) {
        e.printStackTrace();// [2]
    }

[1] 请求失败会抛出对应的异常

[2] 请求被取消执行会抛出 CancelledException

注：同步调用为阻塞方法，请避免在主线程使用， 并且无法获取进度的通知