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的集羣。

  若文中存在錯誤和不足，歡迎指正！