Merge pull request #105 from cryptape/docs

doc: add detail document for SDK

README.md

@@ -8,6 +8,8 @@
 
 cita-sdk-java, originally adapted from Ethereum web3j, is a Java library for working with Smart Contract and integrating with clients on CITA.
 
+Here is [detail documentation](docs/index.md)
+
 ## Features
 
 - Complete implementation of CITA JSON-RPC API over HTTP.
@@ -144,6 +146,9 @@ Please find complete code in [TokenAccountExample](https://github.com/cryptape/c
 
 ## 简介
 cita-sdk-java 是对以太坊 Web3j 进行改写，适配 CITA 的一个 Java 开发包。cita-sdk-java 集成了与 CITA 客户端交互的功能，可以用来对 CITA 发送交易，系统配置，信息查询。
+
+开发请参考[详细文档](docs/index.md)
+
 ## 特性
 - 通过 HTTP 协议，实现了 CITA 所定义的所有 JSON-RPC 方法。
 - 可以通过 Solidity 智能合约生成该合约的 Java 类。这个智能合约的 Java 类作为 java 对智能合约的包裹层，可以使开发和通过 java 方便地对智能合约进行部署和合约方法的调用（支持Solidity 和 Truffle 的格式）。

core/src/main/java/com/cryptape/cita/protocol/account/Account.java

@@ -59,7 +59,7 @@ public AppSendTransaction deploy(
                         version, chainId, value);
     }
 
-    public Future<AppSendTransaction> deployAsync(
+    public Flowable<AppSendTransaction> deployAsync(
             File contractFile, String nonce, long quota,
             int version, BigInteger chainId, String value)
             throws IOException, InterruptedException, CompiledContract.ContractCompileError {
@@ -70,7 +70,6 @@ public Future<AppSendTransaction> deployAsync(
                         version, chainId, value);
     }
 
-    // eth_call: nonce and quota is null
     // sendTransaction: nonce and quota is necessary
     public Object callContract(
             String contractAddress, String funcName,
@@ -101,7 +100,7 @@ public Object callContract(
 
         Function func;
         if (functionAbi.isConstant()) {
-            // eth_call
+            // call
             List<TypedAbi.ArgRetType> retsType = new ArrayList<>();
             List<TypeReference<?>> retsTypeRef = new ArrayList<>();
             List<AbiDefinition.NamedType> outputs = functionAbi.getOutputs();
@@ -111,7 +110,7 @@ public Object callContract(
                 retsTypeRef.add(retType.getTypeReference());
             }
             func = new Function(functionAbi.getName(), params, retsTypeRef);
-            return ethCall(contractAddress, func, retsType);
+            return appCall(contractAddress, func, retsType);
         } else {
             // send_transaction
             func = new Function(functionAbi.getName(), params, Collections.emptyList());
@@ -120,7 +119,7 @@ public Object callContract(
         }
     }
 
-    public Object ethCall(String contractAddress, Function func, List<TypedAbi.ArgRetType> retsType)
+    public Object appCall(String contractAddress, Function func, List<TypedAbi.ArgRetType> retsType)
             throws IOException {
         String data = FunctionEncoder.encode(func);
         AppCall call = this.service.appCall(new Call(this.transactionManager.getFromAddress(),

core/src/main/java/com/cryptape/cita/tx/RawTransactionManager.java

@@ -14,6 +14,7 @@
 import com.cryptape.cita.protocol.core.methods.response.AppGetTransactionCount;
 import com.cryptape.cita.protocol.core.methods.response.AppSendTransaction;
 import com.cryptape.cita.utils.Numeric;
+import io.reactivex.Flowable;
 
 public class RawTransactionManager extends TransactionManager {
 
@@ -108,7 +109,7 @@ public AppSendTransaction sendTransaction(
         return citaj.appSendRawTransaction(rawTx).send();
     }
 
-    public Future<AppSendTransaction> sendTransactionAsync(
+    public Flowable<AppSendTransaction> sendTransactionAsync(
             String to, String data, long quota, String nonce,
             long validUntilBlock, int version, BigInteger chainId, String value)
             throws IOException {
@@ -124,7 +125,7 @@ public Future<AppSendTransaction> sendTransactionAsync(
         } else if (this.signature != null) {
             rawTx = transaction.sign(this.signature);
         }
-        return citaj.appSendRawTransaction(rawTx).sendAsync();
+        return citaj.appSendRawTransaction(rawTx).flowable();
     }
 
     @Override

core/src/main/java/com/cryptape/cita/tx/TransactionManager.java

@@ -12,11 +12,10 @@
 import com.cryptape.cita.protocol.exceptions.TransactionException;
 
 /**
- * Transaction manager abstraction for executing transactions with Ethereum client via
+ * Transaction manager abstraction for executing transactions with CITA client via
  * various mechanisms.
  */
 
-///TODO this class includes ethereum methods: remove them later
 public abstract class TransactionManager {
 
     public static final int DEFAULT_POLLING_ATTEMPTS_PER_TX_HASH = 40;

docs/account.md

@@ -0,0 +1,94 @@
+## Account
+
+Account 封装了 TransactionManager，通过 CITAj 和账户的私钥进行实例化。
+
+Account 使用了 CompiledContract 类，可以直接读取 Solidity 合约文件，生成 ABI 和 BIN 文件以供 TransactionManager 使用。
+
+* [New account](#new-account)
+* [Deploy contract](#deploy-contract)
+* [Call Contract](#call-contract)
+
+### New account
+
+**方法名**
+
+`Account(String privateKey, CITAj service)`
+
+实例化Account对象。
+
+**参数**
+
+* privateKey - 发送交易地址的私钥
+* service - CITAj 实例
+
+**返回值**
+
+Account
+
+**示例**
+
+```
+String privateKey = "{private key}";
+CITAj service  = CITAj.build(new HttpService("http://127.0.0.1"));
+Account account = new Account(privateKey, service);
+```
+### Deploy contract
+
+**方法名**
+
+`AppSendTransaction deploy(File contractFile, BigInteger nonce, long quota, int version, int chainId, String value)`
+
+部署合约。
+
+**参数**
+
+* contractFile - solidity智能合约文件
+* nonce - 随机数用于防止重放攻击
+* quota - 用户支付矿工的费用
+* version - 链的版本信息
+* chainId - 链Id
+* value - 交易中原生token的数量
+
+**返回值**
+
+AppSendTransaction
+
+**示例**
+```
+String privateKey = "{private key}";
+CITAj service  = CITAj.build(new HttpService("http://127.0.0.1"));
+Account account = new Account(privateKey, service);
+AppSendTransaction appSendTransaction = account.deploy(new File(path), randomNonce(), quota, version, chainId, value);
+```
+
+### Call contract
+
+**方法名**
+
+`Object callContract(String contractAddress, String funcName, BigInteger nonce, long quota, int version, int chainId, String value, Object... args)`
+
+调用合约方法,根据Abi中对方法的定义判断使用sendRawTransaction还是app_call。
+
+**参数**
+
+* contractAddress - 合约地址
+* funcName - 合约方法名称
+* nonce - 随机数用于防止重放攻击
+* quota - 用户支付矿工的费用
+* version - 链的版本信息
+* chainId - 链Id
+* value - 交易中原生token的数量
+* args - 合约方法参数
+
+**返回值**
+
+Object
+
+**示例**
+
+```
+String privateKey = "{private key}";
+CITAj service  = CITAj.build(new HttpService("http://127.0.0.1"));
+Account account = new Account(privateKey, service);
+AppSendTransaction appSendTransaction = (AppSendTransaction) account.callContract(contractAddress, transfer, randomNonce(), quota, version, chainId, value, toAddress, amount);
+```

docs/index.md

@@ -0,0 +1,19 @@
+# cita-sdk-java API 文档
+
+## 概述：
+
+cita-sdk-java 是对于 CITA 进行交互的 Java SDK 包，cita-sdk-java 使用 JSON-RPC 协议对 CITA 网络节点发送包含方法名和参数的请求，请求可以是转账或者合约的部署和调用。
+
+在 cita-sdk-java 中，一共有三种方式实现和链上节点的交互：
+
+第一种: 通过 cita-sdk-java 定义的方法手动输入包括合约的Abi和Bin来进行操作。
+
+第二种: 通过codeGen工具将Solidity合约生成Java类，该Java类继承自Contract类并包含合约中定义的所有方法。
+相比于第一种方法的手动拼接参数，这个方式可以不用生成Abi和Bin文件而直接通过Java类中的方法来进行合约的部署和调用。  
+
+第三种: 通过封装在Account中的方法来构建并发送交易，Account会实例化TransactionManager，TransactionManager 提供了异步和同步方式对合约进行部署和调用。
+
+## 目录：
+1. [JSON-RPC](jsonrpc.md)
+2. [Transaction](transaction.md)
+3. [Account](account.md)