标签:java-sdk
Client
Java SDK为区块链应用开发者提供了Java API接口,按照功能,Java API可分为如下几类:
- Client: 提供访问FISCO BCOS 2.0+节点JSON-RPC接口支持、提供部署及调用合约的支持;
- Precompiled: 提供调用FISCO BCOS 2.0+ Precompiled合约(预编译合约)的接口,主要包括
ConsensusService
、SystemConfigService
、PermissionService
、ChainGovernanceService
、TableCRUDService
、ContractLifeCycleService
、CNSService
。
.. note::
- Client接口声明位于 `Client.java` 文件中
- Client是群组维度的对象,可参考 `快速入门 <quick_start.html>`_ 初始化Client,初始化Client时,必须传入群组ID
发送交易到区块链节点。
- signedTransactionData:签名后的交易
- SendTransaction: 节点收到交易后,回复给SDK的回包,包括交易哈希信息。
交易发布异步接口, 收到节点的响应之后,调用指定的callback。
- signedTransactionData: 签名后的交易字符串;
- callback: SDK收到节点的回包后,调用的回调函数。
- 无
向区块链节点发送交易,且声明在交易推送时交易回执中包含交易Merkle证明和交易回执Merkle证明。
- signedTransactionData: 签名后的交易。
- SendTransaction: 节点收到交易后,回复给SDK的回包,包括交易哈希信息。
sendRawTransactionAndGetProof
异步接口,向节点发送交易,并在收到节点回报时,调用回调函数。
- signedTransactionData: SDK发送到节点的签名后交易;
- callback: SDK收到节点回包后,调用的回调函数。
- 无
交易发送同步接口,发送交易并获取交易回执。
- signedTransactionData: 组装好的交易字符串,包含签名信息。
- TransactionReceipt: 交易回执。
交易发送异步接口,发送交易,并在收到交易回执时调用指定的回调函数。
- signedTransactionData: 组装好的交易字符串,包含签名信息;
- callback: 收到交易回执后调用的回调函数。
- 无。
交易发送同步接口,发送交易,并获取带有交易Merkle证明和交易回执Merkle证明的交易回执。
- signedTransactionData: 组装好的交易字符串,包含签名信息;
- TransactionReceipt: 带有交易Merkle证明和交易回执Merkle证明的交易回执。
交易发送异步接口,发送交易,并在收到交易回执时,调用指定的回调函数(交易回执中包含交易Merkle证明和交易回执的Merkle证明)。
- signedTransactionData: 组装好的交易字符串,包含签名信息;
- callback: 收到交易回执后调用的回调函数。
- 无。
向节点发送请求,调用合约常量接口。
- transaction: 合约调用信息,包含合约地址、合约调用者以及调用的合约接口和参数的abi编码
- Call: 合约常量接口的返回结果,包括当前块高、接口执行状态信息以及接口执行结果
合约常量接口异步调用,接收到节点返回的合约接口执行结果后,执行指定的回调函数
- transaction: 合约调用信息,包含合约地址、合约调用者以及调用的接口和参数信息;
- callback: 回调函数。
- 无
获取Client对象对应的群组最新块高。
- 无
- BlockNumber: Client对象对应的群组最新区块高度。
查询指定合约地址对应的合约代码信息。
- address: 合约地址。
- Code: 合约地址对应的合约代码。
获取Client对应群组的交易统计信息,包括上链的交易数、上链失败的交易数目。
- 无
- TotalTransactionCount: 交易统计信息,包括:
- txSum: 上链的交易总量
- blockNumber: 群组的当前区块高度
- failedTxSum: 上链执行异常的交易总量
根据区块哈希获取区块信息。
- blockHash: 区块哈希;
- returnFullTransactionObjects: true/false,表明获取的区块信息中是否包含完整的交易信息;
- true: 节点返回的区块中包含完整的交易信息;
- false: 节点返回的区块中仅包含交易哈希。
- BcosBlock: 查询获取的区块信息。
根据区块高度获取区块信息。
- blockNumber: 区块高度;
- returnFullTransactionObjects: true/false,表明获取的区块信息中是否包含完整的交易信息;
- true: 节点返回的区块中包含完整的交易信息;
- false: 节点返回的区块中仅包含交易哈希。
- BcosBlock: 查询获取的区块信息
根据区块高度获取区块哈希。
- blockNumber: 区块高度。
- BlockHash: 指定区块高度对应的区块哈希
根据区块哈希获取区块头信息。
- blockHash: 区块哈希;
- returnSignatureList: true/false,表明返回的区块头中是否附带签名列表信息
- true: 返回的区块头中带有区块签名列表信息;
- false: 返回的区块头中不带区块签名列表信息。
- BcosBlockHeader: 指定区块哈希对应的区块头。
根据区块高度获取区块头信息。
- blockHash: 区块高度;
- returnSignatureList: true/false,表明返回的区块头中是否附带签名列表信息
- true: 返回的区块头中带有区块签名列表信息;
- false: 返回的区块头中不带区块签名列表信息。
- BcosBlockHeader: 指定区块高度对应的区块头。
根据交易哈希获取交易信息。
- transactionHash: 交易哈希
- BcosTransaction: 指定哈希对应的交易信息。
根据交易哈希获取交易信息,交易信息中带有交易Merkle证明。
- transactionHash: 交易哈希
- BcosTransaction: 指定哈希对应的交易信息。
根据区块高度和交易索引获取交易信息。
- blockNumber: 交易所在的区块高度;
- transactionIndex: 交易索引。
- BcosTransaction: 指定区块高度和交易索引对应的交易信息。
根据区块哈希和交易索引获取交易信息。
- blockHash: 交易所在的区块哈希;
- transactionIndex:交易索引。
- BcosTransaction: 指定区块哈希和交易索引对应的交易信息。
根据交易哈希获取交易回执信息。
- transactionHash: 交易哈希
- BcosTransactionReceipt: 交易哈希对应的回执信息。
根据交易哈希获取交易回执信息,回执中带有Merkle证明。
- transactionHash: 交易哈希。
- TransactionReceiptWithProof: 带有Merkle证明的交易回执信息。
获取交易池内待处理的交易列表。
- 无
- PendingTransactions: 交易池内未处理的交易列表。
获取交易池内未处理的交易数目。
- 无
- PendingTxSize: 交易池内未处理的交易数目。
获取Client对应群组的BlockLimit,BlockLimit主要用于交易防重。
- 无
- BigInteger: 群组的BlockLimit。
/**
- Get cached block height
- @return block number */ BigInteger getBlockLimit();
为指定节点动态创建一个新群组。
- groupId: 创建的群组ID;
- timestamp: 新创建的群组创世块时间戳;
- enableFreeStorage: 新创建群组是否使用
enable_free_storage
的gas计算模式,推荐设置为false
; - nodeList: 新创建群组的共识节点NodeID列表;
- peerIpPort: 创建该群组的节点
IP:Port
信息。
- GenerateGroup: 群组创建结果。
启动指定节点的指定群组。
- groupId: 需要启动的群组ID;
- peerIpPort: 启动指定群组的节点
IP:Port
信息。
- StartGroup: 群组启动状态。
停止指定节点的指定群组。
- groupId: 需要停止的群组ID;
- peerIpPort: 群组所在的节点
IP:Port
信息。
- StopGroup: 被停止的群组状态。
删除指定节点的指定群组。
- groupId: 被删除的群组信息;
- peerIpPort: 群组所在的节点
IP:Port
信息。
- RemoveGroup: 被删除的群组状态。
恢复指定节点被删除的群组。
- groupId: 需要恢复的群组ID;
- peerIpPort: 群组所在的节点
IP:Port
信息。
- RecoverGroup: 被恢复的群组状态。
查询指定群组的状态。
- groupId: 被查询的群组ID;
- peerIpPort: 群组状态查询发送到的目标节点信息,包括
IP:Port
信息。
- QueryGroupStatus: 被查询的群组状态。
获取指定节点的群组列表。
- peerIpPort: 被查询的节点的
IP:Port
。
- GroupList: 指定节点的群组列表。
获取指定节点指定群组连接的节点列表。
- peerIpPort: 被查询的节点的
IP:Port
。
- GroupPeers: 指定群组连接的节点列表。
获取指定节点的网络连接信息。
- endpoint: 被查询的节点的
IP:Port
。
- Peers: 指定节点的网络连接信息。
获取指定节点连接的节点列表。
- endpoint: 被查询的节点的
IP:Port
。
- NodeIDList: 指定节点连接的节点列表。
获取Client对应群组的观察节点列表。
- 无
- ObserverList: 观察节点列表。
获取Client对应群组的共识节点列表。
- 无
- SealerList: 共识节点列表。
节点使用PBFT共识算法时,获取PBFT视图信息。
- 无
- PbftView: PBFT视图信息。
获取节点版本信息。
- ipAndPort: 请求发送的目标节点,包括
IP:Port
信息。
- NodeVersion: 查询获取的节点版本信息。
获取节点的NodeID,Topic等信息。
- ipAndPort: 请求发送的目标节点,包括
IP:Port
信息。
- NodeInfo: 查询获取的节点版本信息。
获取节点共识状态。
- 无
- ConsensusStatus: 节点共识状态。
根据指定配置关键字获取系统配置项的值。
- key: 系统配置项,目前包括
tx_count_limit
,tx_gas_limit
,rpbft_epoch_sealer_num
,rpbft_epoch_block_num
和consensus_timeout
.
- SystemConfig: 系统配置项的值。
获取节点同步状态。
- 无
- SyncStatus: 区块链节点同步状态。
将指定节点添加为共识节点。
参数
- nodeId: 被添加为共识节点的node ID.
返回值
- RetCode: 共识节点添加结果。
.. note::
为了保证新节点加入不影响共识,即将被添加为共识节点的节点必须与群组内其他节点建立P2P网络连接,否则其无法被添加为共识节点。
将指定节点添加为观察节点。
参数
- nodeId: 被添加为观察节点的node ID.
返回值
- RetCode: 观察节点添加结果。
将指定节点移出群组。
参数
- nodeId: 被移出群组的节点的node ID.
返回值
- RetCode: 节点被移出群组的执行结果。
设置指定系统配置项的值。
参数
-
key: 配置项,目前支持
tx_count_limit
,tx_gas_limit
,rpbft_epoch_block_num
,rpbft_epoch_sealer_num
和consensus_time
; -
value: 系统配置项被设置的值。
返回值
- RetCode: 系统配置项设置结果。
为指定用户添加对指定表的写权限。
参数
- tableName: 授权访问的表名;
- userAddress: 被授权对指定表写操作权限的账户地址。
返回值
- RetCode: 授权结果。
撤销指定用户对指定表的写权限。
参数
- tableName: 撤销写访问权限的表名;
- userAddress: 被撤销对指定表写访问权限的账户地址。
返回值
- RetCode: 权限撤销结果。
查询对指定合约有权限的账户信息。
参数
- contractAddress: 被查询的合约地址。
返回值
- List: 拥有对指定合约写权限的账户信息列表。
授权指定用户对指定合约的写权限。
参数
- contractAddress: 授权写访问的合约地址;
- userAddress: 被授权对指定合约写访问权限的账户地址。
返回值
- RetCode: 授权结果。
撤销指定用户对指定合约的写访问权限。
参数
- contractAddress: 撤销写访问权限的合约地址;
- userAddress: 被撤销对指定合约写访问权限的账户地址。
返回值
- RetCode: 合约写访问权限撤销结果。
查询对指定表有写权限的账户地址信息。
参数
- tableName: 查询权限信息的表名。
返回值
- List: 拥有对指定表写访问权限的账户信息列表。
授权指定用户部署和调用合约的权限。
参数
- userAddress: 被授权部署和调用合约权限的账户地址。
返回值
- RetCode: 授权结果。
撤销指定账户部署和调用合约的权限。
参数
- userAddress: 被撤销部署和调用合约权限的账户地址。
返回值
- RetCode: 指定用户合约部署和调用权限的撤销结果。
列出拥有部署和调用合约权限的账户信息。
参数
- 无
返回值
- 拥有部署和调用合约权限的账户信息列表。
授予指定用户权限控制的权限,被授权的账户可配置普通账户的访问权限。
参数
- userAddress: 被授予权限控制权限的账户地址。
返回值
- RetCode: 授权结果
撤销指定用户权限控制的权限,被撤销的账户不可配置普通账户的对合约、表的访问权限。
参数
- userAddress: 被撤销权限的账户地址。
返回值
- RetCode: 权限撤销结果。
列出拥有权限配置权力的账户信息。
参数
- 无
返回值
- List: 拥有权限控制权限的账户信息列表。
授权指定用户操作系统共识表的权限,被授权用户可增加共识节点、增加观察者节点、删除节点。
参数
- userAddress: 被授权的账户地址。
返回值
- RetCode: 授权结果。
撤销指定用户对系统共识表的写访问权限,撤销权限的账户无法进行增加共识节点、增加观察者节点、删除节点等操作。
参数
- userAddress: 被撤销的账户地址。
返回值
- RetCode: 系统够共识表写访问权限撤销结果。
列出拥有增加共识节点、增加观察者节点、删除节点等操作权限的账户信息。
参数
- 无
返回值
- List: 有增加共识节点、增加观察者节点、删除节点等操作权限的账户信息。
授权指定账户操作CNS表的权限。
参数
- userAddress: 被授权账户地址。
返回值
- RetCode: 授权结果。
撤销指定账户对CNS表的写权限。
参数
- userAddress: 被撤销的账户地址。
返回值
- RetCode: 撤销结果。
列出对CNS表有写权限的账户信息。
参数
- 无
返回值
- List: 对CNS表有写权限的账户列表。
授权指定用户设置系统配置项的权限。
参数
- userAddress: 被授权账户地址。
返回值
- RetCode: 授权结果。
撤销指定用户设置系统配置项的权限。
参数
- userAddress: 被撤销账户地址。
返回值
- RetCode: 权限撤销结果。
列出有修改系统配置项权限的账户信息。
参数
- 无
返回值
- List: 有修改系统配置项权限的账户信息。
授权指定用户为链管理员
参数
- userAddress: 被授权为链管理员的账户地址。
返回值
- RetCode: 授权结果。
撤销指定链管理员为普通账户。
参数
- userAddress: 被撤销的链管理员账户地址。
返回值
- RetCode: 撤销结果。
列出当前链管理员信息。
参数
- 无
返回值
- List: 所有链管理员的信息。
修改指定链管理员的投票权重。
参数
- userAddress: 更新投票权重的链管理员账户地址;
- weight: 更新后的投票权重。
返回值
- RetCode: 连管理员投票权重更新结果。
修改投票生效阈值。
参数
- threshold: 更新后的投票生效阈值。
返回值
- RetCode: 投票生效阈值更新结果。
查询当前的投票生效阈值。
参数
- 无
返回值
- BigInteger: 当前投票生效阈值。
查询指定链管理员的投票权重。
参数
- userAddress: 被查询投票权重的链管理员账户地址。
返回值
- BigInteger: 查询到的指定链管理员投票权重。
将指定账户授权为运维管理员。
参数
- userAddress: 被授权为运维管理员的账户地址。
返回值
- RetCode: 授权结果。
撤销指定运维管理员的运维权限。
参数
- userAddress: 被撤销的运维管理员账户地址。
返回值
- RetCode: 运维权限撤销结果。
列出当前群组的运维管理员信息。
参数
- 无
返回值
- List: 运维管理员列表。
查询指定账户被选举为委员账户的投票情况
参数
account
: 被查询的账户地址
返回值
String
: 返回该账户被选举为委员账户的投票情况;若没有任何委员选举该账户,则返回null字符串
查询updateThreshold的投票情况
参数
- 无
返回值
- String: updateThreshold的投票情况,当没有任何委员更新threshold时,返回null字符串。
冻结指定账户,被冻结的账户不能部署和调用合约。
参数
- userAddress: 被冻结的账户地址。
返回值
- RetCode: 账户冻结结果。
解冻被冻结的账户,解冻后的账户可以部署和调用合约。
参数
- userAddress: 解冻的账户地址。
返回值
- RetCode: 账户解冻结果。
获取指定账户的状态。
参数
- userAddress: 账户地址。
返回值
- String: 指定账户的状态。
创建用户表。
参数
- tableName: 创建的用户表名;
- keyFieldName: 用户表的主key名;
- valueFields: 用户表的fields.
返回值
- RetCode: 用户表创建结果。
向指定用户表中插入一条记录。
参数
- tableName: 需要插入记录的表名;
- key: 主key被设置的值;
- fieldNameToValue: 每个field到其对应值的映射。
返回值
- RetCode: 记录是否插入成功。
更新指定用户表中,将指定主key对应的记录更新为传入的记录。
参数
- tableName: 用户表名;
- key: 需要更新的记录对应的主key值;
- fieldNameToValue: 更新后的记录;
- condition: 记录更新条件。
返回值
- RetCode: 记录是否更新成功。
删除用户表指定记录。
参数
- tableName: 用户表名;
- key: 被删除的记录主key值;
- condition: 被删除记录的匹配条件。
返回值
- RetCode: 记录删除结果。
查询用户表指定记录。
参数
- tableName: 被查询的用户表名;
- key: 被查询的主key值;
- condition: 查询条件。
返回值
- List<Map<String, String>>: 查询结果。
获取指定用户表的描述信息。
参数
- tableName: 被查询的用户表名。
返回值
- List<Map<String, String>>: 用户表描述信息,记录了
PrecompiledConstant.KEY_NAME
到主key的映射,以及PrecompiledConstant.FIELD_NAME
到所有field的映射,field之间用逗号分隔开。
insert
的异步接口,向指定表插入指定记录,并在接收到节点的回执后,调用指定回调函数。
参数
- tableName: 需要插入记录的表名;
- key: 主key被设置的值;
- fieldNameToValue: 每个field到其对应值的映射;
- callback: 回调函数。
返回值
- 无
update
的异步接口,更新指定记录,并在接收到节点的回执后,调用指定回调函数。
参数
- tableName: 用户表名;
- key: 需要更新的记录对应的主key值;
- fieldNameToValue: 更新后的记录;
- condition: 记录更新条件;
- callback: 回调函数。
返回值
- 无
remove
的异步接口,删除指定记录,并在接收到节点的回执后,调用指定回调函数。
参数
- tableName: 用户表名;
- key: 被删除的记录主key值;
- condition: 被删除记录的匹配条件;
- callback: 回调函数。
返回值
- 无
冻结指定合约。
参数
- contractAddress: 被冻结的合约地址。
返回值
- RetCode: 合约冻结结果。
解冻指定合约。
参数
- contractAddress: 被解冻的合约地址。
返回值
- RetCode: 合约解冻结果。
给指定账户授权冻结/解冻指定合约的权限。
参数
- contractAddress: 指定的合约地址;
- userAddress: 被授权对指定合约冻结/解冻权限的账户地址。
返回值
- RetCode: 合约生命周期管理权限授权结果。
获取指定合约的状态。
参数
- contractAddress: 合约地址。
返回值
- String: 合约状态。
获取对某合约有管理权限的账户地址。
参数
- contractAddress: 合约地址。
返回值
- List: 对指定合约有冻结/解冻权限的账户信息。
为指定合约注册CNS。
参数
- contractName: 合约名;
- contractVersion: 注册的合约版本;
- contractAddress: 合约地址;
- abiData: 注册合约的abi;
返回值
- RetCode: CNS注册结果。
根据合约名查询合约CNS信息。
参数
- contractName: 需要查询CNS信息的合约名;
返回值
- List: 查询到的CNS信息列表。
根据合约名和合约版本查询CNS信息。
参数
- contractName: 合约名;
- contractVersion: 合约版本。
返回值
- List: 查询到的CNS信息。
根据合约名和合约版本获取合约地址。
参数
- contractName: 合约名;
- contractVersion: 合约版本。
返回值
- String: 查询到的合约地址。
根据区块高度和交易范围,批量返回群组内的交易回执信息。
blockNumber
: 请求获取的回执信息所在的区块高度;from
: 需要获取的回执起始索引;count
: 需要批量获取的回执数目,当设置为-1时,返回区块内所有回执信息;
BcosTransactionReceiptsDecoder
: 包含压缩编码信息的交易回执数据,调用decodeTransactionReceiptsInfo
方法可将压缩的交易回执转换为TransactionReceiptsInfo
对象,并可通过该对象获取交易回执具体信息
示例:
// 获取最新区块高度的所有交易回执信息(cient初始化过程省略,详细可以参考快速入门)
BcosTransactionReceiptsDecoder bcosTransactionReceiptsDecoder =
client.getBatchReceiptsByBlockNumberAndRange(
client.getBlockNumber().getBlockNumber(), "0", "-1");
// 解码交易回执信息
BcosTransactionReceiptsInfo.TransactionReceiptsInfo receiptsInfo = bcosTransactionReceiptsDecoder.decodeTransactionReceiptsInfo();
// 获取回执所在的区块信息
BcosTransactionReceiptsInfo.BlockInfo blockInfo = receiptsInfo.getBlockInfo();
// 获取交易回执列表
List<TransactionReceipt> receiptList = receiptsInfo.getTransactionReceipts();
根据区块哈希和交易范围,批量返回群组内的交易回执信息。
blockHash
: 请求获取的回执信息所在的区块哈希;from
: 需要获取的回执起始索引;count
: 需要批量获取的回执数目,当设置为-1时,返回区块内所有回执信息;
BcosTransactionReceiptsDecoder
: 包含压缩编码信息的交易回执数据,调用decodeTransactionReceiptsInfo
方法可将压缩的交易回执转换为TransactionReceiptsInfo
对象,并可通过该对象获取交易回执具体信息
示例:
// 获取最新区块的所有交易回执信息(cient初始化过程省略,详细可以参考快速入门)
BcosTransactionReceiptsDecoder bcosTransactionReceiptsDecoder =
client.getBatchReceiptsByBlockHashAndRange(
client.getBlockHashByNumber(client.getBlockNumber().getBlockNumber())
.getBlockHashByNumber(),
"0",
"-1");
// 解码交易回执信息
BcosTransactionReceiptsInfo.TransactionReceiptsInfo receiptsInfo = bcosTransactionReceiptsDecoder.decodeTransactionReceiptsInfo();
// 获取回执所在的区块信息
BcosTransactionReceiptsInfo.BlockInfo blockInfo = receiptsInfo.getBlockInfo();
// 获取交易回执列表
List<TransactionReceipt> receiptList = receiptsInfo.getTransactionReceipts();