快速入门¶
标签：java-sdk 引入Java SDK
1. 安装环境¶
Java：JDK 14 （JDK1.8 至JDK 14都支持）
首先，在官网上下载JDK14并安装
然后，修改环境变量
# 确认您当前的java版本 $ java -version # 确认您的java路径 $ ls Library/Java/JavaVirtualMachines # 返回 # jdk-14.0.2.jdk # 如果使用的是bash $ vim .bash_profile # 在文件中加入JAVA_HOME的路径 # export JAVA_HOME = Library/Java/JavaVirtualMachines/jdk-14.0.2.jdk/Contents/Home $ source .bash_profile # 如果使用的是zash $ vim .zashrc # 在文件中加入JAVA_HOME的路径 # export JAVA_HOME = Library/Java/JavaVirtualMachines/jdk-14.0.2.jdk/Contents/Home $ source .zashrc # 确认您的java版本 $ java -version # 返回 # java version "14.0.2" 2020-07-14 # Java(TM) SE Runtime Environment (build 14.0.2+12-46) # Java HotSpot(TM) 64-Bit Server VM (build 14.0.2+12-46, mixed mode, sharing)
IDE：IntelliJ IDE.
进入IntelliJ IDE官网，下载并安装社区版IntelliJ IDE
2. 搭建一条FISCO BCOS链¶
请参考FISCO BCOS安装搭建。
3. 开发智能合约应用¶
第一步. 创建一个Gradle应用¶
在IntelliJ IDE中创建一个gradle项目。勾选Gradle和Java。
第二步. 引入Java SDK¶
在build.gradle中引入Java SDK。
compile ('org.fisco-bcos.java-sdk:fisco-bcos-java-sdk:2.9.0')
如果您使用maven 通过以下方法引入Java SDK
<dependency>
<groupId>org.fisco-bcos.java-sdk</groupId>
<artifactId>fisco-bcos-java-sdk</artifactId>
<version>2.9.0</version>
</dependency>
注解
- 由于sol转java代码的变更，若使用最新控制台生成java代码，请升级Java SDK至 2.8.0+ 版本
第三步. 配置SDK证书¶
参考Java SDK证书配置。
注解
将SDK证书拷贝到Java SDK的示例如下(这里假设SDK证书位于~/fisco/nodes/127.0.0.1/sdk目录)：
# 假设SDK证书位于~/fisco/nodes/127.0.0.1/sdk/目录
mkdir -p conf && cp -r ~/fisco/nodes/127.0.0.1/sdk/* conf
第四步. 准备智能合约¶
控制台console和java-sdk-demo均提供了工具，可以将solidity合约生成出调用该合约java工具类。本例中使用console做为例子，使用java-sdk-demo的例子请看第6章“附录一. 使用java-sdk-demo给智能合约生成调用它的Java工具类”
首先，下载控制台。
$ mkdir -p ~/fisco && cd ~/fisco
# 获取控制台
$ curl -#LO https://github.com/FISCO-BCOS/console/releases/download/v2.9.1/download_console.sh
# 若因为网络问题导致长时间无法执行以上命令，请尝试以下命令：
$ https://osp-1257653870.cos.ap-guangzhou.myqcloud.com/FISCO-BCOS/console/releases/v2.9.1/download_console.sh
$ bash download_console.sh
$ cd ~/fisco/console
然后，将您要用到的Solidity智能合约放入~/fisco/console/contracts/solidity的目录。本次我们用console中的HelloWorld.sol作为例子。保证HelloWorld.sol在指定的目录下。
# 当前目录~/fisco/console
$ ls contracts/solidity
得到返回
HelloWorld.sol KVTableTest.sol ShaTest.sol Table.sol TableTest.sol
接着，生成调用该智能合约的java类
若控制台版本大于等于2.8.0：
# 使用sol2java.sh将contracts/solidity下的所有合约编译产生bin,abi,java工具类。
# 当前目录~/fisco/console
$ bash sol2java.sh -p org.com.fisco
# 以上命令中参数“org.com.fisco”是指定产生的java类所属的包名。
# 通过命令./sol2java.sh -h可查看该脚本使用方法
若控制台版本小于2.8.0：
# 使用sol2java.sh将contracts/solidity下的所有合约编译产生bin,abi,java工具类。
# 当前目录~/fisco/console
$ bash sol2java.sh org.com.fisco
# 以上命令中参数“org.com.fisco”是指定产生的java类所属的包名。
# ./sol2java.sh [packageName] [solidityFilePath] [javaCodeOutputDir]
sol2java.sh的用法可以参照第4章 “附录二. sol2java.sh脚本的使用方法”。
得到返回
*** Compile solidity TableTest.sol***
INFO: Compile for solidity TableTest.sol success.
*** Convert solidity to java for TableTest.sol success ***
*** Compile solidity KVTableTest.sol***
INFO: Compile for solidity KVTableTest.sol success.
*** Convert solidity to java for KVTableTest.sol success ***
*** Compile solidity HelloWorld.sol***
INFO: Compile for solidity HelloWorld.sol success.
*** Convert solidity to java for HelloWorld.sol success ***
*** Compile solidity Table.sol***
INFO: Compile for solidity Table.sol success.
*** Convert solidity to java for Table.sol success ***
*** Compile solidity ShaTest.sol***
INFO: Compile for solidity ShaTest.sol success.
*** Convert solidity to java for ShaTest.sol success ***
查看编译结果
$ ls contracts/sdk/java/org/com/fisco
# 得到返回
# HelloWorld.java KVTableTest.java ShaTest.java Table.java TableTest.java
**最后, 将编译得到的HelloWorld.java放入应用中。**注意：在应用中所放的位置要与我们设定的包名相同。
(操作示范请看如下gif动图，动画总共有2分40秒，请耐心等待观看，请勿点击图片，如果点击图片将从头开始播放。)
第五步. 创建配置文件¶
在项目中创建配置文件config.toml, 可参照配置向导进行配置，也可以参照config-example.toml,
通过xml配置请参照第4章“附录三. 使用xml配置进行配置”。
第六步. 使用Java SDK部署和调用智能合约¶
以使用Java SDK调用群组1的getBlockNumber接口获取群组1最新块高，并向群组1部署和调用HelloWorld合约为例，对应的示例代码如下：
public class BcosSDKTest
{
// 获取配置文件路径
public final String configFile = BcosSDKTest.class.getClassLoader().getResource("config-example.toml").getPath();
public void testClient() throws ConfigException {
// 初始化BcosSDK
BcosSDK sdk = BcosSDK.build(configFile);
// 为群组1初始化client
Client client = sdk.getClient(Integer.valueOf(1));
// 获取群组1的块高
BlockNumber blockNumber = client.getBlockNumber();
// 向群组1部署HelloWorld合约
CryptoKeyPair cryptoKeyPair = client.getCryptoSuite().getCryptoKeyPair();
HelloWorld helloWorld = HelloWorld.deploy(client, cryptoKeyPair);
// 调用HelloWorld合约的get接口
String getValue = helloWorld.get();
// 调用HelloWorld合约的set接口
TransactionReceipt receipt = helloWorld.set("Hello, fisco");
}
}
4. 附录¶
附录一. 使用java-sdk-demo给智能合约生成调用它的Java工具类¶
$ mkdir -p ~/fisco && cd ~/fisco
# 获取java-sdk代码
$ git clone https://github.com/FISCO-BCOS/java-sdk-demo
# 若因为网络问题导致长时间无法执行以上命令，请尝试以下命令：
$ git clone https://gitee.com/FISCO-BCOS/java-sdk-demo
$ cd java-sdk-demo
# 切换到2.0版本
git checkout main-2.0
# 编译
$ ./gradlew clean build -x test
# 进入sdk-demo/dist目录，创建合约存放目录
$ cd dist && mkdir -p contracts/solidity
# 将需要转换为java代码的sol文件拷贝到~/fisco/java-sdk/dist/contracts/solidity路径下
# 转换sol, 其中${packageName}是生成的java代码包路径
# 生成的java代码位于 ~/fisco/java-sdk/dist/contracts/sdk/java目录下
java -cp "apps/*:lib/*:conf/" org.fisco.bcos.sdk.demo.codegen.DemoSolcToJava ${packageName}
附录二. sol2java.sh脚本的使用方法¶
控制台v2.6+提供了sol2java.sh脚本可将solidity转换为java代码, sol2java.sh使用方法如下：
# 若控制台版本大于或等于2.8.0, 脚本sol2java.sh的使用方法如下：
$ bash sol2java.sh -h
usage: Compile Solidity Tool:
-h,--help
-l,--libraries <arg> [Optional] Set library address information built
into the solidity contract
eg:
--libraries lib1:lib1_address lib2:lib2_address
-o,--output <arg> [Optional] The file path of the generated java
code, default is contracts/sdk/java/
-p,--package <arg> [Optional] The package name of the generated java
code, default is com
-s,--sol <arg> [Optional] The solidity file path or the solidity
directory path, default is contracts/solidity/
# 若控制台版本小于2.8.0，脚本sol2java.sh的使用方法如下：
$ bash sol2java.sh -h
# Compile Solidity Tool
./sol2java.sh [packageName] [solidityFilePath] [javaCodeOutputDir]
packageName:
the package name of the generated Java class file
solidityFilePath:
(optional) the solidity file path or the directory where solidity files located, default: contracts/solidity
javaCodeOutputDir:
(optional) the directory where the generated Java files located, default: contracts/sdk/java
附录三. 使用xml配置进行配置¶
为了适配更多场景，Java SDK支持使用xml初始化BcosSDK, xml配置示例请参考Java SDK源码的applicationContext-sample.xml, 配置项的含义参考配置说明.
通过xml配置文件初始化BcosSDK之前，需要先引入spring。
通过gradle引入spring如下：
def spring_version = "4.3.27.RELEASE"
List spring = [
"org.springframework:spring-core:$spring_version",
"org.springframework:spring-beans:$spring_version",
"org.springframework:spring-context:$spring_version",
"org.springframework:spring-tx:$spring_version",
]
compile spring
通过maven引入spring如下：
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-core</artifactId>
<version>4.3.27.RELEASE</version>
<groupId>org.springframework</groupId>
<artifactId>spring-beans</artifactId>
<version>4.3.27.RELEASE</version>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
<version>4.3.27.RELEASE</version>
<groupId>org.springframework</groupId>
<artifactId>spring-tx</artifactId>
<version>4.3.27.RELEASE</version>
</dependency>
使用applicationContext-sample初始化BcosSDK如下：
ApplicationContext context =
new ClassPathXmlApplicationContext("classpath:applicationContext-sample.xml");
BcosSDK sdk = context.getBean(BcosSDK.class);
附录四. 使用ConfigOption初始化BcosSDK¶
Java SDK提供了灵活的BcosSDK初始化方式，应用除了直接通过toml和xml直接初始化BcosSDK外，还可通过ConfigProperty对象加载ConfigOption，并使用ConfigOption初始化BcosSDK。
ConfigProperty维护了key, value类型配置映射，其核心的数据结构如下：
public class ConfigProperty {
// 证书配置选项，目前主要包括以下几个配置项：
// certPath: 证书路径
// caCert: CA证书路径
// sslCert: SDK证书
// sslKey: SDK私钥
// enSslCert: 国密SSL的SDK证书
// enSslKey: 国密SSL的SDK私钥
public Map<String, Object> cryptoMaterial;
// SDK到节点的网络配置选项，目前包含以下配置选项：
// peers: 配置SDK连接的节点列表
public Map<String, Object> network;
// AMOP配置选项，目前包括以下配置项：
// topicName: 订阅的AMOP topic
// publicKeys: 私有AMOP topic中，定义允许接收本客户端消息的其他客户端的公钥列表，用于进行topic认证
// privateKey: 私有AMOP topic中，定义本客户端的私钥，用于进行topic认证
// password: 若客户端私钥是p12文件，此配置项定义私钥文件的加载密码
public List<AmopTopic> amop;
// 账户配置项，目前包括以下配置项：
// keyStoreDir: 账户私钥保存路径，默认为account
// accountFilePath: 从配置文件中加载的账户路劲
// accountFileFormat: 账户格式，目前支持pem和p12
// accountAddress: 加载的账户地址
// password: 加载p12类型账户私钥时，定义访问账户私钥的口令
public Map<String, Object> account;
// 线程池配置项，目前主要包括以下配置项:
// channelProcessorThreadSize: 处理channel消息包的线程数目，默认为CPU核心线程数目
// receiptProcessorThreadSize: 处理交易回执的线程数目，默认为CPU核心数目
public Map<String, Object> threadPool;
}
应用可根据实际情况初始化ConfigProperty，ConfigProperty初始化完毕后，可加载产生ConfigOption，示例代码如下：
// 从ConfigProperty加载ConfigOption
public ConfigOption loadConfigOption(ConfigProperty configProperty)throws ConfigException
{
return new ConfigOption(configProperty);
}
初始化ConfigOption后，可通过ConfigOption创建BcosSDK，示例代码如下：
public BcosSDK createBcosSDK(ConfigOption configOption)throws BcosSDKException
{
return new BcosSDK(configOption);
}