全部产品

Java SDK 快速开始

本文通过示例阐述如何 运行应用,展示 示例执行流程,并指导如何 指定密码学套件

运行应用

应用运行的过程主要分为 4 步:

  1. 准备环境
  2. 编写应用
  3. 编译应用
  4. 执行应用

准备环境

  • 准备 SSL 连接文件和账户私钥文件。

    要与 BaaS 平台建立 SSL 连接,您需准备三个证书文件:CA 机构的根证书(trustCa)、客户端的证书文件(client.crt)以及客户端的私钥文件(client.key)。此外,提交交易还需要账户的私钥文件(user.key)。这四个文件的详细说明如下。

    文件名称 文件说明 文件来源
    client.crt 客户端的证书文件 使用 BaaS 提供的 密钥生成工具 生成证书请求文件 client.csr,提交请求文件到 BaaS 平台申请证书,申请成功后可下载此 crt 文件。
    client.key 客户端的私钥文件 通过 BaaS 提供的 密钥生成工具 生成。
    trustCa 存储 CA 证书的 trustStore 通过 BaaS 平台下载,trustCa 文件密码为 mychain。
    user.key 账户私钥文件 通过 BaaS 提供的 密钥生成工具 手动生成,或自动生成下载。
  • 准备 TEE 硬件隐私合约链文件。

    如果使用 TEE 硬件隐私合约链,还需要使用一个 tee_rsa_public_key.pem 文件,此文件可从已存在的 TEE 硬件隐私合约链申请,如果使用的是标准的合约链,则不需要使用此文件。

    文件名称 文件说明 文件来源
    tee_rsa_public_key.pem TEE 硬件隐私合约链,节点对外公开的 RSA 公钥文件 通过 BaaS 平台下载。
  • 看合约链节点信息。

    要与合约链交互,您需要获取链节点的 IP 地址和端口号。在 BaaS 平台,通过查看目标合约链详情,在区块浏览器中查看节点详情,可获取链节点的 IP 地址和端口号。

编写应用

  1. 使用 Intellij IDEA 创建一个基于 Maven 构建的空项目(Demo)。创建完成后,项目目录结构应如下:
    1545295559042-521770ec-412b-49ed-935e-a6b644bb0949.png

  2. 在上图中的 java 目录创建自定义包名,例如:com.example.demo,并将 DemoSample.java(点击下载 DemoSample.java 文件)中的内容完整拷贝至创建的包中,并将 SDK 必须使用的 client.crtclient.keytrustCauser.key 文件放入到 resources 目录中,如下图所示:
    1

    说明:Demo 项目中需要使用合约源代码编译后的字节码。有关合约源代码,参见 Solidity 合约开发;Solidity 编译工具参见 Solidity 合约编译工具。WASM 的示例请参考 mychainx-example,支持 0.10.2.12 及以上版本。
  3. pom.xml 中添加依赖。将 SDK 与要演示使用的 slf4j-log4j12 引入到 pom.xml 中,并在 resources 中添加 log4j 的配置文件,如下图所示。

    注意:在本步骤中,SDK 依赖的版本号请使用最新版本。
    pom

    带有 slf4j-log4j12 的完整 pom 依赖可参考:

    1. <dependencies>
    2. <dependency>
    3. <groupId>com.alipay.mychainx</groupId>
    4. <artifactId>mychainx-sdk</artifactId>
    5. <!--请使用最新 SDK 版本 -->
    6. <version>0.10.2.12</version>
    7. </dependency>
    8. <dependency>
    9. <groupId>org.slf4j</groupId>
    10. <artifactId>slf4j-log4j12</artifactId>
    11. <version>1.8.0-alpha0</version>
    12. </dependency>
    13. </dependencies>
    14. <build>
    15. <extensions>
    16. <extension>
    17. <groupId>kr.motd.maven</groupId>
    18. <artifactId>os-maven-plugin</artifactId>
    19. <version>1.6.1</version>
    20. </extension>
    21. </extensions>
    22. </build>

    在某些情况下,可能会出现如下异常:
    2

    异常原因有可能是 Netty 加载失败,可以尝试修改 pom 依赖,如下所示:

    1. <dependencies>
    2. <dependency>
    3. <groupId>com.alipay.mychainx</groupId>
    4. <artifactId>mychainx-sdk</artifactId>
    5. <!--请使用最新 SDK 版本 -->
    6. <version>0.10.2.12</version>
    7. <exclusions>
    8. <exclusion>
    9. <groupId>io.netty</groupId>
    10. <artifactId>netty-tcnative-openssl-static</artifactId>
    11. </exclusion>
    12. </exclusions>
    13. </dependency>
    14. <dependency>
    15. <groupId>org.slf4j</groupId>
    16. <artifactId>slf4j-log4j12</artifactId>
    17. <version>1.8.0-alpha0</version>
    18. </dependency>
    19. </dependencies>
    20. <build>
    21. <extensions>
    22. <extension>
    23. <groupId>kr.motd.maven</groupId>
    24. <artifactId>os-maven-plugin</artifactId>
    25. <version>1.6.1</version>
    26. </extension>
    27. </extensions>
    28. </build>

    log4j.properties 文件内容如下:

    1. log4j.rootLogger=INFO, R
    2. # 日志输出位置为控制台
    3. log4j.appender.stdout=org.apache.log4j.ConsoleAppender
    4. log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
    5. log4j.appender.stdout.layout.ConversionPattern=[QC] %p [%t] %C.%M(%L) | %m%n
    6. # 日志输出位置为文件
    7. log4j.appender.R=org.apache.log4j.DailyRollingFileAppender
    8. log4j.appender.R.File=./sdk.log
    9. log4j.appender.R.layout=org.apache.log4j.PatternLayout
    10. log4j.appender.R.layout.ConversionPattern=%d-[TS] %p %t %c - %m%n

编译应用

在项目根路径运行 mvn clean compile 执行项目编译。

执行应用

DemoSample.java 中,运行该项目。生成的日志文件位于 项目根路径 ./sdk.log,若从日志中搜索到“Hand shake success”,则代表与区块链平台连接成功。

预期输出如下:

  1. create testAccount1 success.
  2. create testAccount2 success.
  3. deploy contract success.
  4. issue success.
  5. transfer success.
  6. check account balance success.

示例执行流程

  1. 初始化环境。

    1. //step 1: init logger.
    2. initLogger();
    3. //step 2:init mychain env.
    4. env = initMychainEnv();
  2. 创建账户交易。

    1. //step 4: init account that will be created.
    2. initAccount();
    3. //step 5: init private key list which will be used during transaction.
    4. initPrivateKeyList();
    5. //step 6: execute create two accounts.
    6. createAccount();
  3. 部署智能合约。

    1. //step 7 : deploy a contract using testAccount1.
    2. deployContract();
  4. 申购积分。

    1. //step 8:issue 100 credits to testAccount2.
    2. issue();
  5. 进行账户间转账。

    1. //step 9 : transfer 50 credits from testAccount2 to testAccount1
    2. transfer();
  6. 查询账户余额。

    1. //step 10 : query testAccount2 whose balance should be 50.
    2. BigInteger balance = query(test2PrivateKeyArrayList,testAccount2);
    3. //step 11 : compare to expect balance.
    4. expect(balance,BigInteger.valueOf(50));
  7. 关闭 SDK 连接。

    1. //step 12 : sdk shut down
    2. sdk.shutDown();

指定密码学套件

合约链的链环境可能使用以下两种密码学套件中的一种:

  • classic:使用国际商用密码算法,包括 SHA256 摘要、ECC 公钥算法、AES 对称加密等,标准合约链默认为此套件配置;
  • china-sm:使用中国国家商用密码算法,包括 SM3 摘要、SM2 公钥算法、SM4 对称加密等,国密算法合约链默认为此套件配置。

如果不清楚 SDK 连接的目标合约链使用的是哪一种密码套件,可咨询该链的管理员。构建 ClientEnv 时,必须显式的指定 SignerBase。示例如下:

  1. Pkcs8KeyOperator pkcs8KeyOperator = new Pkcs8KeyOperator();
  2. Keypair keyPair = pkcs8KeyOperator.load(privateKeyPath, keyPassword);
  3. SignerBase signerBase = MyCrypto.getInstance().createSigner(keyPair);
说明:SDK 与合约平台之间的 SSL 通信不受密码学套件影响,由颁发证书的 PKI 机构决定。