WeCross Java SDK API

SDK API分为两大类型，一种是RPC接口，一种是资源接口，其中资源接口是对RPC接口进行了封装。

API列表

  • RPC接口

    RemoteCall supportedStubs();

    RemoteCall listAccounts();

    RemoteCall listResources(Boolean ignoreRemote);

    RemoteCall detail(String path);

    RemoteCall call(Request request);

    RemoteCall call(String path, String account, String method, String… args);

    RemoteCall sendTransaction(Request request);

    RemoteCall sendTransaction(String path, String account, String method, String… args);

    RemoteCall callTransaction(String transactionID, String path, String account, String method, String… args);

    RemoteCall execTransaction(String transactionID,String seq, String path, String account, String method, String… args);

    RemoteCall startTransaction(String transactionID, String[] accounts, String[] paths);

    RemoteCall commitTransaction(String transactionID, String[] accounts, String[] paths);

    RemoteCall rollbackTransaction(String transactionID, String[] accounts, String[] paths);

    RemoteCall getTransactionInfo(String transactionID, String[] accounts, String[] paths);

    RemoteCall customCommand(String command, String path, String account, Object… args);

    RemoteCall getTransactionIDs(String path, String account, int option);

  • 资源接口

    Resource ResourceFactory.build(WeCrossRPC weCrossRPC, String path, String account)

    boolean isActive();

    ResourceDetail detail();

    TransactionResponse call(Request request);

    String[] call(String method);

    String[] call(String method, String… args);

    TransactionResponse sendTransaction(Request request);

    String[] sendTransaction(String method);

    String[] sendTransaction(String method, String… args);

RPC接口解析

supportedStubs

显示router当前支持的插件列表。

参数

  • 无

返回值

  • StubResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: Stubs - 支持的插件列表

java示例

  1.     // 初始化RPC实例
  2.     WeCrossRPCService weCrossRPCService = new WeCrossRPCService();
  3.     WeCrossRPC weCrossRPC = WeCrossRPCFactory.build(weCrossRPCService);
  5.     // 调用RPC接口，目前只支持同步调用
  6.     StubResponse response = weCrossRPC.supportedStubs().send();

注 - 之后的java示例，会省去初始化WeCrossRPC的步骤。

listAccounts

显示所有已配置的账户列表。

参数

  • 无

返回值

  • AccountResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: Accounts - 配置的账户列表

java示例

  1.     AccountResponse response = weCrossRPC.listAccounts().send();

listResources

显示router配置的跨链资源。

参数

  • ignoreRemote: Boolean - 是否忽略远程资源

返回值

  • ResourceResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: Resources - 配置的资源列表

java示例

  1.     ResourceResponse response = weCrossRPC.listResources(true).send();

detail

获取资源详情。

参数

  • path: String - 跨链资源标识

返回值

  • ResourceDetailResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: ResourceDetail - 资源详情

java示例

  1.     ResourceDetailResponse response = weCrossRPC.detail("payment.bcos.HelloWeCross").send();

call(无参数)

调用智能合约，不更改链状态，不发交易。

参数

  • path: String - 跨链资源标识
  • account: String - 账户名
  • method: String - 调用的方法

返回值

  • TransactionResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: Receipt - 调用结果

java示例

  1.     TransactionResponse transactionResponse =
  2.         weCrossRPC
  3.             .call(
  4.                 "payment.bcos.HelloWeCross","get")
  5.             .send();

call(带参数)

调用智能合约，不更改链状态，不发交易。

参数

  • path: String - 跨链资源标识
  • account: String - 账户名
  • method: String - 调用的方法
  • args : String... - 可变参数列表

返回值

  • TransactionResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: Receipt - 调用结果

java示例

  1.     TransactionResponse transactionResponse =
  2.         weCrossRPC
  3.             .call(
  4.                 "payment.bcos.HelloWeCross","get","key")
  5.             .send();

sendTransaction(无参数)

调用智能合约，会改变链状态，发交易。

参数

  • path: String - 跨链资源标识
  • account: String - 账户名
  • method: String - 调用的方法

返回值

  • TransactionResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: Receipt - 调用结果

java示例

  1.     TransactionResponse transactionResponse =
  2.         weCrossRPC
  3.             .sendTransaction(
  4.                 "payment.bcos.HelloWeCross","set")
  5.             .send();

sendTransaction(带参数)

调用智能合约，会改变链状态，发交易。

参数

  • path: String - 跨链资源标识
  • account: String - 账户名
  • method: String - 调用的方法
  • args : String... - 可变参数列表

返回值

  • TransactionResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: Receipt - 调用结果

java示例

  1.     TransactionResponse transactionResponse =
  2.         weCrossRPC
  3.             .sendTransaction(
  4.                 "payment.bcos.HelloWeCross","set","value")
  5.             .send();

callTransaction

获取事务中的状态数据，不发交易

参数

  • transactionID:String - 事务ID
  • path: String - 跨链资源标识
  • account: String - 账户名
  • method: String - 调用的方法
  • args : String... - 可变参数列表

返回值

  • TransactionResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: Receipt - 调用结果

java示例

  1.     TransactionResponse transactionResponse =
  2.         weCrossRPC
  3.             .callTransaction(
  4.                 "0001","payment.bcos.2pc","queryEvidence","key1")
  5.             .send();

execTransaction

执行事务，发交易

参数

  • transactionID:String - 事务ID
  • seq:String - 事务序列号，需递增
  • path: String - 跨链资源标识
  • account: String - 账户名
  • method: String - 调用的方法
  • args : String... - 可变参数列表

返回值

  • TransactionResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: Receipt - 调用结果

java示例

  1.     TransactionResponse transactionResponse =
  2.         weCrossRPC
  3.             .execTransaction(
  4.                 "0001","1","payment.bcos.2pc","newEvidence","key1","evidence1")
  5.             .send();

startTransaction

开始事务，锁定事务相关资源，发交易

参数

  • transactionID:String - 事务ID
  • accounts:String[] - 账户列表，每条链需要一个发交易的账户
  • paths: String[] - 跨链资源列表

返回值

  • RoutineResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: int - 调用结果

java示例

  1.     RoutineResponse routineResponse =
  2.         weCrossRPC
  3.             .startTransaction(
  4.                 "0001", new String[]{"bcos_user1","fabric_user1"}, new String[]{"payment.bcos.2pc", "payment.fabric.2pc"},)
  5.             .send();

commitTransaction

提交事务，释放事务相关资源，发交易

参数

  • transactionID:String - 事务ID
  • accounts:String[] - 账户列表，每条链需要一个发交易的账户
  • paths: String[] - 跨链资源列表

返回值

  • RoutineResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: int - 调用结果

java示例

  1.     RoutineResponse routineResponse =
  2.         weCrossRPC
  3.             .commitTransaction(
  4.                 "0001", new String[]{"bcos_user1","fabric_user1"}, new String[]{"payment.bcos.2pc", "payment.fabric.2pc"},)
  5.             .send();

rollbackTransaction

回滚事务，释放事务相关资源，发交易

参数

  • transactionID:String - 事务ID
  • accounts:String[] - 账户列表，每条链需要一个发交易的账户
  • paths: String[] - 跨链资源列表

返回值

  • RoutineResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: int - 调用结果

java示例

  1.     RoutineResponse routineResponse =
  2.         weCrossRPC
  3.             .rollbackTransaction(
  4.                 "0001", new String[]{"bcos_user1","fabric_user1"}, new String[]{"payment.bcos.2pc", "payment.fabric.2pc"},)
  5.             .send();

getTransactionInfo

获取事务详情，不发交易

参数

  • transactionID:String - 事务ID
  • accounts:String[] - 账户列表，每条链需要一个发交易的账户
  • paths: String[] - 跨链资源列表

返回值

  • RoutineInfoResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: String - 事务信息

java示例

  1.     RoutineInfoResponse routineInfoResponse =
  2.         weCrossRPC
  3.             .getTransactionInfo(
  4.                 "0001", new String[]{"bcos_user1","fabric_user1"}, new String[]{"payment.bcos.2pc", "payment.fabric.2pc"},)
  5.             .send();

getTransactionIDs

获取事务ID列表，不发交易

参数

  • path: String - 跨链资源标识
  • account: String - 账户名
  • option: int - 选项，0全部事务，1已完成的事务，2未完成的事务

返回值

  • RoutineIDResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: String[] - 事务ID列表

java示例

  1.     RoutineIDResponse routineIDResponse =
  2.         weCrossRPC
  3.             .getTransactionIDs(
  4.                 "payment.bcos.2pc", "bcos_user1", 0)
  5.             .send();

customCommand

自定义命令

参数

  • command: String - 命令名称
  • path: String - 跨链资源标识
  • account: String - 账户名
  • args: Object... - 可变参数

返回值

  • CommandResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: String - 调用结果

java示例

  1.     CommandResponse commandResponse =
  2.         weCrossRPC
  3.             .customCommand(
  4.                 "deploy", "payment.bcos.2pc", "bcos_user1")
  5.             .send();

资源接口解析

ResourceFactory.build

初始化一个跨链资源

参数

  • weCrossRPC : WeCrossRPC - RPC实例
  • path: String - 跨链资源标识
  • account: String - 账户名

返回值

  • Resource - 跨链资源实例

java示例

  1.     // 初始化RPC实例
  2.     WeCrossRPCService weCrossRPCService = new WeCrossRPCService();
  3.     WeCrossRPC weCrossRPC = WeCrossRPCFactory.build(weCrossRPCService);
  5.     // 初始化资源实例
  6.     Resource resource = ResourceFactory.build(weCrossRPC, path, account);

注 - 之后的java示例，会省去初始化Resource的步骤。

isActive

获取资源状态，true:可达，false:不可达。

参数

  • 无

返回值

  • bool - 资源状态

java示例

  1.     bool status = resource.isActive();

detail

获取资源详情。

参数

  • 无

返回值

  • ResourceDetail - 资源详情

java示例

  1.     ResourceDetail detail = resource.detail();

call

调用智能合约，不更改链状态，不发交易。

参数

  • request: Request<TransactionRequest> - 请求体

返回值

  • TransactionResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: Receipt - 调用结果

java示例

  1.     TransactionResponse transactionResponse = resource.call(request);

call(无参数)

调用智能合约，不更改链状态，不发交易。

参数

  • method: String - 调用的方法

返回值

  • String[] - 调用结果

java示例

  1.     String[] result = resource.call("get");

call(带参数)

调用智能合约，不更改链状态，不发交易。

参数

  • method: String - 调用的方法
  • args: String... - 可变参数列表

返回值

  • String[] - 调用结果

java示例

  1.     String[] result = resource.call("get", "key");

sendTransaction

调用智能合约，会改变链状态，发交易。

参数

  • request: Request<TransactionRequest> - 请求体

返回值

  • TransactionResponse - 响应包
    • version: String - 版本号
    • errorCode: int - 状态码
    • message: String - 错误消息
    • data: Receipt - 调用结果

java示例

  1.     TransactionResponse transactionResponse = resource.sendTransaction(request);

sendTransaction(无参数)

调用智能合约，会改变链状态，发交易。

参数

  • method: String - 调用的方法

返回值

  • String[] - 调用结果

java示例

  1.     String[] result = resource.sendTransaction("set");

sendTransaction(带参数)

调用智能合约，会改变链状态，发交易。

参数

  • method: String - 调用的方法
  • args: String... - 可变参数列表

返回值

  • String[] - 调用结果

java示例

  1.     String[] result = resource.sendTransaction("set", "value");

RPC状态码

当一个RPC调用遇到错误时，返回的响应对象必须包含error错误结果字段，该字段有下列成员参数：

  • errorCode: 使用数值表示该异常的错误类型，必须为整数。
  • message: 对该错误的简单描述字符串。

标准状态码及其对应的含义如下：

code含义
0执行成功
10100内部错误
10201版本错误
10202资源标识错误
10203资源不存在
10205请求解码错误
10301htlc错误
2000x内部错误，结合message查看错误原因
5xxxx插件内错误，结合message查看错误原因
6xxxx两阶段事务错误，结合message查看错误原因