Memcached学习笔记 ― 第四部分:Memcached Java 客户端-gwhalin(5)-主要API解析

找了很久都找不到官方的APIdoc，木有办法，只有看源代码整理个。

SocketIOPool

主要负责客户端连接池，通讯和定位。2.6.0后的版本是由schooner重新实现的，只是保持了API接口没有改变，新的实现是：com.schooner.MemCached.SchoonerSockIOPool

public static SockIOPool getInstance()
获得连接池的单态方法。这个方法有一个重载方法getInstance( String poolName )，每个poolName只构造一个SockIOPool实例。缺省构造的poolName是default。

public void setServers( String[] servers )
设置连接池可用的cache服务器列表

public void setWeights( Integer[] weights )
设置连接池可用cache服务器的权重，与servers对应，建议有多少太服务器就相应设置多少个权重值，否则可以不设置，默认都是1：1对应。

public void setInitConn( int initConn )
设置开始时每个cache服务器的可用连接数

public void setMinConn( int minConn )
设置每个服务器最少可用连接数

public void setMaxConn( int maxConn )
设置每个服务器最大可用连接数

public void setMaxIdle( long maxIdle )
设置可用连接池的最长等待时间

public void setMaintSleep( long maintSleep )
设置连接池维护线程的睡眠时间，设置为0，维护线程不启动

public void setNagle( boolean nagle )
设置是否使用Nagle算法，因为我们的通讯数据量通常都比较大（相对TCP控制数据）而且要求响应及时，因此该值需要设置为false（默认是true）

public void setSocketTO( int socketTO )
设置socket的读取等待超时值

public void setSocketConnectTO( int socketConnectTO )
设置socket的连接等待超时值

public void setAliveCheck( boolean aliveCheck )
设置连接心跳监测开关。设为true则每次通信都要进行连接是否有效的监测，造成通信次数倍增，加大网络负载，因此该参数应该在对HA要求比较高的场合设为TRUE，默认状态是false。

public void setFailback( boolean failback )
设置连接失败恢复开关，设置为TRUE，当宕机的服务器启动或中断的网络连接后，这个socket连接还可继续使用，否则将不再使用，默认状态是true，建议保持默认。

public void setFailover( boolean failover )
设置容错开关，设置为TRUE，当当前socket不可用时，程序会自动查找可用连接并返回，否则返回NULL，默认状态是true，建议保持默认。

public void setHashingAlg( int alg )
设置服务器定位算法：
1. 使用String.hashCode()获得hash code,该方法依赖JDK，可能和其他客户端不兼容，建议不使用
2. 使用original 兼容hash算法，兼容其他客户端
3. 使用CRC32兼容hash算法，兼容其他客户端，性能优于original算法
4. 使用一致性HASH算法
采用前三种hash算法的时候，查找cache服务器使用余数方法。采用最后一种是一致性HASH，也是默认算法。

public void initialize()
设置完pool参数后最后调用该方法，启动pool。

public void shutdown
释放连接池pool，释放资源。

MemCachedClient主要方法

 

add方法

public boolean add(String key, Object value)
public boolean add(String key, Object value, Integer hashCode)
public boolean add(String key, Object value, Date expiry)
public boolean add(String key, Object value, Date expiry, Integer hashCode)
将数据添加到cache服务器,如果保存成功则返回true
如果cache服务器存在同样key，则返回false
add有4个重载方法，key和value是必须的参数，还有过期时间，hash码两个可选参数
注意：
1. 官方协议支持的是UNIX DATE或当前时间秒的偏移量，这里的API支持的是是java.util.Date。
2. hashCode是用于客户端分布式定位的自定义hashCode值。可以不用设置，客户端会根据设置的算法，计算key的hashCode来定位。

set方法

public boolean set(String key, Object value)
public boolean set(String key, Object value, Date expiry)
public boolean set(String key, Object value, Date expiry, Integer hashCode)
设置key对应的缓存，缓存中是否存在都可以使用。
有3个重载，key和value是必须的。过期时间和hashCode是可选。

replace方法

public boolean replace(String key, Object value)
public boolean replace(String key, Object value, Integer hashCode)
public boolean replace(String key, Object value, Date expiry)
public boolean replace(String key, Object value, Date expiry, Integer hashCode)
将数据替换cache服务器中相同的key,如果保存成功则返回true，如果缓存不存在，会返回false，请注意add/set/replace的微妙区别。

append/prepend

public boolean append(String key, Object value)
public boolean append(String key, Object value, Integer hashCode)
public boolean prepend(String key, Object value)
public boolean prepend(String key, Object value, Integer hashCode)
append表示在现有缓存前添加数据，生成新的缓存；prepend表示在现有缓存后添加数据，生成新的缓存。
分别提供2个重载。设置成功返回true，其它或Key不存在返回false。

get方法

public Object get(String key)
public Object get(String key, Integer hashCode)

get方法从cache服务器获取一个数据，没有提供独立的读取超时，是通过SocketIOPool. setSocketTO(int socketTO)统一设置的。

gets方法

public MemcachedItem gets(String key)
public MemcachedItem gets(String key, Integer hashCode)
gets出来会返回缓存值外，还会返回当前缓存的版本号，一般是用于协同CAS完成原子操作使用。

getMulti方法

public Map<String, Object> getMulti(String[] keys)
public Map<String, Object> getMulti(String[] keys, Integer[] hashCodes)
public Map<String, Object> getMulti(String[] keys, Integer[] hashCodes, boolean asString)
使用getMulti方法从cache服务器获取一组数据，get方法的数组实现，输入参数keys是一个key数组，返回是一个map。

getMultiArray方法

public Object[] getMultiArray(String[] keys)
public Object[] getMultiArray(String[] keys, Integer[] hashCodes)
public Object[] getMultiArray(String[] keys, Integer[] hashCodes, boolean asString)
返回缓存的数组。

CAS方法

public boolean cas(String key, Object value, long casUnique)
public boolean cas(String key, Object value, Date expiry, long casUnique)
public boolean cas(String key, Object value, Date expiry, Integer hashCode, long casUnique)
原子设置缓存操作，通过版本号casUnique保证设置的唯一性，如果发现服务器的缓存版本与传入的不同，则放弃设置缓存，返回false。请参见前面协议详解。

Count计数相关方法

public boolean storeCounter(String key, long counter)
public boolean storeCounter(String key, Long counter)
public boolean storeCounter(String key, Long counter, Integer hashCode)

public long getCounter(String key)
public long getCounter(String key, Integer hashCode)

public long incr(String key)
public long incr(String key, long inc)
public long incr(String key, long inc, Integer hashCode)
public long decr(String key)
public long decr(String key, long inc)
public long decr(String key, long inc, Integer hashCode)

public long addOrIncr(String key)
public long addOrIncr(String key, long inc)
public long addOrIncr(String key, long inc, Integer hashCode)
public long addOrDecr(String key)
public long addOrDecr(String key, long inc)
public long addOrDecr(String key, long inc, Integer hashCode)
1. 使用storeCounter方法初始化一个计数器
2. 使用getCounter方法获取当前的计数器值
3. 使用incr方法对计数器增量操作，只有一个key的方法默认加1。
4. 使用decr对计数器减量操作，只有一个key的方法默认减1。
5. addOrIncr，addOrDecr：key存在则与incr和decr相同，不存在则相当于storeCounter

setPrimitiveAsString方法

public void setPrimitiveAsString( boolean primitiveAsString )
设置cache数据的原始类型存储方式是String，默认值是false，只有在确定cache的数据类型是string的情况下才设为true，这样可以加快处理速度。

setDefaultEncoding方法

public void setDefaultEncoding( String defaultEncoding )
当primitiveAsString为true时使用的编码转化格式，默认值是utf-8，如果确认主要写入数据是中文等非ASCII编码字符，建议采用GBK等更短的编码格式