OpenDS Core SDK for Java
A Java library for OpenAPI's HTTP-based Core APIs.
下载地址
SDK安装
将压缩包中的opends-sdk-java-0.1.0-jar-with-dependencies.jar导入到本地项目工程中即可
注意事项
- jdk支持版本：1.7以上
- 字符编码使用UTF-8
- 支持的数据类型：number, string, date(建议使用 %Y-%m-%d %H:%M:%S 格式)
- 数据源名, 工作表名, 同一张表的不同字段名, title不可重复
- 当前的架构设计对于频繁的小量数据写入处理效率不高，所以建议还是尽量批量的更新数据， 但是大量的数据传输会提高等待时间，因此建议尽量将数据量控制在5万条左右
- ACCESS_TOKEN从BDP网站的开发者中心获取
SDK简介
- 工具类：
| 类 | 实例方法 | 描述 |
|---|---|---|
| BDPClient | BDPClient(String accessToken, String domain) | 构造方法 |
Map<String,DS> getAllDs() | 获取所有数据源对象 | |
| DS getDs(String name) | 根据数据源名获取数据源对象 | |
| DS createDs(String name) | 根据名字创建数据源 | |
| void deleteDs(String name) | 根据名字删除数据源 | |
| DS | Map<String, Table> getAllTables() | 获取该数据源的所有工作表对象 |
Table createTable(String name,List<Schema> schema,String[] uniqKey,String title) | 创建工作表 | |
| void deleteTable(String name) | 根据名字删除工作表 | |
| Table getTable(String name) | 根据名字获取工作表 | |
| void update(String[] tbNames) | 根据工作表名列表更新相应工作表 | |
| void updateAll() | 级联更新该数据源的下的所有工作表 | |
| String getDsId() | 获取数据源id | |
| Table | void insertDataByName(String[] fields, String[][] data) | 向指定的字段插入数据，根据字段名 |
| void insertDataById(String[] fieldIds, String[][] data) | 向指定的字段插入数据，根据字段id | |
| void bulkDelete(String where) | 根据where条件批量删除数据 | |
| void deleteDataByName(String[] fields, String[][] data) | 根据fields列表中的字段名删除数据行 | |
| void deleteDataById(String[] fieldIds, String[][] data) | 根据fields列表中的字段id删除数据行 | |
| void updateDataByName(String[] fields, String[][] data) | 根据fields列表中的字段名更新数据行 | |
| void updateDataById(String[] fieldIds, String[][] data) | 根据fields列表中的字段id更新数据行 | |
| void commit() | 提交原始工作表 | |
| void revert() | 回滚原始工作表中未提交的数据 | |
| void clean() | 清空该工作表 | |
List<Field> getFields() | 列出所有字段 | |
| void addField(String field,String type,String uniqIndex,String title) | 添加指定字段 | |
| void modifyTable(String alias) | 修改表的别名（在web端显示的名称) | |
| void modifyField(String field,String type,String uniqIndex,String title) | 修改字段属性 | |
| PreviewInfo preview() | 预览数据 | |
| TableInfo getInfo() | 获取表信息 | |
| String getId() | 获取表id |
- javaBean类：
| 类 | 描述 | 字段 | 字段描述 |
|---|---|---|---|
| Field | 描述字段信息 | String name | 字段名 |
| String field_id | 字段ID | ||
| String uniq_index | 是否为主键，‘1’代表是，'0'不是 | ||
| String type | 字段类型，只能是string/number/date | ||
| String title | 字段别名 | ||
| PreviewInfo | 预览数据对象 | List<Schema> schema | 字段信息列表 |
List<List<String>> data | 数据集合 | ||
| String data_count | 数据条数 | ||
| Schema | 表结构对象 | String name | 字段名 |
| String type | 字段类型 | ||
| String remark | 字段描述 | ||
| String title | 字段别名 | ||
| TableInfo | 描述工作表信息对象 | String tb_id | 工作表id |
| String name | 工作表名 | ||
| String data_count | 工作表记录数 | ||
| String title | 工作表别名 | ||
List<Field> fields | 字段列表 |
SDK说明
BDPClient
用于初始化客户端，进行数据源增、删、查操作等等。
构造方法:
- `BDPClient(String accessToken, String domain)`
- 示例:
```java
BDPClient client = new BDPClient(ACCESS_TOKEN, "domain");
```
实例方法:
- `Map<String,DS> getAllDs()` 获取所有数据源对象，返回键为数据源名字，值为相应数据源对象的Map。
- 参数:
* 无
- 返回:
* DS对象Map
- 示例:
```java
Map<String, DS> map = client.getAllDs();
```
- `DS getDs(String name)` 根据名字获取数据源，返回数据源对象
- 参数:
* name 数据源名称
- 返回:
* DS对象
- 示例:
```java
DS ds = client.getDs("dsName");
```
- `void deleteDs(String name)` 根据名字删除数据源
- 参数:
* name 数据源名称
- 返回:
* 无
- 示例:
```java
client.deleteDs("dsName");
```
- `DS createDs(String name)` 根据名字创建数据源，返回创建的数据源对象
- 参数:
* name 数据源名称
- 返回:
* 本次创建的DS对象
- 示例:
```java
DS ds = client.createDs("dsName");
```
DS
数据源类，可以管理该数据源内的各种工作表，并对工作表进行增、删、改、查等操作。
>通过调用BDPClient类的createDs方法来创建DS对象,不能通过直接实例化DS类来创建数据源.
>通过调用BDPClient类的getDs方法来获取相应的DS对象.
#### 使用
DS ds = client.getDs("dsName");
实例方法
- `Map<String, Table> getAllTables()` 获取该数据源的所有工作表对象，返回键为表名，值为工作表对象的Map
- 参数:
* 无
- 返回:
* Table对象Map
- 示例:
```java
Map<String, Table> tables = ds.getAllTables();
```
- `Table createTable(String name,List<Schema> schema,String[] uniqKey,String title)` 在该数据源中创建工作表，返回该工作表, schema中的type只能是"string"/"number"/"date"其中一种。对于每个字段的设定，remark和title参数可以为null。
- 参数:
* name 工作表名
* schema 描述表结构schema列表
* uniqKey 联合主键数组，可以为null
* title 工作表别名，可以为null
- 返回:
* 本次创建的Table对象
- 示例:
```java
List<Schema> schemas = new ArrayList<Schema>();
Schema schema1 = new Schema("field1", "string",null,null);
Schema schema2 = new Schema("field2", "string",null,null);
String[] uniqKey = new String[]{"field1"};
schemas.add(schema1);
schemas.add(schema2);
Table table = ds.createTable(name, schemas, uniqKey, null);
```
- `void deleteTable(String name)` 根据名字删除工作表
- 参数:
* name 工作表名
- 返回:
* 无
- 示例:
```java
ds.delete_table("tableName")
```
- `Table getTable(String name)` 根据名字获取工作表
- 参数:
* name 工作表名
- 返回:
* Table对象
- 示例:
```java
Table table = ds.getTable("tbName");
```
- `void update(String[] tbNames)` 根据工作表名列表更新相应工作表
- 参数:
* name 需要更新的工作表名列表
- 返回:
* 无
- 示例:
```java
String[] tables = new String[]{"tbName1","tbName2"};
ds.update(tables);
```
- `void updateAll()` 级联更新该数据源的下的所有工作表
- 参数:
* 无
- 返回:
* 无
- 示例:
```java
ds.updateAll();
```
- `String getDsId()` 获取数据源id
- 参数:
* name 无
- 返回:
* 数据源id
- 示例:
```java
String dsId = ds.get_id();
```
Table
工作表类，对工作表进行增、删、改的操作。
> 通过调用DS类的createTable方法而不是通过实例化Table类来创建新表。
> 通过调用DS类的getTable方法来获取相应表的Table实例。
#### 使用
```java
Table table = ds.getTable("tbName");
```
实例方法
- `void insertDataByName(String[] fields, String[][] data)` 向指定的字段插入数据，根据字段名
- 参数:
* fields 字段名数组
* data 存储表数据的二维数组
- 返回:
* 无
- 示例:
```java
String[] fields = {"field1","field2","birth"};
String[][] data = new String[][] { { "1", "data1", "1991-09-07 12:35:59" },
{ "2", "data2", "1994-08-23 02:41:50" } };
table.insertDataByName(fields, data);
```
- `void insertDataById(String[] fieldIds, String[][] data)` 向指定的字段插入数据，根据字段id
- 参数:
* fieldIds 字段id数组
* data 存储表数据的二维数组
- 返回:
* 无
- 示例:
```java
//获取fieldId
List<Field> fields = table.getInfo().getFields();
String[] fieldIds = new String[fields.size()];
int index = 0;
for (Field field : fields) {
fieldIds[index++] = field.getField_id();
}
String[][] data = new String[][] { { "1", "data1", "1991-09-07 12:35:59" },
{ "2", "data2", "1994-08-23 02:41:50" } };
table.insertDataByName(fields, data);
```
- `void bulkDelete(String where)` 根据where条件批量删除数据
- 参数:
* where 删除条件
- 返回:
* 无
- 示例:
```java
String where = "`id`=1";
table.bulkDelete(where);
```
- `void deleteDataByName(String[] fields, String[][] data)` 根据fields列表中的字段名删除数据行
- 参数:
* fields 字段名数组
* data 存储表数据的二维数组
- 返回:
* 无
- 示例:
```java
String[] fields = {"field1","field2","birth"};
String[][] data = new String[][] { { "1", "data1", "1991-09-07 12:35:59" },
{ "2", "data2", "1994-08-23 02:41:50" } };
table.deleteDataByName(fields, data);
```
- `void deleteDataById(String[] fieldIds, String[][] data)` 根据fields列表中的字段id删除数据行
- 参数:
* fieldIds 字段id数组
* data 存储表数据的二维数组
- 返回:
* 无
- 示例:
```java
String[][] data = new String[][] { { "1", "data1", "1991-09-07 12:35:59" },
{ "2", "data2", "1994-08-23 02:41:50" } };
//获取fieldId
List<Field> fields = table.getInfo().getFields();
String[] fieldIds = new String[4];
int index = 0;
for (Field field : fields) {
fieldIds[index++] = field.getField_id();
}
table.deleteDataById(fieldIds, data);
```
- `void updateDataByName(String[] fields, String[][] data)` 根据fields列表中的字段名更新数据行
- 参数:
* fields 字段名数组
* data 存储表数据的二维数组
- 返回:
* 无
- 示例:
```java
String[] fields = {"field1","field2","birth"};
String[][] data = new String[][] { { "1", "data1", "1991-09-07 12:35:59" },
{ "2", "data2", "1994-08-23 02:41:50" } };
table.updateDataByName(fields, data);
```
- `void updateDataById(String[] fieldIds, String[][] data)` 根据fields列表中的字段id更新数据行
- 参数:
* fieldIds 字段id数组
* data 存储表数据的二维数组
- 返回:
* 无
- 示例:
```java
String[][] data = new String[][] { { "1", "data1", "1991-09-07 12:35:59" },
{ "2", "data2", "1994-08-23 02:41:50" } };
//获取fieldId
String[] fieldIds = new String[fields.size()];
int index = 0;
for (Field field : fields) {
fieldIds[index++] = field.getField_id();
}
table.updateDataById(fieldIds, data);
```
- `void commit()` 提交原始工作表
- 参数:
* 无
- 返回:
* 无
- 示例:
```java
Table table = ds.getTable("tableName");
table.commit();
```
- `void revert()` 回滚原始工作表中未提交的数据
- 参数:
* 无
- 返回:
* 无
- 示例:
```java
Table table = ds.getTable("tableName");
table.revert();
```
- `void clean()` 清空该工作表
- 参数:
* 无
- 返回:
* 无
- 示例:
```java
Table table = ds.getTable("tableName");
table.clean();
```
- `List<Field> getFields()` 列出所有字段
- 参数:
* 无
- 返回:
* table下的所有Field列表
- 示例:
```java
List<Field> fields = table.getFields()
```
- `void addField(String field,String type,String uniqIndex,String title)` 添加指定字段, type只能是"string"/"number"/"date"其中一种。uniqIndex为1表示该字段为主键，0为非主键, title为字段别名,可以为null。
- 参数:
* field 字段名
* type 字段类型，只能是string/number/date
* uniqIndex 是否为联合主键，1是，0不是，可以为null
* title 字段别名，可以为null
- 返回:
* 无
- 示例:
```java
table.addField("newField", "string", "1", "alias");
```
- `void deleteField(String field)` 删除指定字段
- 参数:
* field 字段名
- 返回:
* 无
- 示例:
```java
Table table = ds.getTable(tableName);
table.deleteField("field1");
```
- `void modifyTable(String alias)` 修改表的别名（在web端显示的名称)
- 参数:
* alias 表别名
- 返回:
* 无
- 示例:
```java
table.modifyTable("aliasName");
```
- `void modifyField(String field,String type,String uniqIndex,String title)` 修改字段属性,type只能是"string"/"number"/"date"其中一种。uniqIndex为1表示该字段为主键，0为非主键， title为字段别名，可以为null。
- 参数:
* field 字段名
* type 字段类型，只能是string/number/date
* uniqIndex 是否为联合主键，1是，0不是，可以为null
* title 字段别名，可以为null
- 返回:
* 无
- 示例:
```java
table.modifyField("addField", "number", "1", "haha");
```
- `PreviewInfo preview()` 预览数据
- 参数:
* 无
- 返回:
* PreviewInfo对象
- 示例:
```java
PreviewInfo info = table.preview();
```
- `TableInfo getInfo()` 获取表信息
- 参数:
* 无
- 返回:
* TableInfo对象
- 示例:
```java
TableInfo info = table.getInfo();
```
- `String getId()` 获取表id
- 参数:
* 无
- 返回:
* 工作表id
- 示例:
```java
String tbId = table.getId();
```
javaBean
- 用于保存返回信息的javaBean，如：PreviewInfo，TableInfo，Field，Schema等均在cn.bdp.bean中
异常信息
- 所有的服务器端异常都将抛出包含错误码以及错误信息的BDPException，错误码可以参照API文档
- 本地的异常将直接抛出带英文信息的BDPException
Example
获取指定数据源对象并获取其中所有的工作表
import cn.bdp.bean.Field;
import cn.bdp.bean.Schema;
import cn.bdp.bean.TableInfo;
import cn.bdp.sdk.BDPClient;
import cn.bdp.sdk.DS;
import cn.bdp.sdk.Table;
BDPClient client = new BDPClient(ACCESS_TOKEN, "domain");
DS ds = client.getDs("dsName");
Map<String,Table> tablesMap = ds.get_all_tables();
Table table = ds.getTable("tableName");
table.commit();