Memcached-Java-Client 3.0.0 API 解析

  Memcached-Java-Client是一个Memcached Java客户端API，相对比较古老了，Github已经停止更新了，最后时间已经是2012年左右的事情了。但不论其是否活跃，但对于研究或者应用Memcached来说，并没有太大的妨碍。

  Github地址：http://github.com/gwhalin/Memcached-Java-Client。

  源码搭建

  首先访问Github源码地址，选择相应版本就可以，本文选择3.0.0版本源码进行搭建。

​

  源码是依赖Maven构建的，只需按照正常的Maven项目导入到Eclipse中即可。

  Memcached-Java-Client主要包括SockIOPool和MemCachedClient两个类，下面对两个类进行详细解析。

  SockIOPool

  ● public static synchronized SockIOPool getInstance(String poolName)

  根据给定池名称创建或者查找池。

  ● public static SockIOPool getInstance(boolean isTcp)

  根据给定是否TCP标志创建或者查找池。

  ● public static SockIOPool getInstance(String poolName, boolean isTcp)

  根据给定池名称和是否TCP标志创建或者查找池。

  ● public static SockIOPool getInstance()

  默认池方法，默认池名称是default。

  ● public void setServers(String[] servers)

  设置缓存服务器列表，格式为host:port。

  ● public void setWeights(Integer[] weights)

  设置缓存服务器权重，与servers数组一一对应。

  ● public void setInitConn(int initConn)

  设置可用池中每个服务器的初始连接数。

  ● public void setMinConn(int minConn)

  设置可用池中要维护的最小备用连接数。

  ● public void setMaxConn(int maxConn)

  设置可用池中允许的最大备用连接数。

  ● public void setMaxBusyTime(long maxBusyTime)

  设置池中线程最大繁忙时间。

  ● public void setSocketTO(int socketTO)

  设置套接字读取的超时时间。

  ● public void setSocketConnectTO(int socketConnectTO)

  设置套接字连接的超时时间。

  ● public void setMaxIdle(long maxIdle)

  设置可用池中线程的最长空闲时间。

  ● public void setMaintSleep(long maintSleep)

  设置池维护线程运行之间的睡眠时间。如果设置为0，则维护线程将不会启动。

  ● public void setFailover(boolean failover)

  设置池的故障转移标志。

  如果此标志设置为true，并且套接字无法连接，则池将尝试从另一个服务器返回套接字（如果存在）。如果设置为false，那么如果无法连接到请求的服务器，则获取套接字将返回null。

  ● public void setFailback(boolean failback)

​  设置池的故障回复标志。

  如果是true，池会尝试恢复存在问题的连接。如果是false，池不会做这样的尝试。

  ● public void setAliveCheck(boolean aliveCheck)

  设置池的心跳检查标志。

  如果为true，则将尝试在每次连接退出时与服务器对话，以确保连接仍然有效。这会增加额外的网络通信，因此默认为关闭。如果要确保在断开连接的情况下与服务器通信时不会出现任何问题，则可能会很有用。

  ● public void setNagle(boolean nagle)

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

  ● public void setHashingAlg(int alg)

  设置hash算法。

  0：SockIOPool.NATIVE_HASH，使用String.hashCode()获得hash code，该方法依赖JDK，可能和其他客户端不兼容，建议不使用。

  1：SockIOPool.OLD_COMPAT_HASH，使用original 兼容hash算法，兼容其他客户端。

  2：SockIOPool.NEW_COMPAT_HASH，使用CRC32兼容hash算法，兼容其他客户端，性能优于original算法。

  3：SockIOPool.CONSISTENT_HASH，使用MD5算法实现的一致性哈希。

  ● public void initialize()

  初始化连接池。

  ● public void shutDown()

  关闭连接池。

  清除并关闭所有连接。

  在Memcached 1.4+中，用户可以为每个Memcached项指定内存大小。

  可以在服务器端用参数"-I"来指定它。

  在客户端中，使用默认值1Mb设置最大Memcached项大小。

  在这种情况下，可以扩展任意大小，需要确保客户端有足够的内存，因为使用直接缓冲区来保存内存，它们在关闭之前是不会释放的。

  MemCachedClient

  ● public void setPrimitiveAsString(boolean primitiveAsString)

  允许将基础类型存储为其字符串格式。

  ● public void setDefaultEncoding(String defaultEncoding)

  设置允许将基础类型存储为其字符串格式时使用的编码。默认值为UTF-8。

  ● public void setSanitizeKeys(boolean sanitizeKeys)

  启用或禁用使用URLEncoding清理键值。

  ● public boolean keyExists(String key)

​  检查缓存中是否存在指定键。

  ● public boolean delete(String key)

  删除缓存中指定的键。

  ● public boolean set(String key, Object value)

  将指定的键值对存储到缓存中。

  ● public boolean set(String key, Object value, Integer hashCode)

  将指定的键值对存储到缓存中，并指定hashCode。

  ● public boolean set(String key, Object value, Date expiry)

  将指定的键值对存储到缓存中，并指定过期时间。

  ● public boolean set(String key, Object value, Date expiry, Integer hashCode)

  将指定的键值对存储到缓存中，并指定hashCode和过期时间。

  ● public boolean add(String key, Object value)

  将指定的键值对存储到缓存中。

  若指定的键存在，且未过期，则不会更新数据。其他情况都更新数据。

  ● public boolean add(String key, Object value, Date expiry)

  将指定的键值对存储到缓存中，并指定过期时间。

  若指定的键存在，且未过期，则不会更新数据。其他情况都更新数据。

  ● public boolean add(String key, Object value, Date expiry, Integer hashCode)

  将指定的键值对存储到缓存中，并指定hashCode和过期时间。

  若指定的键存在，且未过期，则不会更新数据。其他情况都更新数据。

  ● public boolean replace(String key, Object value)

  将指定的键的值替换掉。

  ● public boolean replace(String key, Object value, Integer hashCode)

  将指定的键的值替换掉，并指定hashCode。

  ● public boolean replace(String key, Object value, Date expiry)

  将指定的键的值替换掉，并设置过期时间。

  ● public boolean replace(String key, Object value, Date expiry, Integer hashCode)

  将指定的键的值替换掉，并设置hashCode和过期时间。

  ● public boolean storeCounter(String key, Long counter)

  根据指定键存储计数器。

  ● public boolean storeCounter(String key, Long counter, Date date)

  根据指定键存储计数器，并指定过期时间。

  ● public boolean storeCounter(String key, Long counter, Date date, Integer hashCode)

  根据指定键存储计数器，并指定hashCode和过期时间。

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

  根据指定键存储计数器，并指定hashCode。

  ● public long addOrIncr(String key)

  将指定的键和默认值0存储到缓存中，若键存在则自增。

  ● public long addOrIncr(String key, long inc)

  将指定的键和值存储到缓存中，若键存在则增加。

  ● public long addOrIncr(String key, long inc, Integer hashCode)

  将指定的键和值存储到缓存中，若键存在则增加，并指定hashCode。

  ● public long addOrDecr(String key)

  将指定的键和默认值0存储到缓存中，若键存在则自减。

  ● public long addOrDecr(String key, long inc)

  将指定的键和值存储到缓存中，若键存在则减少。

  ● public long addOrDecr(String key, long inc, Integer hashCode)

  将指定的键和值存储到缓存中，若键存在则减少，并指定hashCode。

  ● public long incr(String key)

  将指定键处的值递增1，然后返回它。

  如果使用set命令存储键/值对，确保setPrimitiveAsString=true。

  ● public long incr(String key, long inc)

  通过传入val在指定键处递增值。

  如果使用set命令存储键/值对，确保setPrimitiveAsString=true。

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

  通过传入val在指定键处递增值。

  如果使用set命令存储键/值对，确保setPrimitiveAsString=true，并指定hashCode。

  ● public long decr(String key)

  将指定键处的值递减1，然后返回它。

  如果使用set命令存储键/值对，确保setPrimitiveAsString=true。

  ● public long decr(String key, long inc)

  通过传入val在指定键处递减值。

  如果使用set命令存储键/值对，确保setPrimitiveAsString=true。

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

  通过传入val在指定键处递减值。

  如果使用set命令存储键/值对，确保setPrimitiveAsString=true，并指定hashCode。

  ● public Object get(String key)

  获取指定的键对应的值。

  ● public Object get(String key, Integer hashCode, boolean asString)

  获取指定的键对应的值，并指定hashCode。

  ● public MemcachedItem gets(String key)

  获取指定的key对应的值，值包含cas token。

  ● public MemcachedItem gets(String key, Integer hashCode)

  获取指定的key对应的值，值包含cas token，并指定hashCode。

  ● public Object[] getMultiArray(String[] keys)

  批量获取指定的键数组对应的值。

  ● public Object[] getMultiArray(String[] keys, Integer[] hashCodes)

  批量获取指定的键数组对应的值，并指定hashCode。

  ● public Object[] getMultiArray(String[] keys, Integer[] hashCodes, boolean asString)

  批量获取指定的键数组对应的值，并指定hashCode。

  ● public Map<String, Object> getMulti(String[] keys)

  批量获取指定的键数组对应的值。

  ● public Map<String, Object> getMulti(String[] keys, Integer[] hashCodes)

​  批量获取指定的键数组对应的值，并指定hashCode。

  ● public Map<String, Object> getMulti(String[] keys, Integer[] hashCodes, boolean asString)

  批量获取指定的键数组对应的值，并指定hashCode。

  ● public boolean flushAll()

  清理所有缓存服务器上的缓存内容。

  ● public boolean flushAll(String[] servers)

  清理指定缓存服务器上的缓存内容。

  ● public Map<String, Map<String, String>> stats()

  返回所有服务器的统计信息。

  ● public Map<String, Map<String, String>> stats(String[] servers)

  返回指定服务器的统计信息。

  ● public Map<String, Map<String, String>> statsItems()

  返回所有服务器的item的统计信息。

  ● public Map<String, Map<String, String>> statsItems(String[] servers)

  返回指定服务器的item的统计信息。

  ● public Map<String, Map<String, String>> statsSlabs()

  返回所有服务器的slab的统计信息。

  ● public Map<String, Map<String, String>> statsSlabs(String[] servers)

  返回指定服务器的slab的统计信息。

  ● public Map<String, Map<String, String>> statsCacheDump(int slabNumber, int limit)

  返回所有服务器的内存DUMP统计信息。

  ● public Map<String, Map<String, String>> statsCacheDump(String[] servers, int slabNumber, int limit)

  返回指定服务器的内存DUMP统计信息。

  ● public boolean append(String key, Object value)

  在指定的键对应的值后面追加值。

  ● public boolean append(String key, Object value, Integer hashCode)

  在指定的键对应的值后面追加值，并指定hashCode。

  ● public boolean cas(String key, Object value, long casUnique)

  以CAS的方式将指定的键值对存储到缓存中，指定需要比较的cas token。

  ● public boolean cas(String key, Object value, Integer hashCode, long casUnique)

  以CAS的方式将指定的键值对存储到缓存中，指定需要比较的cas token，并指定hashCode。

  ● public boolean cas(String key, Object value, Date expiry, long casUnique)

  以CAS的方式将指定的键值对存储到缓存中，指定需要比较的cas token，并指定过期时间。

  ● public boolean cas(String key, Object value, Date expiry, Integer hashCode, long casUnique)

​  以CAS的方式将指定的键值对存储到缓存中，指定需要比较的cas token，并指定hashCode和过期时间。

  ● public boolean prepend(String key, Object value)

  在指定的键对应的值前面追加值。

  ● public boolean prepend(String key, Object value, Integer hashCode)

  在指定的键对应的值前面追加值，并指定hashCode。

  总结

  Memcached-Java-Client的API，3.0.0版本较之前弃用了一些看起比较累赘的功能，如：setCompressEnable、setCompressThreshold等。文中罗列基本是Memcached主要API，与Memcached的命令相对应，并提供了分片机制，可以通过客户端完成Memcached的集群。

  若文中存在错误和不足，欢迎指正！