基本操作

用户管理

表操作

数据操作

数据查询

权限管理

事务相关

区块信息

事件订阅

运算符

Java 接口命令参考

基本操作

ChainSQL jar

获取依赖jar包

a.如果本地有maven环境,将以下代码加入本地开发环境pom.xml文件进行jar包下载。

<dependency> <groupId>com.peersafe</groupId> <artifactId>chainsql</artifactId> <version>1.4.2</version> </dependency>

b.如果本地没有maven环境,直接下载项目依赖的jar包,在“buildPath”中选择“libraries”,再Add External Jars 添加相应的jar包。

项目依赖的jar包下载:libs.zip

c

Chainsql c = Chainsql.c;

ChainSQL的操作对象;

Example:获取ChainSQL的操作对象;

import com.peersafe.chainsql.core.Chainsql;

import com.peersafe.chainsql.core.Table;

public static final Chainsql c= Chainsql.c;
					

connect

c.connect(url);

创建一个新的连接到ChainSQL节点;

如果无法建立连接,会抛出java.net.ConnectException;

Example:连接指定的路径的主机。

c.connect("ws://192.168.0.162:6006");
					

as

c.as(address,secret);

提供操作者的身份;

Example:

c.as("zP8Mum8xaGSkypRgDHKRbN8otJSzwgiJ9M", "xcUd996waZzyaPEmeFVp4q5S3FZYB");
					

use

c.use(address);

切换表的所有者(即后续操作的上下文),默认表的所有者为操作者;

Example:

c.use("zP8Mum8xaGSkypRgDHKRbN8otJSzwgiJ9M");
					

setRestrict

c.setRestrict(true/false);

设置是否使用严格模式,默认为非严格模式;在严格模式下,语句共识通过的条件是期望的快照HASH与预期一致

true:严格模式     false: 非严格模式

Example:

c.setRestrict(false);
					

submit

c.submit();

submit有3个重载函数,对应异步和同步,客户可以根据需要填写参数。返回值均为JSON对象,指示成功或失败;

1. JSONObject submit()

同步接口,等待交易提交结果,参数为空

c.table("marvel").insert(args).submit();

提交操作,执行查询操作时,返回json类型;

Example:

c.table("marvel")
.insert(c.array("{'name': 'peera','age': 22}","{'name': 'peerb','age': 21}"))
.submit();
					

2. JSONObject submit(Callback cb)

异步接口,参数为一回调函数

c.table("marvel").insert(args).submit(Callback cb);

Example:

c.table("marvel").insert(c.array("{'name': 'peera','age': 22}", "{'name': 'peerb','age': 21}"))
.submit(new Callback () {
	public void called(JSONObject data) {
		System.out.println(data);
}));
                

3. JSONObject submit(SyncCond cond)

同步接口,参数为一枚举类型

enum SyncCond { validate_success, db_success };

validate_success:交易共识通过

db_success:交易成功同步到数据库

c.table("marvel").insert(args).submit(SyncCond.db_success);

Example:

c.table("marvel").insert(c.array("{'name': 'peera','age': 22}", "{'name': 'peerb','age': 21}"))
.submit(SyncCond.db_success);
					

用户管理

generateAddress

c.generateAddress();

创建用户,返回JSON数据类型,包含:

secret:账户秘钥

address:账户地址

publicKey:公钥

Example:

JSONObject json = c.generateAddress();

输出:

{
	"secret":"xcUd996waZzyaPEmeFVp4q5S3FZYB",
	"address":"zP8Mum8xaGSkypRgDHKRbN8otJSzwgiJ9M",
	"publicKey":"02B2F836C47A36DE57C2AF2116B8E812B7C70E7F0FEB0906493B8476FC58692EBE"
}
	     			

pay

c.pay(accountId,count);

返回值为JSONObject类型

给用户转账,新创建的用户在转账成功之后才能正常使用;其中accountId表示转账的用户地址,count转账金额,count最小值5;

根账户地址:zHb9CJAWyB4zj91VRWn96DkukG4bwdtyTh,私钥:xnoPBzXtMeMyMHUVTgbuqAfg1SUTb

Example: 给账户地址等于 z9VF7yQPLcKgUoHwMbzmQBjvPsyMy19ubs 的用户转账5.

c.pay("z9VF7yQPLcKgUoHwMbzmQBjvPsyMy19ubs", "5")
					

表操作

createTable

c.createTable(tableName,raw,confidential).submit(SyncCond.db_success);

有三个重载函数:

  public Chainsql createTable(String name, List raw)
  public Chainsql createTable(String name, List rawList ,boolean confidential)
  public Chainsql createTable(String name, List raw,JSONObject operationRule)

tableName:所创建表名,创建表不支持自增型;

raw:创建表的字段名称必须为Json格式数据;例如:

"{'field':'id','type':'int','length':11,'PK':1,'NN':1,'UQ':1}",
"{'field':'name','type':'varchar','length':50,'default':null}",
"{'field':'age','type':'int'}"

operationRule:行级控制规则,不能与confidential一起使用

confidential:为boolean类型,表示创建的表是否为加密的表,true:创建加密表;如果不写,默认为false;

创建表参数说明:

  • field:表字段名
  • type:字段名类型,支持int/float/double/decimal/varchar/blob/text/datetime
  • length:字段值的字节长度
  • PK:值为1表示字段为主键
  • NN:值为1表示值不能为空,NOT NULL
  • UQ:值为1表示值唯一
  • index:值为1表示字段为索引
  • FK:值为1表示字段为某表的外键,必须配合REFERENCES使用
  • REFERENCES:值的格式为 {'table':'user','field':'id'}
Example: 创建表 "dc_universe"

JSONObject ret = c.createTable("dc_universe", c.array(
"{'field':'id','type':'int','length':11,'PK':1,'NN':1,'UQ':1}",
"{'field':'name','type':'varchar','length':50,'default':null}",
"{'field':'age','type':'int'}"),
false)
.submit(SyncCond.db_success);
					

renameTable

c.renameTable(tableName, NewTableName).submit();

修改数据库中表的名字,tableName:表名;NewTableName:新的表名,两个名字都不能为空;

Example: 将表"dc_universe"改为"dc_name"

c.renameTable("dc_universe", "dc_name").submit();
					

dropTable

c.dropTable(tableName).submit();

从数据库删除一个表。表和它的所有数据将被删除;

Example: 删除表 "dc_universe".

c.dropTable("dc_universe").submit();
					

数据操作

insert

c.table(tableName).insert(raw).submit(SyncCond.db_success);

向数据库中插入数据。raw类型必须都是例子中的json格式的数据类型;

Example: 向表"posts"中插入一条记录.

c.table("posts").insert(c.array("{id: 1, 'name': 'peera','age': 22}", "{id: 2, 'name': 'peerb','age': 21}"))
.submit(SyncCond.db_success);
					

update

c.table(tableName).get(raw).update(raw).submit();

更新表中数据。如果get添加为空,则更新表中所有记录;其中raw为json格式字符串;

Example: 更新 id 等于 1 的记录:

c.table("posts")
.get(c.array("{'id': 1}"))
.update("{'age':52,'name':'lisi'}")
.submit(SyncCond.db_success);
					

delete

c.table(tableName).get(raw).delete().submit(SyncCond.db_success);

从表中删除对应条件的数据,如果get条件为空,则删除所有数据;

Example: 删除 id 等于 1 的记录.

c.table("comments")
.get(c.array("{'id': 1}"))
.delete()
.submit(SyncCond.db_success);
					

数据查询

get

c.table(tableName).get(raw).submit();

从数据库查询数据,后面可以进行其他操作,例如update、delete等;

Example: 查询 name 等于 aa 的记录.

c.table("posts")
.get(c.array("{'name': 'aa'}"))
.submit();



c.table("posts")
.get(c.array("{'name': 'aa'}"))
.withFields([])
.submit();
					

limit

c.table(tableName).get(raw).limit("{index:0,total:10}").withFields([]).submit();

对数据库进行分页查询.返回对应条件的数据;

Example: 查询 name 等于 aa 的前10条记录.

c.table("posts")
.get(c.array("{'name': 'aa'}"))
.limit("{index:0,total:10}")
.withFields([])
.submit();
					

order

c.table(tableName).get(raw).order(["{id:1}","{name:-1}"]).withFields([]).submit()

对查询的数据按指定字段进行排序;

Example: 按 id 升序,name 的降序排序

c.table("posts")
.get(c.array("{'name': 'aa'}"))
.order(c.array("{id:1}", "{name:-1}"))
.withFields([])
.submit();					
					

withFields

c.table(tableName).get(raw).withFields([field1,dield2,...]).submit();

从数据库查询数据,并返回指定字段,必须个get配合使用;

Example: 查询 name 等于 aa 的记录.

c.table("posts")
.get(c.array("{'name': 'aa'}"))
.withFields("['name','age']")
.submit();					
					

权限管理

grant

c.grant(tableName,user,rightInfo).submit();

c.grant(tableName,user,rightInfo,publicKey).submit();

向用户授予数据表操作权限,授权为非数据库操作,validate_success即可

tableName:授权的表名;

user:所要授权的账户地址;flags(array):所要授权的权限;

rightInfo:为授权字符串,例如:{select: true, insert: true, update: true,delete:false};

publicKey:被授权账户的公钥(选填字段,用于加密表);

用户权限有以下几种:Select、Insert、Update、Delete;

Example1: 向用户授予Insert、Delete操作权限.

c.grant("Table", "User.address", "{insert:true, delete:true}")
.submit(SyncCond.validate_success);
					
Example1: 取消用户Insert、Delete操作权限.

c.grant("Table", "User.address", "{insert:false, delete:false}")
.submit(SyncCond.validate_success);
					

事务相关


在事务开始和结束之间的insert,update,delete,assert语句会包装在一个原子操作中执行

与数据库的事务类似,事务中执行的语句要么全部成功,要么全部失败

执行事务类型交易主要涉及两个api:beginTran,commit.

beginTran开启事务,commit提交事务,事务中的操作全部执行成功事务才成功,有一个执行失败,则事务会自动回滚

在事务上下文中,不在支持单个语句的submit

beginTran

c.beginTran();

事务开始;

sqlAssert

c.table(tableName).get(jsonObj1).sqlAssert(jsonObj2);

断言操作,只能在事务中使用,assert为true则继续,false则回滚事务;

jsonObj1:查询条件;

jsonObj2:断言表达;

Example: 判断id等于1的记录age是否等于52并且name等于lisi,如果是则继续,如果有一个条件不满足或记录不存在,则回滚事务
c.table("posts")
.get({id: 1})
.assert({age:'52',name:'lisi'});
					
Example: 判断id等于1的记录集的行数是否等于1,如果是则继续,如果不是或表不存在,则回滚事务

c.table("posts")
.get({id: 1})
.assert({$rowcount:'1'});
					
Example: 判断表posts是否存在,如果有则继续,如果不存在,则回滚事务

c.table("posts").assert({$IsExisted:'1'});
					

commit

c.commit();

提交事务;

本次事务期间的所有操作都会打包提交到区块链网络

Example:

c.beginTran();

c.table("posts").insert({name: 'peera',age: 22}, {name: 'peerb',age: 21});
c.table("posts").get({id: 1}).assert({age:22,name:'peera'});
c.table("posts").get({id: 1}).update({age:52,name:'lisi'});
c.table("comments").delete({id: 1});

c.commit();	     				
	     			

区块信息

getLedger

获取区块信息

1.接口原型:JSONObject getLedger()

返回值:成功返回最新区块信息,失败返回null;

2. JSONObject getLedger(int ledger_index);

ledger_index:区块号;

返回值:成功为JSONObject,失败为null;

getLedgerVersion

接口原型:JSONObject getLedgerVersion ()

返回值说明:整数,当前的区块高度

getTransaction

查询某个hash下的交易信息;

接口原型:

同步:JSONObject getTransaction (String hash);

异步:void getTransaction(String hash,Callback cb);

参数说明:Hash:交易哈希值

同步接口返回值:成功为交易信息,失败为null

getTransactions

查询某账户提交的最新20笔交易

接口原型:

同步:JSONObject getTransactions(String address);

异步:void getTransactions(String address,Callback cb);

参数说明:要查询的账户地址 address:

同步接口返回值:成功为交易信息数组,失败为null


事件订阅

subscribeTable

c.event.subscribeTable(tablename ,owner, callback);

1.订阅某张表

tablename:为表名;

owner:为表的所有者地址;

callback:回调函数;

返回值示例:
{
	"owner":"zP8Mum8xaGSkypRgDHKRbN8otJSzwgiJ9M",
	"status":"validate_success",
	"tablename":"sub_message1", 
	"transaction": {
		… 
	},
	"type":"table"
}
	     			
Example: 用户订阅TestName表信息,表的创建者为zP8Mum8xaGSkypRgDHKRbN8otJSzwgiJ9M

c.event.subscribeTable("TestName", "zP8Mum8xaGSkypRgDHKRbN8otJSzwgiJ9M",new Callback(){

	@Override
	public void called(Object args) {
		//do something here
	}
});     				
	     			

unsubcribeTable

c.event.unsubcribeTable(owner, tablename);

2.取消订阅某张表

owner:为表的所有者地址;

tablename:为表名;

Example: 用户取消订阅TestName表信息.

c.event.unsubcribeTable("zP8Mum8xaGSkypRgDHKRbN8otJSzwgiJ9M");	     				
	     			

subscribeTx

c.event.subscribeTx(txid, callback);

3.订阅某个交易

txid:交易Hash

callback:回调函数

注:callback回调函数参数说明:


{ 
	"status":"validate_success",
	"transaction": {
		 … 
	},
	"type":"singleTransaction" 
}

					 
Example: 用户订阅交易Hash信息.

c.event.subscribeTx(txid, (data) -> {
	//do something here
}));  				
	     			

unsubscribeTx

c.event.unsubscribeTx(txid);

4.取消订阅某个交易

txid:交易Hash

Example: 用户取消订阅交易Hash信息.

c.event.unsubscribeTx(txid);   				
	     			

运算符

comparison operators

比较运算符

运算符 说明 语法
$ne 不等于 {field:{$ne:value}}
$eq 等于 {field:{$eq:value}} or {field:value}
$lt 小于 {field:{$lt:value}}
$le 小于等于 {field:{$le:value}}
$gt 大于 {field:{$gt:value}}
$ge 大于等于 {field:{$ge:value}}
$in 字段值在指定的数组中 {field:{$in:[v1, v2, ..., vn]}}
$nin 字段值不在指定的数组中 {field:{$nin:[v1, v2, ..., vn]}}

logical operators

逻辑符

逻辑符 说明 语法
$and 逻辑与 {$and:[{express1},{express2},...,{expressN}]}
$or 逻辑或 {$or:[{express1},{express2},...,{expressN}]}

fuzzy matching

模糊匹配

语法 说明
{"field":{"$regex":"/value/"}} like "%value%"
{"field":{"$regex":"/^value/"}} like "%value"

例子

where id > 10 and id < 100

对应 json 对象

{
	$and: [
		{
			id: {$gt: 10}
		},
		{
			id: {$lt: 100}
		}
	]
}
					
where id > 10 and id < 100

对应 json 对象

{
	$and: [
		{
			id: {$gt:10}
		},
		{
			id: {$lt:100}
		}
	]
}
					
where name = 'peersafe' or name = 'zongxiang'

对应 json 对象

{
	$or: [
		{
			name: {$eq:'peersafe'}
		},
		{
			name: {$eq:zongxiang}
		}
	]
}
					
where (id > 10 and name = 'peersafe') or name = 'zongxiang'

对应 json 对象

{
	$or: [
		{
			$and: [
				{
					id: {$gt:10}
				},
				{
					name:'peersafe'
				}]
		},
		{
			name:'zongxiang'
		}
	]
}
					
where name like '%peersafe%'

对应 json 对象

{
	name: {
		$regex:'/peersafe/'
	}
}
				
where name like '%peersafe'

对应 json 对象

{
	name: {
		$regex:'/^peersafe/'
	}
}