【TcaplusDB知识库】Java快速上手TDR表的增删查改操作

说明

TDR表是基于TDR协议设计的TcaplusDB表，TDR协议是腾讯自研的RPC通信协议，用于TcaplusDB存储数据的序列化、反序列化等操作，相比于PB表(Protocol协议表)在传输效率及传输质量上有一定优势，在腾讯游戏内部有广泛应用基础，具体关于TDR表的定义说明可参考章节：表定义语言(PB,TDR)。TDR表定义以xml格式来定义表结构，支持丰富的数据类型，请参考章节：数据类型(PB, TDR)。

快速入手TDR协议表的开发涉及几个步骤，下面介绍如何基于TcalusDB本地Docker版环境，快速上手基于Java进行TDR表的增删查改操作。所有操作均在申请的开发测试机或云主机进行。

基础环境准备

Docker环境准备

在开始示例代码演示之前，需要提前准备好TcaplusDB本地Docker环境及tcapluscli工具，具体请参考资料：[Linux] TcaplusDB Local版部署。

Java环境准备

Java SDK示例依赖JDK环境部署，JDK版本：openjdk-1.7以上。在不同环境安装方式如下：

#CentOS7环境安装,安装jdk1.8版本
yum install java-1.8.0-openjdk java-1.8.0-openjdk-devel
 
#Debian8.2环境安装，安装1.7版本
apt-get install openjdk-7-jre openjdk-7-jdk

TcaplusDB环境准备

TcaplusDB表准备

准备TDR表示例文件

表名: test, 表类型: GENERIC，表定义具体内容保存在test.xml。文件具体内容如下：

<?xml version="1.0" encoding="GBK" standalone="yes" ?>               
<metalib name="table_test" tagsetversion="1" version="1">               
    <struct name="test" version="1" splittablekey="gameid"  primarykey="gameid,itemid,name">               
        <entry name="gameid" type="uint" />                
        <entry name="itemid" type="uint" />               
        <entry name="name" type="string" size="5" />               
        <entry name="typeid" type="uint8"/>               
        <entry name="data" type="tinyuint" defaultvalue="9"/>               
        <entry name="uname" type="string" size="5" defaultvalue="ab"/>               
        <index name="index_id" column="gameid" />               
    </struct>
</metalib>

TcaplusDB集群准备

对于TcaplusDB,在创建表之前需要创建对应的表集群。对于Docker本地版，集群已经默认创建好一个供大家使用，所以不用再创建集群。

TcaplusDB表格组准备

表创建依赖于表格组，需要在默认集群下创建一个表格组。创建表格组依赖tcapluscli工具，关于tcapluscli的使用，具体可参考：表格组相关操作命令。

#查看表格组帮助命令
./tcapluscli tablegroup -h
#创建一个表格组，id指定为4，　endpoint-url，用于docker环境连接使用, group name由字母、数字和下划线组成
./tcapluscli tablegroup create --endpoint-url=http://localhost　--access-id=2 --group-id=4　--group-name=zone_4

TcaplusDB表创建

现在正式进入表创建环节，在上述表格组基础上创建一个TDR表，执行创建表命令，如下所示：

#查看表创建命令提示帮助
./tcapluscli table -h
 
#创建一个表, 指定endpoint-url, 集群接入ID: 2 (TDR集群), 表格组id: group-id, 表类型: TDR, 表定义文件: table_test.xml,放当前路径
./tcapluscli table create --endpoint-url=http://localhost  --access-id=2 --group-id=4 --schema-type=TDR --schema-file=test.xml
 
#查看表是否创建成功
./tcapluscli table describe --endpoint-url=http://localhost --access-id=2 --group-id=4 --list

示例代码

获取公共环境信息

参数	值	获取方法
目录服务地址列表	*.*.*.*:9999	获取目录服务地址列表
业务ID/集群ID	8	获取集群ID
业务密码	****************	获取业务密码
表格组ID	4	获取表格组ID
表格名称	test

获取依赖包

包名	下载地址	用途
tcaplus-service-api-3.32.0	下载	Java SDK包
org.slf4j:slf4j-api:1.7.5	下载	Java SDK依赖的第三方包，用于输出日志 。

如果使用Maven作为Java项目管理工具，则可以将获取的jar包，导入到Maven仓库中，再通过配置pom.xml，引入到项目中即可。

示例代码

将下述示例代码保存至Example.java

示例代码

import com.tencent.tcaplus.client.Client;
import com.tencent.tcaplus.client.ClientFactory;
import com.tencent.tcaplus.client.Record;
import com.tencent.tcaplus.client.Request;
import com.tencent.tcaplus.client.Response;
import com.tencent.tdr.tcaplus_protocol_cs.TcaplusProtocolCsConstants;
 
import java.util.ArrayList;
import java.util.List;
 
public class Example {
    
    
 
    public static void main(String[] arguments) {
    
    
        // 1. 准备环境信息
        // 1.1. 目录服务地址列表,对于Docker本地版：dir地址为docker部署的机器内网ip地址，端口默认为9999;对于线上云环境，为集群连接内网地址，端口默认为9999
        List<String> dirList = new ArrayList<String>();
        dirList.add("tcp://localhost:9999");
        // 1.2. 业务ID,接入ID,对于Docker本地版: TDR表默认为2，PB表默认为3; 对于线上云环境，根据实际创建的集群接入ID填写
        int appId = 2;
        // 1.3. 业务密码,对于Docker本地版:可以通过打开oms本地环境查看对应TDR业务的集群密码,业务管理－>业务维护->选择TDR业务，查看集群密码; 对于线上云环境，根据自行设置的密码填写
        String appPassword = "****************";
        // 1.4. 表格组ID，替换为自己创建的表格组id
        int tableGroupId = 4;
        // 1.5. 表格名称, 替换为自己创建的表名
        String tableName = "test";
 
        // 2. 创建客户端
        Client client = ClientFactory.createClient(appId, tableGroupId, appPassword, dirList);
        try {
    
    
            // 插入数据
            insert(client, tableName);
 
            // 获取数据
            select(client, tableName);
 
            // 修改数据
            update(client, tableName);
 
            // 删除数据
            delete(client, tableName);
        } finally {
    
    
            // 3. 销毁客户端对象
            ClientFactory.destroyClient(client);
        }
    }
 
    private static void insert(Client client, String tableName) {
    
    
        // 1. 构造插入数据的请求
        // 1.1. 获取请求对象。为了提升SDK性能，Request对象是复用的
        Request request = client.acquireRequest();
        // 1.2. 设置请求类型和目标表名
        request.setCmd(TcaplusProtocolCsConstants.TCAPLUS_CMD_INSERT_REQ);
        request.setTableName(tableName);
        // 1.3. 设置数据各字段的值，这里要注意Key字段和Value字段，使用的是不同的方法设置字段值
        Record record = request.addRecord();
        record.setKeyInt("gameid", 1);
        record.setKeyInt("itemid", 1);
        record.setKeyString("name", "test");
        record.setValueByte("typeid", (byte) 1);
        record.setValueByte("data", (byte) 1);
        record.setValueString("uname", "test");
 
        // 2. 发送请求，并获取结果
        Response response = client.poll(request);
 
        System.out.println(response.toString());
        // 3. 处理结果
        if (response.getResult() == 0) {
    
    
            // 插入数据成功
            // TODO 可在此处添加处理数据插入成功的后续处理代码
        } else {
    
    
            // 插入数据失败
            // TODO 可在此处添加处理数据插入失败的后续处理代码
        }
    }
 
    private static void select(Client client, String tableName) {
    
    
        // 1. 构造查询数据的请求
        // 1.1. 获取请求对象。为了提升SDK性能，Request对象是复用的
        Request request = client.acquireRequest();
        // 1.2. 设置请求类型和目标表名
        request.setCmd(TcaplusProtocolCsConstants.TCAPLUS_CMD_GET_REQ);
        request.setTableName(tableName);
        // 1.3. 设置各个Key字段的值
        Record record = request.addRecord();
        record.setKeyInt("gameid", 1);
        record.setKeyInt("itemid", 1);
        record.setKeyString("name", "test");
        // 1.4. 添加需要查询的Value字段
        request.addFieldName("typeid");
        request.addFieldName("data");
        request.addFieldName("uname");
 
        // 2. 发送请求，并获取结果
        Response response = client.poll(request);
 
         
 
        // 3. 处理结果
        if (response.getResult() == 0) {
    
    
            // 查询数据成功
            Record result = response.fetchRecord();
            System.out.println(result.toString());
            // TODO 可在此处添加处理数据查询成功的后续处理代码
        } else {
    
    
            // 查询数据失败
            // TODO 可在此处添加处理数据查询失败的后续处理代码
            System.out.println(response.toString());
        }
    }
 
    private static void update(Client client, String tableName) {
    
    
        // 1. 构造更新数据的请求
        // 1.1. 获取请求对象。为了提升SDK性能，Request对象是复用的
        Request request = client.acquireRequest();
        // 1.2. 设置请求类型和目标表名
        request.setCmd(TcaplusProtocolCsConstants.TCAPLUS_CMD_UPDATE_REQ);
        request.setTableName(tableName);
        // 1.3. 设置各Key字段的值。说明：Key字段值是不允许更新的
        Record record = request.addRecord();
        record.setKeyInt("gameid", 1);
        record.setKeyInt("itemid", 1);
        record.setKeyString("name", "test");
        // 1.4. 设置各Value字段的新值
        record.setValueByte("typeid", (byte) 1);
        record.setValueByte("data", (byte) 1);
        record.setValueString("uname", "test");
 
        // 2. 发送请求，并获取结果
        Response response = client.poll(request);
 
        System.out.println(response.toString());
 
        // 3. 处理结果
        if (response.getResult() == 0) {
    
    
            // 更新数据成功
            // TODO 可在此处添加处理数据更新成功的后续处理代码
        } else {
    
    
            // 更新数据失败
            // TODO 可在此处添加处理数据更新失败的后续处理代码
        }
    }
 
    private static void delete(Client client, String tableName) {
    
    
        // 1. 构造删除数据的请求
        // 1.1. 获取请求对象。为了提升SDK性能，Request对象是复用的
        Request request = client.acquireRequest();
        // 1.2. 设置请求类型和目标表名
        request.setCmd(TcaplusProtocolCsConstants.TCAPLUS_CMD_DELETE_REQ);
        request.setTableName(tableName);
        // 1.3. 设置各Key字段的值
        Record record = request.addRecord();
        record.setKeyInt("gameid", 1);
        record.setKeyInt("itemid", 1);
        record.setKeyString("name", "test");
 
        // 2. 发送请求，并获取结果
        Response response = client.poll(request);
         
        System.out.println(response.toString());
        // 3. 处理结果
        if (response.getResult() == 0) {
    
    
            // 删除数据成功
            // TODO 可在此处添加处理数据删除成功的后续处理代码
        } else {
    
    
            // 删除数据失败
            // TODO 可在此处添加处理数据删除失败的后续处理代码
        }
    }
 
}

示例代码运行

示例代码编译

将上述下载的tcaplus-service-api-3.32.0.jar包和slf4j-api-1.7.5.jar包放至和Demo.java同等级目录，执行如下命令编译：

javac -cp ./tcaplus-service-api-3.32.0.jar:./slf4j-api-1.7.5.jar Demo.java

示例代码运行

java -cp ./tcaplus-service-api-3.32.0.jar:./slf4j-api-1.7.5.jar Demo

---

TcaplusDB是腾讯出品的分布式NoSQL数据库，存储和调度的代码完全自研。具备缓存+落地融合架构、PB级存储、毫秒级时延、无损水平扩展和复杂数据结构等特性。同时具备丰富的生态、便捷的迁移、极低的运维成本和五个九高可用等特点。客户覆盖游戏、互联网、政务、金融、制造和物联网等领域。