Java Promise 中文 Wiki 帮助 API 文档

发布于 2021-01-12 09:59:48 字数 8759 浏览 957 评论 0

Promise 规范

Promise 规范可以参考 Promise A+规范。其中 ES6 Promise对象 在 Promise A+ 规范上做了一些补充。Java Promise 在使用上基本与 ES6 Promise 对象保持一致,部分地方有些许不同,后面会做出说明。 Promise 的三个状态

  • pending:等待态,对应线程未执行或执行中
  • fulfilled:完成态,对应线程正常执行完毕,其执行结果称为终值
  • rejected:拒绝态,对应线程异常结束,其异常原因称为拒因
    状态转移只能由pending->fulfilled或pending->rejected,状态一旦发生转移无法再次改变。

Promise

Promise 是 IPromise 的实现,Promise 实例一经创建,将立即异步执行,部分接口如下

IPromise then(OnFulfilledExecutor onFulfilledExecutor, OnRejectedExecutor onRejectedExecutor)

  • 如果当前 promise 处于 pending 状态,阻塞当前线程,等待 promise 状态转变为 fulfilled 或 rejected
  • 如果处于 fulfilled 状态,执行 onFulfilledExecutor.onFulfilled(resolvedData) 回调。
    • 如果回调返回一个 Promise 对象a,以a作为then方法的返回值,如果回调返回一个普通对象obj,以obj作为终值、状态为fulfilled包装一个新Promise 作为 then 方法的返回值
    • 如果执行回调过程中产生异常e,返回一个以e作为拒因、状态为rejected的新Promise,并拒绝执行接下来的所有Promise直到遇到pCatch。
  • 如果处于rejected状态,执行onRejectedExecutor.onRejected(rejectReason)回调,返回一个以当前promise的异常作为拒因、状态为rejected的新Promise,并拒绝执行接下来的所有Promise直到遇到pCatch或pFinally
    参数:

IPromise pCatch(OnCatchedExecutor onCatchedExecutor);

then(null,onRejectedExecutor)的别名,但返回不同于then,出现异常时可以选择不拒绝接下来Promise的执行,可用于异常修正,类似于try{}catch{}
该方法会尝试捕获当前promise的异常,最终返回一个新Promise,当被捕获Promise处于不同的状态时有不同的行为

  • pending:阻塞当前线程,等待pending转变为fulfilled或rejected,行为同then
  • fulfilled:不执行回调,以当前Promise终值和状态返回一个全新的Promise
  • rejected:执行onCatched(Throwable catchReason)回调。
    • 如果onCatched方法返回一个Promise,以这个Promise作为最终返回。
    • 如果onCatched方法返回一个非Promise对象obj,以obj作为终值、fulfilled状态返回一个全新的对象。
    • 如果执行回调过程中产生异常e,以e为拒因、状态为rejected返回一个新的Promise,并拒绝执行接下来的所有Promise直到再次遇到pCatch

void listen(OnCompleteListener onCompleteListener);

指定一个监听器,在promise状态转为fulfilled或rejected调用,该方法不会阻塞线程执行,可以多次调用指定多个监听器

void pFinally(OnCompleteListener onCompleteListener);

listen 的别名,行为同listen

Status getStatus()

获取promise的当前状态

Object getResolvedData()

获取promise fulfilled状态下的终值,其余状态下时为null

Throwable getRejectedData()

获取promise rejected状态下的拒因,其余状态下为null

Future getFuture()

获取promise对应异步任务的future

boolean cancel()

尝试取消promise对应的异步任务,底层调用future.cancel(true)。fulfilled或rejected状态下无效。

Promise.Builder

Promise对象生成器

Builder pool(ExecutorService threadPool)

指定一个线程池用于执行promise任务,如果不指定,每一个promise都将启动一个线程

Builder promiseHanler(PromiseHandler promiseExecutor)

指定promise执行器,在promiseHanler的run方法中实现线程的具体业务逻辑,注意==promise对象一经创建,将立即执行其中的逻辑==

Builder externalInput(Object externalInput)

向Promise注入一个外部参数,可以在指定PromiseHandler时通过PromiseExecutor.getExternalInput()获取

int i = 3;
IPromise p = new Promise.Builder()
.externalInput(i).promiseHanler(new PromiseHandler() {
  public Object run(PromiseExecutor executor) {
    Integer args = (Integer) executor.getExternalInput();
    return args*2;
  }
}).build();

Builder promise(IPromise promise)

指定一个promise x,使当前promise接受 x 的状态

  • 如果 x 处于pending, 当前promise 需保持为pending直至 x 转为fulfilled或rejected
  • 如果 x 处于fulfilled,用x的终值值执行当前promise,可以在指定PromiseHandler时通过PromiseExecutor.getPromiseInput()获取
  • 如果 x 处于拒绝态,用相同的据因拒绝当前promise执行
ExecutorService fixedPool = Promise.pool(1);
IPromise promise1 = new Promise.Builder().pool(fixedPool).promiseHanler(executor->3).build();
IPromise promise2 = new Promise.Builder().pool(fixedPool)
  .promise(promise1)
  .promiseHanler(executor->4+(Integer) executor.getPromiseInput())
.build()
.then(resolvedData->{
  System.out.println(resolvedData);
  return resolvedData;
}, rejectedReason-> rejectedReason.printStackTrace());

最终结果返回7,。如果promise1在执行过程中抛出异常e,promise2将被拒绝执行,将会以e作为拒因,状态为rejected返回一个新的Promise,最终会执行rejectedReason-> rejectedReason.printStackTrace()回调。

IPromise build()

创建一个Promise实例

Promise 的静态方法

static IPromise all(IPromise ...promises)

将多个 Promise 实例p1,...pn,包装成一个新的 Promise 实例 p,只有当p1-pn的状态都转为fulfilled时,p的状态才为fulfilled,此时p1-pn的返回值包装为一个数组Object[r1,...rn]作为p的终值。
只要p1-pn中任意一个被rejected,p的状态就转为rejected,将第一个被rejected的promise的拒因作为p的拒因,并尝试取消其余promise的执行(内部调用future.cancel(true))

static IPromise waitAll(IPromise ...promises)

将多个 Promise 实例p1,...pn,包装成一个新的 Promise 实例 p,等待p1-pn的状态全部转为fulfilled或rejected,p的状态转为fulfilled,将p1-pn的终值包装为一个数组Object[r1,...rn]作为p的终值。r1...rn的值取决于p1...pn的最终状态。假如p2异常结束,那么r2为一个throwable实例。不同于all,即便只要p1-pn中任意一个被rejected,p都会等待全部的promise执行完成

static IPromise race(IPromise ...promises)

将多个 Promise p1,...pn实例,包装成一个新的 Promise 实例 p,只要p1-pn有一个状态发生改变,p的状态立即改变。并尝试取消其余promise的执行(内部调用future.cancel(true))
第一个改变的promise的状态和数据作为p的状态和数据

static IPromise resolve()

创建一个终值为null、fulfilled状态的promise

static IPromise resolve(Object object)

创建一个终值为object、fulfilled状态的promise

static IPromise resolve(Object object,List args)

将object的then方法以异步方式执行,then方法的执行结果作为Promise的终值

static IPromise resolve(Object object,String methodName,List args)

将object的指定方法以异步方式执行,该方法的执行结果作为Promise的终值,目标方法的参数必须按顺序包含在List中,如object.doSomething(int a,Map b),用resolve执行为

List args = new ArrayList()
args.add(1);
args.add(map)
Promise.resolve(object,"doSomething",args);

static IPromise reject(Object reason)

创建一个拒因为reason、rejected状态的promise

static IPromise pTry(Object object,String methodName,List args)

将object的指定方法以同步方式执行,该方法的执行结果作为Promise的终值,如果object为IPromise实例,将忽略methodName和args参数,异步执行该实例。

该方法是以Promise统一处理同步和异步方法,不管object是同步操作还是异步操作,都可以使用then指定下一步流程,用pCatch方法捕获异常,避免开发中出现以下情况

try{
  object.doSomething(args1,args2);//可能会抛出异常
  promise.then(resolvedData->{
    //一些逻辑
  }).then(resolvedData->{
    //一些逻辑
  }).pCatch(e->{
    //异常处理逻辑
  })
}catch(Exception e){
  //异常处理逻辑
}

使用pTry,可以简化异常处理

List args = new ArrayList(){args1,args2};
Promise.pTry(object,"doSomething",args)
.then(resolvedData->{
    //一些逻辑
}).then(resolvedData->{
  //一些逻辑
}).pCatch(e->{
  //异常处理逻辑
})

PromiseHandler

定义异步逻辑的接口

Object run(PromiseExecutor executor)throws Exception;

run方法中实现具体的业务逻辑,最终run方式是在线程的call方法执行,如果run方法中含有wait、sleep...等锁操作,可能需要自行处理InterruptedException。因为该线程可能被外部调用cancel()或interrupt()方法

PromiseExecutor

promise 状态处理

void resolve(final Object args)

将Promise对象的状态从“未完成”变为“成功”(即从pending变为fulfilled)。注意该方法一经调用,promise状态将不可改变,如下例,在调用executor.resolve(3);后,return之前抛出一个异常,promise的状态依旧是fulfilled,终值为3。

new Promise.Builder().promiseHanler(new PromiseHandler(){
  @Override
  public Object run(PromiseExecutor executor) {
    executor.resolve(3);
    throw new RuntimeException("error");
    return null;
  }
}).build()

在run方法中executor.resolve(3)等同于return 3

@Override
public Object run(PromiseExecutor executor) {
  return 3;
}

大多数情况下建议直接使用return返回promise的终值。

void reject(final Throwable args)

将Promise对象的状态从“未完成”变为“失败”(即从pending变为fulfilled)

Object getExternalInput()

获取通过 new Promise.Builder().externalInput(Object externalInput) 方法注入的参数,具体参考 Promise.Builder#externalInput(Object externalInput)

Object getPromiseInput()

获内部promise的执行结果。通过new Promise.Builder().promise(promise1)指定的promise1的执行结果。具体参考 Promise.Builder#promise(IPromise promise)

OnFulfilledExecutor

fulfilled 回调接口

Object onFulfilled(Object resolvedData)throws Exception;

状态转为fulfilled时的回调,返回值可以是IPromise实例或普通对象。如果object是IPromise实例,object作为then方法的返回值,如果object是个普通对象,以object作为终值、状态为fulfilled包装一个新Promise作为then方法的返回值

OnRejectedExecutor

rejected 回调接口

void onRejected(Throwable rejectReason)throws Exception;

当Promise转变为rejected状态时的回调

OnCatchedExecutor

rejected回调接口

Object onCatched(Throwable catchReason)throws Exception;

当发生异常时的回调,最终返回一个Promise或普通对象,如果是一个普通对象,这个对象将作为下一个Promise的终值

OnCompleteListener

void listen(Object resolvedData,Throwable e);

当Promise执行结束时的回调(无论是fulfilled还是rejected)

  • resolvedData fulfilled状态时的终值,rejected状态时为null
  • e rejected状态时的异常信息,fulfilled状态时为null

项目地址:https://github.com/zhanyingf15/promise

如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。

扫码二维码加入Web技术交流群

发布评论

需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

列表为空,暂无数据

关于作者

JSmiles

生命进入颠沛而奔忙的本质状态,并将以不断告别和相遇的陈旧方式继续下去。

0 文章
0 评论
84935 人气
更多

推荐作者

遥远的她

文章 0 评论 0

情深如许

文章 0 评论 0

18120987591

文章 0 评论 0

女皇必胜

文章 0 评论 0

13002228876

文章 0 评论 0

    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击“接受”或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。