Tair用户使用手册

1 前提

Tair集群搭建完毕。

2 使用java客户端

2.1 初始化方式

假设tair集群configserver地址和端口为192.168.1.100:5198,groupname为group_1 初始化方式如下

DefaultTairManagerdefaultTairManager= new DefaultTairManager(); Listcs = new ArrayList(); cs.add(“192.168.1.100:5198”);

defaultTairManager.setConfigServerList(cs); defaultTairManager.setGroupName(“group_1”); defaultTairManager.init();

2.2 接口说明

put

ResultCodeput(int namespace, Serializablekey, Serializable value)

描述

写入数据，key若存在则强制更新，不过期

参数：

namespace - 申请时分配的namespace key - key，不超过1k

value - 可序列化对象value，不超过1M。基于性能考虑，建议在10k之内。

返回值

ResultCode对象。ResultCode.SUCCESS表示写成功，其他表示写失败。其他返回值参见2.4 节常见返回码说明。

另见

ResultCode put(int namespace, Object key, Serializable value, int version)，ResultCode put(int namespace, Object key, Serializable value, int version, intexpireTime)

put

ResultCodeput(int namespace, Serializablekey, Serializable value, int version)

描述

写入数据，可用version实现并发处理，不过期

参数：

namespace - 申请时分配的namespace key - key，不超过1k

value -可序列化对象value，不超过1M。基于性能考虑，建议在10k之内。 version -参见 2.3节特殊参数说明。

返回值

ResultCode对象。ResultCode.SUCCESS表示写成功，其他表示写失败。其他返回值参见2.4 节常见返回码说明。

另见

ResultCodeput(int namespace, Object key, Serializable value)

ResultCodeput(int namespace, Object key, Serializable value, int version, intexpireTime)

put

ResultCodeput(int namespace, Serializablekey, Serializable value, int version, intexpireTime)

描述

写入数据，可设置版本号和过期时间

参数：

namespace - 申请时分配的namespace。 key - key，不超过1k

value -可序列化对象value，不超过1M。基于性能考虑，建议在10k之内。

version参见 2.3节特殊参数说明。

expireTime–参见2.3节特殊参数说明。

返回值

ResultCode对象。ResultCode.SUCCESS表示写成功，其他表示写失败。其他返回值参见2.4 节常见返回码说明。

另见

ResultCode put(int namespace, Object key, Serializable value)，ResultCode put(int namespace, Object key, Serializable value, int version)

get

Resultget(int namespace, Serializablekey)

描述

读取key相对应的value。

参数

namespace - 申请时分配的namespace。 key - key，不超过1k。

返回值

Result对象，可用isSuccess()方法判断请求是否成功，再用getRc()方法获取到ResultCode。isSuccess有两种情况，ResultCode.SUCCESS表示读成功，ResultCode.DATANOTEXSITS表示数据不存在。其余情况皆表示读取失败。其他返回值参见2.4 节常见返回码说明。

delete

ResultCodedelete(int namespace, Serializablekey)

描述

删除key。

参数：

namespace - 申请时分配的namespace key - key，不超过1k

返回值

ResultCode对象，ResultCode.SUCCESS表示删除成功。其他返回值参见2.4 节常见返回码说明。

2.3 特殊参数说明

expiredTime

expiredTime是指数据的过期时间。一旦超过过期时间，数据将对应用不可见，后端清理策略和应用无关。对应用来说，过期时间始终是精确的。

调用接口时，expiredTime单位是秒。expireTime<= 0，表示数据永不过期。expireTime> 0，表示设置过期时间。若expireTime>当前时间的时间戳（即Unix时间戳，需转换成距1970-1-1 00:00:00的秒数，比如：2014-01-01 00:00:00，则设置expireTime为1388505600），则表示使用绝对时间，否则使用相对时间。

version

version的作用

在Tair的put接口中，有一个version参数，这个参数是为了解决并发更新同一个数据而设置的。

很多情况下，更新数据是先get，修改get回来的数据，然后put回系统。如果有多个客户端get到同一份数据，都对其修改并保存，那么先保存的修改就会被后到达的修改覆盖，从而导致数据丢失问题。在某些情况下，这个是我们不希望发生的。比如客户端A和B取到数据{key, value}，A将value修改为value_a，B将value修改为value_b，A先保存，B然后保存，则最终的value为value_b，这时A的修改就不可见了。 version是为了防止这中情况而设置的。

服务器端version初始化为0，当数据第一次put时，version增加为1。后续每次更新数据，服务器端都会将version加1。每次get数据，服务器都会返回当前数据的版本，如果Tair中的数据版本与更新接口中传入的version相同，此次更新才会成功。否则如果在get与更新之间，数据被更新，导致Tair中的version与client传来的version不一致，该次更新会失败，返回ResultCode.VERERROR。version不会无增大，当version达到int16的最大值后，会重置为1。

如果应用不关心并发更新的一致性，调用客户端接口时，version必须不传或者传入0。 注意：

1. version的增加是服务器端的行为，tair并不支持多版本数据。另外，更新也是使用put接口。

2. version的值是由服务器端决定的，和client指定的version值无关。 version使用方法

get接口返回的是DataEntry对象，该对象中包含get到的数据的版本号，可以通过getVersion()接口获得该版本号。在put时，将该版本号作为put的参数即可。如果不考虑版本问题，则可设置version参数为0，系统将强行覆盖数据，即使版本不一致。

如果返回version不一致，怎么办？

如果更新所基于的version和系统中当前的版本不一致，则服务器会返回

ResultCode.VERERROR。这时你可以选择重新get数据，然后在新版本的数据上修改；或者设置version为0重新请求，以达到强制更新的效果。 version具体使用案例

如果应用有10个client会对key进行并发put，那么操作过程如下：

1. get key。如果get key成功，则进入步骤2；如果数据不存在，则进入步骤3. 2. 在调用put的时候将get key返回的verison重新传入put接口。服务端根据version是否匹配来返回client是否put成功。

3. get key数据不存在，则新put数据。此时传入的version必须不是0和1，其他的值都可以（例如10，要保证所有client是一套逻辑）。 不传入0是因为，tair会认为强制覆盖；

不传入1是因为，会出现两个client都写入成功的情况，不能防止并发。假设这样一个场景，client A第一次put key，写入成功，这时服务器端version为1。如果client B设置version为1，服务器端接收到后比较version正确，那么client B也会写成功。这和我们的预期就不一致了。而把version设为其他值时，服务器端接收到后比较version不同，则可以返回version error，client B就写失败了，需要重新get后获取到version值再进行更新。 案例分析：分布式锁

tair中存在该key，则认为该key所代表的锁已被lock；不存在该key，在未加锁。操作过程和上面相似。业务方可以在put的时候增加expire，已避免该锁被长期锁住。 我该不该使用Version？

这取决于用户对数据一致性的要求，如果对数据一致性有较高的要求，并且访问并发高，有很多类似append的操作，那么通过version可以避免数据的意外结果。 当不需要关心并发的时候，不传入或者传入version为0。 什么情况下version会重置为1？

第一次put到tair，或version已经达到int16的最大值。 NOTE：原则上，用户在通过 Get 接口拿到真实 version 之前，『不应该』对 version 的当前值做任何假定。

2.4 常见返回码说明

code msg 0 success 1 data not exist -1 connection error or timeout 含义 操作成功 该key在tair中不存在 与tair服务器交互失败或超时 服务器端接收到未知包 key的长度超过 解决方法 确认报错接口是否为合法接口。， key长度超过1k，需减小key长度，过大key将极大影响集群性能。 value长度超过1M，建议value-2 unknown error -5 key length error -6 value length error value的长度超过 批量操作接口（如mget）部分成功 该key将由另一台 proxy ds服务 invalid报错，server端队列满 最大最大不要超过10k，过大value将极大影响集群性能。 有部分key请求失败，遍历返回值可知道哪些key操作失败。 集群发生迁移，请稍等片刻后重试。 -10 partly success -3967 key should proxy server-side -3968 task-queue overflowed count reach bound 计数器接口和普通接口不能混用，incr/decr前不要put，prefix系列类似。 接口参数使用错误，具体参见百科开发文档 server端数据迁移中，请稍等片刻重试 server端数据迁移中，请稍等片刻重试 服务器故障。 客户端发包失败，请检查应用服务器网络状态 检查key或value大小是否为0，key是否大于1k，value是否大于1M。如果是incr/decr/setcount等计数类接-3979 count reach zero count减到了0 -3980 count超过了 key已用普通接口写入，无法用计数器接口覆盖 -3981 can not override invalid argument -3982 参数非法 server端数据迁移中 key对应的数据服务器发生变化 服务器无法提供服务 -3984 migrate busy -3986 -3987 -3990 write not on master server can not work send packet failed 发包失败 -3991 item size error key或value大小不对 口，还要看value是否小于0。 1. 确认tair初始化是否成功，如果没有初始化成功，那么写入和读取接口都会返回-3994错误。 2. 如果是写入接口报该错误，一般是key或者value传入的对象中存在有对象没有序列化函数，请详细排查自定义对象中的各成员变量。class要仔细检查每一个-3994 serialize error 序列化错误 成员！！！ 写失败还有一种情况是value > 1M。 3. 如果是读取接口报该错误，a.请查看是否传入的key或者value的序列化方式发生变化了，比如字段序列化顺序发生变化，或者增减了字段，class路径发生变化等等。b. 请确认你的代码能够找到要反序列化的自定义类. -3997 version error -3999 server error counter out of range 指定的version和server不一致 server异常 计数器超出设置的-5114 [lowbound, upbound)返回，没有设置范围的则是超出了int（有符号数）的范围。 -6000 rpc overflow 服务器端限流。 用户需检查是否有热点访问，或者是流量访问突增。 一般发生在高并发写的情况，防止并发。具体参见关于version的介绍