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 提供的 密钥生成工具 手动生成,或自动生成。

  • 获取链节点 IP 和端口号。

    要与合约链交互,您需要获取链节点的 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 合约编译工具。

  3. pom.xml 中添加依赖。将 SDK 与要演示使用的 slf4j-log4j12 引入到 pom.xml 中,并在 resources 中添加 log4j 的配置文件,如下图所示。

    重要

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

    pom

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

    <dependencies>
         <dependency>
             <groupId>com.alipay.mychainx</groupId>
             <artifactId>mychainx-sdk</artifactId>
             <!--请使用最新 SDK 版本 -->
             <version>0.10.2.6</version>
         </dependency>
    
         <dependency>
             <groupId>org.slf4j</groupId>
             <artifactId>slf4j-log4j12</artifactId>
             <version>1.8.0-alpha0</version>
         </dependency>
     </dependencies>
    
     <build>
         <extensions>
             <extension>
                 <groupId>kr.motd.maven</groupId>
                 <artifactId>os-maven-plugin</artifactId>
                 <version>1.6.1</version>
             </extension>
         </extensions>
     </build>

    log4j.properties 文件内容如下:

     log4j.rootLogger=INFO, R
    
     # 日志输出位置为控制台
     log4j.appender.stdout=org.apache.log4j.ConsoleAppender
     log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
     log4j.appender.stdout.layout.ConversionPattern=[QC] %p [%t] %C.%M(%L) | %m%n
    
     # 日志输出位置为文件
     log4j.appender.R=org.apache.log4j.DailyRollingFileAppender
     log4j.appender.R.File=./sdk.log
     log4j.appender.R.layout=org.apache.log4j.PatternLayout
     log4j.appender.R.layout.ConversionPattern=%d-[TS] %p %t %c - %m%n
    
     # mychain-sdk日志开关配置
     log4j.logger.MychainClient=OFF

    如果您使用的是logback的日志框架,则日志开关的配置方法如下:

    <logger name="MychainClient" level="OFF"/>

编译应用

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

执行应用

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

预期输出如下:

create testAccount1 success.
create testAccount2 success.
deploy contract success.
issue success.
transfer success.
check account balance success.

错误信息

当收到交易的结果以后,若交易执行不正确,可以跟进错误码去定位错误原因。

  • ErrorCodeMychainBaseResulterrorCode 字段用来表示交易发送或者执行错误的原因。

当发送的请求是交易相关的内容时,可根据交易的返回值字段中获得关于交易执行错误更详细的错误码。以部署合约为例:

MychainBaseResult<ReplyTransactionReceipt> result = sdk.getContractService()
    .deployContract(
        DeployContractRequest.build(adminAccount.getIdentity(),
            Utils.getIdentityByName(testContractId,env), contractCode, VMTypeEnum.EVM,
            contractParameters, BigInteger.ZERO, params));
assertTrue(result.isSuccess());
assertEquals(0, result.getData().getTransactionReceipt().getResult());
  • result.getData().getTransactionReceipt().getResult() 为 0,代表交易执行成功,反之代表交易执行失败,可以通过 result 的值从MychainErrorCodeEnum中 查找错误原因。

  • result.isSuccess() 可以作为交易是否发送成功的标志。若交易发送失败,可通过 result.getErrorCode() 获取错误码。

示例执行流程

  1. 初始化环境。

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

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

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

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

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

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

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