快速入门

1 环境要求

2 Java应用引入SDK

2.1 使用gradle引入SDK

compile ('org.fisco-bcos.java-sdk:java-sdk:2.6.1-rc1')

2.2 使用maven引入SDK

<dependency>
    <groupId>org.fisco-bcos.java-sdk</groupId>
    <artifactId>java-sdk</artifactId>
    <version>2.6.1-rc1</version>
</dependency>

3 SDK证书配置

参考java sdk证书配置。

.. note::
    - 大部分场景仅需要配置 `certPath` 配置项即可，其他配置项不需额外配置；
    - SDK证书获取：若参考 `安装 <../../installation.html>`_ 搭建区块链，则参考 `这里 <../../installation.html#id7>`_ 将 `nodes/${ip}/sdk/` 目录下的证书拷贝到 `certPath` 指定的路径；若区块链节点参考 `运维部署工具 <../../installation.html>`_ 搭建，则参考 `这里 <../../enterprise_tools/tutorial_one_click.html#id15>`_ 将 `generator/meta` 文件夹下的SDK证书拷贝到 `certPath` 指定路径，`certPath`默认为`conf`目录；
    - SDK与节点间SSL连接方式，可通过节点配置项 `sm_crypto_channel` 判断，该配置项详细说明请参考 `FISCO BCOS配置文件与配置项说明 <../../manual/configuration.html#id10>`_ .

将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

4 solidity代码转java代码

控制台console和java sdk均提供了将solidity代码转换为java代码的工具。

4.1 使用控制台提供的工具

控制台v2.6+提供了sol2java.sh脚本可将solidity转换为java代码, 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

参数如下：

将~/fisco/console/contracts/solidity路径下的sol文件转为java代码的示例如下：

$ mkdir -p ~/fisco && cd ~/fisco
# 获取控制台
$ curl -#LO https://github.com/FISCO-BCOS/console/releases/download/v2.6.1/download_console.sh && bash download_console.sh
$ cd ~/fisco/console
# 将sol转为java代码，指定java包名为org.com.fisco
$ bash sol2java.sh org.com.fisco

使用java-sdk或控制台将solidity代码转换为java代码后，即可将生成的java代码拷贝到规划的包路径，通过调用该java代码部署和调用合约。

4.2 使用java-sdk提供的工具

$ mkdir -p ~/fisco && cd ~/fisco
# 获取java-sdk代码
$ git clone https://github.com/FISCO-BCOS/java-sdk
# 编译
$ ./gradlew clean build -x test
# 进入sdk-demo/dist目录，创建合约存放目录
$ cd sdk-demo/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}

5 SDK使用示例

.. note::
    java sdk同时支持将 `solidity` 转换为 `java` 文件后，调用相应的 `java` 方法部署和调用合约，也支持构造交易的方式部署和调用合约，这里主要展示前者的调用方法，后者详细的使用方法请参考 `这里 <./assemble_transaction.html>`_

5.1 BcosSDK初始化

BcosSDK是使用java sdk开发应用时必须初始化的对象，目前同时支持通过toml和xml配置文件初始化BcosSDK对象。

5.1.1 通过toml配置文件初始化BcosSDK

java sdk toml配置文件说明请参考这里，配置示例请参考java sdk源码的src/test/resources/config-example.toml或配置文件说明的第三节配置示例, 通过toml配置文件初始化BcosSDK的代码示例如下：

public class BcosSDKTest
{
    public BcosSDK initBcosSDK()
    {
        String configFile = BcosSDKTest.class.getClassLoader().getResource("config-example.toml").getPath();
        return BcosSDK.build(configFile);
    }
}

5.1.2 通过xml配置文件初始化BcosSDK

为了适配更多场景，java sdk支持使用xml初始化BcosSDK, xml配置示例请参考java sdk源码的src/test/resources/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);

5.2 部署和调用合约

以使用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");
     }
}