Class MemCachedClient

java.lang.Object
com.danga.MemCached.MemCachedClient

public class MemCachedClient extends Object
This is a Java client for the memcached server available from http://www.danga.com/memcached/.
Supports setting, adding, replacing, deleting compressed/uncompressed and
serialized (can be stored as string if object is native class) objects to memcached.

Now pulls SockIO objects from SockIOPool, which is a connection pool. The server failover
has also been moved into the SockIOPool class.
This pool needs to be initialized prior to the client working. See javadocs from SockIOPool.

Some examples of use follow.

To create cache client object and set params:

 
        MemCachedClient mc = new MemCachedClient();

        // compression is enabled by default    
        mc.setCompressEnable(true);

        // set compression threshhold to 4 KB (default: 15 KB)  
        mc.setCompressThreshold(4096);

        // turn on storing primitive types as a string representation
        // Should not do this in most cases.    
        mc.setPrimitiveAsString(true);
 

To store an object:

        MemCachedClient mc = new MemCachedClient();
        String key   = "cacheKey1";     
        Object value = SomeClass.getObject();   
        mc.set(key, value);
 

To store an object using a custom server hashCode:

        MemCachedClient mc = new MemCachedClient();
        String key   = "cacheKey1";     
        Object value = SomeClass.getObject();   
        Integer hash = new Integer(45); 
        mc.set(key, value, hash);
 
The set method shown above will always set the object in the cache.
The add and replace methods do the same, but with a slight difference.
  • add -- will store the object only if the server does not have an entry for this key
  • replace -- will store the object only if the server already has an entry for this key

To delete a cache entry:

        MemCachedClient mc = new MemCachedClient();
        String key   = "cacheKey1";     
        mc.delete(key);
 

To delete a cache entry using a custom hash code:

        MemCachedClient mc = new MemCachedClient();
        String key   = "cacheKey1";     
        Integer hash = new Integer(45); 
        mc.delete(key, hashCode);
 

To store a counter and then increment or decrement that counter:

        MemCachedClient mc = new MemCachedClient();
        String key   = "counterKey";    
        mc.storeCounter(key, new Integer(100));
        System.out.println("counter after adding      1: " mc.incr(key));       
        System.out.println("counter after adding      5: " mc.incr(key, 5));    
        System.out.println("counter after subtracting 4: " mc.decr(key, 4));    
        System.out.println("counter after subtracting 1: " mc.decr(key));       
 

To store a counter and then increment or decrement that counter with custom hash:

        MemCachedClient mc = new MemCachedClient();
        String key   = "counterKey";    
        Integer hash = new Integer(45); 
        mc.storeCounter(key, new Integer(100), hash);
        System.out.println("counter after adding      1: " mc.incr(key, 1, hash));      
        System.out.println("counter after adding      5: " mc.incr(key, 5, hash));      
        System.out.println("counter after subtracting 4: " mc.decr(key, 4, hash));      
        System.out.println("counter after subtracting 1: " mc.decr(key, 1, hash));      
 

To retrieve an object from the cache:

        MemCachedClient mc = new MemCachedClient();
        String key   = "key";   
        Object value = mc.get(key);     
 

To retrieve an object from the cache with custom hash:

        MemCachedClient mc = new MemCachedClient();
        String key   = "key";   
        Integer hash = new Integer(45); 
        Object value = mc.get(key, hash);       
 

To retrieve an multiple objects from the cache

        MemCachedClient mc = new MemCachedClient();
        String[] keys      = { "key", "key1", "key2" };
        Map<Object> values = mc.getMulti(keys);
 

To retrieve an multiple objects from the cache with custom hashing

        MemCachedClient mc = new MemCachedClient();
        String[] keys      = { "key", "key1", "key2" };
        Integer[] hashes   = { new Integer(45), new Integer(32), new Integer(44) };
        Map<Object> values = mc.getMulti(keys, hashes);
 

To flush all items in server(s)

        MemCachedClient mc = new MemCachedClient();
        mc.flushAll();
 

To get stats from server(s)

        MemCachedClient mc = new MemCachedClient();
        Map stats = mc.stats();
 
Version:
1.5
Author:
greg whalin <greg@meetup.com>, Richard 'toast' Russo <russor@msoe.edu>, Kevin Burton <burton@peerfear.org>, Robert Watts <robert@wattsit.co.uk>, Vin Chawla <vin@tivo.com>
  • Field Details

  • Constructor Details

    • MemCachedClient

      public MemCachedClient()
      Creates a new instance of MemCachedClient.
    • MemCachedClient

      public MemCachedClient(String poolName)
      Creates a new instance of MemCachedClient accepting a passed in pool name.
      Parameters:
      poolName - name of SockIOPool
    • MemCachedClient

      public MemCachedClient(ClassLoader classLoader)
      Creates a new instance of MemCacheClient but acceptes a passed in ClassLoader.
      Parameters:
      classLoader - ClassLoader object.
    • MemCachedClient

      public MemCachedClient(ClassLoader classLoader, ErrorHandler errorHandler)
      Creates a new instance of MemCacheClient but acceptes a passed in ClassLoader and a passed in ErrorHandler.
      Parameters:
      classLoader - ClassLoader object.
      errorHandler - ErrorHandler object.
    • MemCachedClient

      public MemCachedClient(ClassLoader classLoader, ErrorHandler errorHandler, String poolName)
      Creates a new instance of MemCacheClient but acceptes a passed in ClassLoader, ErrorHandler, and SockIOPool name.
      Parameters:
      classLoader - ClassLoader object.
      errorHandler - ErrorHandler object.
      poolName - SockIOPool name
  • Method Details

    • init

      private void init()
      Initializes client object to defaults. This enables compression and sets compression threshhold to 15 KB.
    • setClassLoader

      public void setClassLoader(ClassLoader classLoader)
      Sets an optional ClassLoader to be used for serialization.
      Parameters:
      classLoader -
    • setErrorHandler

      public void setErrorHandler(ErrorHandler errorHandler)
      Sets an optional ErrorHandler.
      Parameters:
      errorHandler -
    • setSanitizeKeys

      public void setSanitizeKeys(boolean sanitizeKeys)
      Enables/disables sanitizing keys by URLEncoding.
      Parameters:
      sanitizeKeys - if true, then URLEncode all keys
    • setPrimitiveAsString

      public void setPrimitiveAsString(boolean primitiveAsString)
      Enables storing primitive types as their String values.
      Parameters:
      primitiveAsString - if true, then store all primitives as their string value.
    • setDefaultEncoding

      public void setDefaultEncoding(String defaultEncoding)
      Sets default String encoding when storing primitives as Strings. Default is UTF-8.
      Parameters:
      defaultEncoding -
    • setCompressEnable

      public void setCompressEnable(boolean compressEnable)
      Enable storing compressed data, provided it meets the threshold requirements. If enabled, data will be stored in compressed form if it is
      longer than the threshold length set with setCompressThreshold(int)

      The default is that compression is enabled.

      Even if compression is disabled, compressed data will be automatically
      decompressed.
      Parameters:
      compressEnable - true to enable compression, false to disable compression
    • setCompressThreshold

      public void setCompressThreshold(long compressThreshold)
      Sets the required length for data to be considered for compression. If the length of the data to be stored is not equal or larger than this value, it will not be compressed. This defaults to 15 KB.
      Parameters:
      compressThreshold - required length of data to consider compression
    • keyExists

      public boolean keyExists(String key)
      Checks to see if key exists in cache.
      Parameters:
      key - the key to look for
      Returns:
      true if key found in cache, false if not (or if cache is down)
    • delete

      public boolean delete(String key)
      Deletes an object from cache given cache key.
      Parameters:
      key - the key to be removed
      Returns:
      true, if the data was deleted successfully
    • delete

      public boolean delete(String key, Date expiry)
      Deletes an object from cache given cache key and expiration date.
      Parameters:
      key - the key to be removed
      expiry - when to expire the record.
      Returns:
      true, if the data was deleted successfully
    • delete

      public boolean delete(String key, Integer hashCode, Date expiry)
      Deletes an object from cache given cache key, a delete time, and an optional hashcode. The item is immediately made non retrievable.
      Keep in mind add and replace
      will fail when used with the same key will fail, until the server reaches the
      specified time. However, set will succeed,
      and the new value will not be deleted.
      Parameters:
      key - the key to be removed
      hashCode - if not null, then the int hashcode to use
      expiry - when to expire the record.
      Returns:
      true, if the data was deleted successfully
    • set

      public boolean set(String key, Object value)
      Stores data on the server; only the key and the value are specified.
      Parameters:
      key - key to store data under
      value - value to store
      Returns:
      true, if the data was successfully stored
    • set

      public boolean set(String key, Object value, Integer hashCode)
      Stores data on the server; only the key and the value are specified.
      Parameters:
      key - key to store data under
      value - value to store
      hashCode - if not null, then the int hashcode to use
      Returns:
      true, if the data was successfully stored
    • set

      public boolean set(String key, Object value, Date expiry)
      Stores data on the server; the key, value, and an expiration time are specified.
      Parameters:
      key - key to store data under
      value - value to store
      expiry - when to expire the record
      Returns:
      true, if the data was successfully stored
    • set

      public boolean set(String key, Object value, Date expiry, Integer hashCode)
      Stores data on the server; the key, value, and an expiration time are specified.
      Parameters:
      key - key to store data under
      value - value to store
      expiry - when to expire the record
      hashCode - if not null, then the int hashcode to use
      Returns:
      true, if the data was successfully stored
    • add

      public boolean add(String key, Object value)
      Adds data to the server; only the key and the value are specified.
      Parameters:
      key - key to store data under
      value - value to store
      Returns:
      true, if the data was successfully stored
    • add

      public boolean add(String key, Object value, Integer hashCode)
      Adds data to the server; the key, value, and an optional hashcode are passed in.
      Parameters:
      key - key to store data under
      value - value to store
      hashCode - if not null, then the int hashcode to use
      Returns:
      true, if the data was successfully stored
    • add

      public boolean add(String key, Object value, Date expiry)
      Adds data to the server; the key, value, and an expiration time are specified.
      Parameters:
      key - key to store data under
      value - value to store
      expiry - when to expire the record
      Returns:
      true, if the data was successfully stored
    • add

      public boolean add(String key, Object value, Date expiry, Integer hashCode)
      Adds data to the server; the key, value, and an expiration time are specified.
      Parameters:
      key - key to store data under
      value - value to store
      expiry - when to expire the record
      hashCode - if not null, then the int hashcode to use
      Returns:
      true, if the data was successfully stored
    • replace

      public boolean replace(String key, Object value)
      Updates data on the server; only the key and the value are specified.
      Parameters:
      key - key to store data under
      value - value to store
      Returns:
      true, if the data was successfully stored
    • replace

      public boolean replace(String key, Object value, Integer hashCode)
      Updates data on the server; only the key and the value and an optional hash are specified.
      Parameters:
      key - key to store data under
      value - value to store
      hashCode - if not null, then the int hashcode to use
      Returns:
      true, if the data was successfully stored
    • replace

      public boolean replace(String key, Object value, Date expiry)
      Updates data on the server; the key, value, and an expiration time are specified.
      Parameters:
      key - key to store data under
      value - value to store
      expiry - when to expire the record
      Returns:
      true, if the data was successfully stored
    • replace

      public boolean replace(String key, Object value, Date expiry, Integer hashCode)
      Updates data on the server; the key, value, and an expiration time are specified.
      Parameters:
      key - key to store data under
      value - value to store
      expiry - when to expire the record
      hashCode - if not null, then the int hashcode to use
      Returns:
      true, if the data was successfully stored
    • set

      private boolean set(String cmdname, String key, Object value, Date expiry, Integer hashCode, boolean asString)
      Stores data to cache. If data does not already exist for this key on the server, or if the key is being
      deleted, the specified value will not be stored.
      The server will automatically delete the value when the expiration time has been reached.

      If compression is enabled, and the data is longer than the compression threshold
      the data will be stored in compressed form.

      As of the current release, all objects stored will use java serialization.
      Parameters:
      cmdname - action to take (set, add, replace)
      key - key to store cache under
      value - object to cache
      expiry - expiration
      hashCode - if not null, then the int hashcode to use
      asString - store this object as a string?
      Returns:
      true/false indicating success
    • storeCounter

      public boolean storeCounter(String key, long counter)
      Store a counter to memcached given a key
      Parameters:
      key - cache key
      counter - number to store
      Returns:
      true/false indicating success
    • storeCounter

      public boolean storeCounter(String key, Long counter)
      Store a counter to memcached given a key
      Parameters:
      key - cache key
      counter - number to store
      Returns:
      true/false indicating success
    • storeCounter

      public boolean storeCounter(String key, Long counter, Integer hashCode)
      Store a counter to memcached given a key
      Parameters:
      key - cache key
      counter - number to store
      hashCode - if not null, then the int hashcode to use
      Returns:
      true/false indicating success
    • getCounter

      public long getCounter(String key)
      Returns value in counter at given key as long.
      Parameters:
      key - cache ket
      Returns:
      counter value or -1 if not found
    • getCounter

      public long getCounter(String key, Integer hashCode)
      Returns value in counter at given key as long.
      Parameters:
      key - cache ket
      hashCode - if not null, then the int hashcode to use
      Returns:
      counter value or -1 if not found
    • addOrIncr

      public long addOrIncr(String key)
      Thread safe way to initialize and increment a counter.
      Parameters:
      key - key where the data is stored
      Returns:
      value of incrementer
    • addOrIncr

      public long addOrIncr(String key, long inc)
      Thread safe way to initialize and increment a counter.
      Parameters:
      key - key where the data is stored
      inc - value to set or increment by
      Returns:
      value of incrementer
    • addOrIncr

      public long addOrIncr(String key, long inc, Integer hashCode)
      Thread safe way to initialize and increment a counter.
      Parameters:
      key - key where the data is stored
      inc - value to set or increment by
      hashCode - if not null, then the int hashcode to use
      Returns:
      value of incrementer
    • addOrDecr

      public long addOrDecr(String key)
      Thread safe way to initialize and decrement a counter.
      Parameters:
      key - key where the data is stored
      Returns:
      value of incrementer
    • addOrDecr

      public long addOrDecr(String key, long inc)
      Thread safe way to initialize and decrement a counter.
      Parameters:
      key - key where the data is stored
      inc - value to set or increment by
      Returns:
      value of incrementer
    • addOrDecr

      public long addOrDecr(String key, long inc, Integer hashCode)
      Thread safe way to initialize and decrement a counter.
      Parameters:
      key - key where the data is stored
      inc - value to set or increment by
      hashCode - if not null, then the int hashcode to use
      Returns:
      value of incrementer
    • incr

      public long incr(String key)
      Increment the value at the specified key by 1, and then return it.
      Parameters:
      key - key where the data is stored
      Returns:
      -1, if the key is not found, the value after incrementing otherwise
    • incr

      public long incr(String key, long inc)
      Increment the value at the specified key by passed in val.
      Parameters:
      key - key where the data is stored
      inc - how much to increment by
      Returns:
      -1, if the key is not found, the value after incrementing otherwise
    • incr

      public long incr(String key, long inc, Integer hashCode)
      Increment the value at the specified key by the specified increment, and then return it.
      Parameters:
      key - key where the data is stored
      inc - how much to increment by
      hashCode - if not null, then the int hashcode to use
      Returns:
      -1, if the key is not found, the value after incrementing otherwise
    • decr

      public long decr(String key)
      Decrement the value at the specified key by 1, and then return it.
      Parameters:
      key - key where the data is stored
      Returns:
      -1, if the key is not found, the value after incrementing otherwise
    • decr

      public long decr(String key, long inc)
      Decrement the value at the specified key by passed in value, and then return it.
      Parameters:
      key - key where the data is stored
      inc - how much to increment by
      Returns:
      -1, if the key is not found, the value after incrementing otherwise
    • decr

      public long decr(String key, long inc, Integer hashCode)
      Decrement the value at the specified key by the specified increment, and then return it.
      Parameters:
      key - key where the data is stored
      inc - how much to increment by
      hashCode - if not null, then the int hashcode to use
      Returns:
      -1, if the key is not found, the value after incrementing otherwise
    • incrdecr

      private long incrdecr(String cmdname, String key, long inc, Integer hashCode)
      Increments/decrements the value at the specified key by inc. Note that the server uses a 32-bit unsigned integer, and checks for
      underflow. In the event of underflow, the result will be zero. Because
      Java lacks unsigned types, the value is returned as a 64-bit integer.
      The server will only decrement a value if it already exists;
      if a value is not found, -1 will be returned.
      Parameters:
      cmdname - increment/decrement
      key - cache key
      inc - amount to incr or decr
      hashCode - if not null, then the int hashcode to use
      Returns:
      new value or -1 if not exist
    • get

      public Object get(String key)
      Retrieve a key from the server, using a specific hash. If the data was compressed or serialized when compressed, it will automatically
      be decompressed or serialized, as appropriate. (Inclusive or)

      Non-serialized data will be returned as a string, so explicit conversion to
      numeric types will be necessary, if desired
      Parameters:
      key - key where data is stored
      Returns:
      the object that was previously stored, or null if it was not previously stored
    • get

      public Object get(String key, Integer hashCode)
      Retrieve a key from the server, using a specific hash. If the data was compressed or serialized when compressed, it will automatically
      be decompressed or serialized, as appropriate. (Inclusive or)

      Non-serialized data will be returned as a string, so explicit conversion to
      numeric types will be necessary, if desired
      Parameters:
      key - key where data is stored
      hashCode - if not null, then the int hashcode to use
      Returns:
      the object that was previously stored, or null if it was not previously stored
    • get

      public Object get(String key, Integer hashCode, boolean asString)
      Retrieve a key from the server, using a specific hash. If the data was compressed or serialized when compressed, it will automatically
      be decompressed or serialized, as appropriate. (Inclusive or)

      Non-serialized data will be returned as a string, so explicit conversion to
      numeric types will be necessary, if desired
      Parameters:
      key - key where data is stored
      hashCode - if not null, then the int hashcode to use
      asString - if true, then return string val
      Returns:
      the object that was previously stored, or null if it was not previously stored
    • getMultiArray

      public Object[] getMultiArray(String[] keys)
      Retrieve multiple objects from the memcache. This is recommended over repeated calls to get(), since it
      is more efficient.
      Parameters:
      keys - String array of keys to retrieve
      Returns:
      Object array ordered in same order as key array containing results
    • getMultiArray

      public Object[] getMultiArray(String[] keys, Integer[] hashCodes)
      Retrieve multiple objects from the memcache. This is recommended over repeated calls to get(), since it
      is more efficient.
      Parameters:
      keys - String array of keys to retrieve
      hashCodes - if not null, then the Integer array of hashCodes
      Returns:
      Object array ordered in same order as key array containing results
    • getMultiArray

      public Object[] getMultiArray(String[] keys, Integer[] hashCodes, boolean asString)
      Retrieve multiple objects from the memcache. This is recommended over repeated calls to get(), since it
      is more efficient.
      Parameters:
      keys - String array of keys to retrieve
      hashCodes - if not null, then the Integer array of hashCodes
      asString - if true, retrieve string vals
      Returns:
      Object array ordered in same order as key array containing results
    • getMulti

      public Map<String,Object> getMulti(String[] keys)
      Retrieve multiple objects from the memcache. This is recommended over repeated calls to get(), since it
      is more efficient.
      Parameters:
      keys - String array of keys to retrieve
      Returns:
      a hashmap with entries for each key is found by the server, keys that are not found are not entered into the hashmap, but attempting to retrieve them from the hashmap gives you null.
    • getMulti

      public Map<String,Object> getMulti(String[] keys, Integer[] hashCodes)
      Retrieve multiple keys from the memcache. This is recommended over repeated calls to get(), since it
      is more efficient.
      Parameters:
      keys - keys to retrieve
      hashCodes - if not null, then the Integer array of hashCodes
      Returns:
      a hashmap with entries for each key is found by the server, keys that are not found are not entered into the hashmap, but attempting to retrieve them from the hashmap gives you null.
    • getMulti

      public Map<String,Object> getMulti(String[] keys, Integer[] hashCodes, boolean asString)
      Retrieve multiple keys from the memcache. This is recommended over repeated calls to get(), since it
      is more efficient.
      Parameters:
      keys - keys to retrieve
      hashCodes - if not null, then the Integer array of hashCodes
      asString - if true then retrieve using String val
      Returns:
      a hashmap with entries for each key is found by the server, keys that are not found are not entered into the hashmap, but attempting to retrieve them from the hashmap gives you null.
    • loadMulti

      private void loadMulti(LineInputStream input, Map<String,Object> hm, boolean asString) throws IOException
      This method loads the data from cache into a Map. Pass a SockIO object which is ready to receive data and a HashMap
      to store the results.
      Parameters:
      sock - socket waiting to pass back data
      hm - hashmap to store data into
      asString - if true, and if we are using NativehHandler, return string val
      Throws:
      IOException - if io exception happens while reading from socket
    • sanitizeKey

      private String sanitizeKey(String key) throws UnsupportedEncodingException
      Throws:
      UnsupportedEncodingException
    • flushAll

      public boolean flushAll()
      Invalidates the entire cache. Will return true only if succeeds in clearing all servers.
      Returns:
      success true/false
    • flushAll

      public boolean flushAll(String[] servers)
      Invalidates the entire cache. Will return true only if succeeds in clearing all servers. If pass in null, then will try to flush all servers.
      Parameters:
      servers - optional array of host(s) to flush (host:port)
      Returns:
      success true/false
    • stats

      public Map stats()
      Retrieves stats for all servers. Returns a map keyed on the servername. The value is another map which contains stats with stat name as key and value as value.
      Returns:
      Stats map
    • stats

      public Map stats(String[] servers)
      Retrieves stats for passed in servers (or all servers). Returns a map keyed on the servername. The value is another map which contains stats with stat name as key and value as value.
      Parameters:
      servers - string array of servers to retrieve stats from, or all if this is null
      Returns:
      Stats map
    • statsItems

      public Map statsItems()
      Retrieves stats items for all servers. Returns a map keyed on the servername. The value is another map which contains item stats with itemname:number:field as key and value as value.
      Returns:
      Stats map
    • statsItems

      public Map statsItems(String[] servers)
      Retrieves stats for passed in servers (or all servers). Returns a map keyed on the servername. The value is another map which contains item stats with itemname:number:field as key and value as value.
      Parameters:
      servers - string array of servers to retrieve stats from, or all if this is null
      Returns:
      Stats map
    • statsSlabs

      public Map statsSlabs()
      Retrieves stats items for all servers. Returns a map keyed on the servername. The value is another map which contains slabs stats with slabnumber:field as key and value as value.
      Returns:
      Stats map
    • statsSlabs

      public Map statsSlabs(String[] servers)
      Retrieves stats for passed in servers (or all servers). Returns a map keyed on the servername. The value is another map which contains slabs stats with slabnumber:field as key and value as value.
      Parameters:
      servers - string array of servers to retrieve stats from, or all if this is null
      Returns:
      Stats map
    • statsCacheDump

      public Map statsCacheDump(int slabNumber, int limit)
      Retrieves items cachedump for all servers. Returns a map keyed on the servername. The value is another map which contains cachedump stats with the cachekey as key and byte size and unix timestamp as value.
      Parameters:
      slabNumber - the item number of the cache dump
      Returns:
      Stats map
    • statsCacheDump

      public Map statsCacheDump(String[] servers, int slabNumber, int limit)
      Retrieves stats for passed in servers (or all servers). Returns a map keyed on the servername. The value is another map which contains cachedump stats with the cachekey as key and byte size and unix timestamp as value.
      Parameters:
      servers - string array of servers to retrieve stats from, or all if this is null
      slabNumber - the item number of the cache dump
      Returns:
      Stats map
    • stats

      private Map stats(String[] servers, String command, String lineStart)