Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

net.spy.memcached
Class MemcachedClient

java.lang.Object
  extended by java.lang.Thread
      extended by net.spy.memcached.compat.SpyThread
          extended by net.spy.memcached.MemcachedClient
All Implemented Interfaces:
Runnable, ConnectionObserver, MemcachedClientIF, Reconfigurable
public class MemcachedClient
extends SpyThread
implements MemcachedClientIF, ConnectionObserver, Reconfigurable

Client to a memcached server.

Basic usage

        MemcachedClient c=new MemcachedClient(
                new InetSocketAddress("hostname", portNum));

        // Store a value (async) for one hour
        c.set("someKey", 3600, someObject);
        // Retrieve a value.
        Object myObject=c.get("someKey");

Advanced Usage

MemcachedClient may be processing a great deal of asynchronous messages or possibly dealing with an unreachable memcached, which may delay processing. If a memcached is disabled, for example, MemcachedConnection will continue to attempt to reconnect and replay pending operations until it comes back up. To prevent this from causing your application to hang, you can use one of the asynchronous mechanisms to time out a request and cancel the operation to the server. 

      // Get a memcached client connected to several servers
      // over the binary protocol
      MemcachedClient c = new MemcachedClient(new BinaryConnectionFactory(),
              AddrUtil.getAddresses("server1:11211 server2:11211"));

      // Try to get a value, for up to 5 seconds, and cancel if it
      // doesn't return
      Object myObj = null;
      Future<Object> f = c.asyncGet("someKey");
      try {
          myObj = f.get(5, TimeUnit.SECONDS);
      // throws expecting InterruptedException, ExecutionException
      // or TimeoutException
      } catch (Exception e) {  /*  /
          // Since we don't need this, go ahead and cancel the operation.
          // This is not strictly necessary, but it'll save some work on
          // the server.  It is okay to cancel it if running.
          f.cancel(true);
          // Do other timeout related stuff
      }

Nested Class Summary
 
Nested classes/interfaces inherited from class java.lang.Thread
Thread.State, Thread.UncaughtExceptionHandler
 
Field Summary
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Fields inherited from interface net.spy.memcached.MemcachedClientIF
MAX_KEY_LENGTH
 
Constructor Summary
MemcachedClient(ConnectionFactory cf, List<InetSocketAddress> addrs)
          Get a memcache client over the specified memcached locations.
MemcachedClient(InetSocketAddress... ia)
          Get a memcache client operating on the specified memcached locations.
MemcachedClient(List<InetSocketAddress> addrs)
          Get a memcache client over the specified memcached locations.
MemcachedClient(List<URI> baseList, String bucketName, String pwd)
          Get a MemcachedClient based on the REST response from a Membase server.
MemcachedClient(List<URI> baseList, String bucketName, String usr, String pwd)
          Get a MemcachedClient based on the REST response from a Membase server where the username is different than the bucket name.
 
Method Summary
 Future<Boolean> add(String key, int exp, Object o)
          Add an object to the cache (using the default transcoder) iff it does not exist already.
<T> Future<Boolean>
add(String key, int exp, T o, Transcoder<T> tc)
          Add an object to the cache iff it does not exist already.
 boolean addObserver(ConnectionObserver obs)
          Add a connection observer.
 Future<Boolean> append(long cas, String key, Object val)
          Append to an existing value in the cache.
<T> Future<Boolean>
append(long cas, String key, T val, Transcoder<T> tc)
          Append to an existing value in the cache.
<T> Future<CASResponse>
asyncCAS(String key, long casId, int exp, T value, Transcoder<T> tc)
          Asynchronous CAS operation.
 Future<CASResponse> asyncCAS(String key, long casId, Object value)
          Asynchronous CAS operation using the default transcoder.
<T> Future<CASResponse>
asyncCAS(String key, long casId, T value, Transcoder<T> tc)
          Asynchronous CAS operation.
 Future<Long> asyncDecr(String key, int by)
          Asynchronous decrement.
 Future<Object> asyncGet(String key)
          Get the given key asynchronously and decode with the default transcoder.
<T> Future<T>
asyncGet(String key, Transcoder<T> tc)
          Get the given key asynchronously.
 Future<CASValue<Object>> asyncGetAndLock(String key, int exp)
          Get and lock the given key asynchronously and decode with the default transcoder.
<T> Future<CASValue<T>>
asyncGetAndLock(String key, int exp, Transcoder<T> tc)
          Gets and locks the given key asynchronously.
 Future<CASValue<Object>> asyncGetAndTouch(String key, int exp)
          Get the given key to reset its expiration time.
<T> Future<CASValue<T>>
asyncGetAndTouch(String key, int exp, Transcoder<T> tc)
          Get the given key to reset its expiration time.
 BulkFuture<Map<String,Object>> asyncGetBulk(Collection<String> keys)
          Asynchronously get a bunch of objects from the cache and decode them with the given transcoder.
<T> BulkFuture<Map<String,T>>
asyncGetBulk(Collection<String> keys, Iterator<Transcoder<T>> tc_iter)
          Asynchronously get a bunch of objects from the cache.
<T> BulkFuture<Map<String,T>>
asyncGetBulk(Collection<String> keys, Transcoder<T> tc)
          Asynchronously get a bunch of objects from the cache.
 BulkFuture<Map<String,Object>> asyncGetBulk(String... keys)
          Varargs wrapper for asynchronous bulk gets with the default transcoder.
<T> BulkFuture<Map<String,T>>
asyncGetBulk(Transcoder<T> tc, String... keys)
          Varargs wrapper for asynchronous bulk gets.
 Future<CASValue<Object>> asyncGets(String key)
          Gets (with CAS support) the given key asynchronously and decode using the default transcoder.
<T> Future<CASValue<T>>
asyncGets(String key, Transcoder<T> tc)
          Gets (with CAS support) the given key asynchronously.
 Future<Long> asyncIncr(String key, int by)
          Asychronous increment.
<T> CASResponse
cas(String key, long casId, int exp, T value, Transcoder<T> tc)
          Perform a synchronous CAS operation.
 CASResponse cas(String key, long casId, Object value)
          Perform a synchronous CAS operation with the default transcoder.
<T> CASResponse
cas(String key, long casId, T value, Transcoder<T> tc)
          Perform a synchronous CAS operation.
 void connectionEstablished(SocketAddress sa, int reconnectCount)
          A connection has just successfully been established on the given socket.
 void connectionLost(SocketAddress sa)
          A connection was just lost on the given socket.
 long decr(String key, int by)
          Decrement the given key by the given value.
 long decr(String key, int by, long def)
          Decrement the given counter, returning the new value.
 long decr(String key, int by, long def, int exp)
          Decrement the given counter, returning the new value.
 Future<Boolean> delete(String key)
          Delete the given key from the cache.
 Future<Boolean> delete(String key, int hold)
          Deprecated. Hold values are no longer honored.
 Future<Boolean> flush()
          Flush all caches from all servers immediately.
 Future<Boolean> flush(int delay)
          Flush all caches from all servers with a delay of application.
 Object get(String key)
          Get with a single key and decode using the default transcoder.
<T> T
get(String key, Transcoder<T> tc)
          Get with a single key.
 CASValue<Object> getAndLock(String key, int exp)
          Get and lock with a single key and decode using the default transcoder.
<T> CASValue<T>
getAndLock(String key, int exp, Transcoder<T> tc)
          Getl with a single key.
 CASValue<Object> getAndTouch(String key, int exp)
          Get a single key and reset its expiration using the default transcoder.
<T> CASValue<T>
getAndTouch(String key, int exp, Transcoder<T> tc)
          Get with a single key and reset its expiration.
 Collection<SocketAddress> getAvailableServers()
          Get the addresses of available servers.
 Map<String,Object> getBulk(Collection<String> keys)
          Get the values for multiple keys from the cache.
<T> Map<String,T>
getBulk(Collection<String> keys, Transcoder<T> tc)
          Get the values for multiple keys from the cache.
 Map<String,Object> getBulk(String... keys)
          Get the values for multiple keys from the cache.
<T> Map<String,T>
getBulk(Transcoder<T> tc, String... keys)
          Get the values for multiple keys from the cache.
 NodeLocator getNodeLocator()
          Get a read-only wrapper around the node locator wrapping this instance.
 CASValue<Object> gets(String key)
          Gets (with CAS support) with a single key using the default transcoder.
<T> CASValue<T>
gets(String key, Transcoder<T> tc)
          Gets (with CAS support) with a single key.
 Map<SocketAddress,Map<String,String>> getStats()
          Get all of the stats from all of the connections.
 Map<SocketAddress,Map<String,String>> getStats(String arg)
          Get a set of stats from all connections.
 Transcoder<Object> getTranscoder()
          Get the default transcoder that's in use.
 Collection<SocketAddress> getUnavailableServers()
          Get the addresses of unavailable servers.
 Map<SocketAddress,String> getVersions()
          Get the versions of all of the connected memcacheds.
 long incr(String key, int by)
          Increment the given key by the given amount.
 long incr(String key, int by, long def)
          Increment the given counter, returning the new value.
 long incr(String key, int by, long def, int exp)
          Increment the given counter, returning the new value.
 Set<String> listSaslMechanisms()
          Get the set of SASL mechanisms supported by the servers.
 Future<Boolean> prepend(long cas, String key, Object val)
          Prepend to an existing value in the cache.
<T> Future<Boolean>
prepend(long cas, String key, T val, Transcoder<T> tc)
          Prepend to an existing value in the cache.
 void reconfigure(Bucket bucket)
          Call on a configuration update
 boolean removeObserver(ConnectionObserver obs)
          Remove a connection observer.
 Future<Boolean> replace(String key, int exp, Object o)
          Replace an object with the given value (transcoded with the default transcoder) iff there is already a value for the given key.
<T> Future<Boolean>
replace(String key, int exp, T o, Transcoder<T> tc)
          Replace an object with the given value iff there is already a value for the given key.
 void run()
          Infinitely loop processing IO.
 Future<Boolean> set(String key, int exp, Object o)
          Set an object in the cache (using the default transcoder) regardless of any existing value.
<T> Future<Boolean>
set(String key, int exp, T o, Transcoder<T> tc)
          Set an object in the cache regardless of any existing value.
 void shutdown()
          Shut down immediately.
 boolean shutdown(long timeout, TimeUnit unit)
          Shut down this client gracefully.
<T> Future<Boolean>
touch(String key, int exp)
          Touch the given key to reset its expiration time with the default transcoder.
<T> Future<Boolean>
touch(String key, int exp, Transcoder<T> tc)
          Touch the given key to reset its expiration time.
 boolean waitForQueues(long timeout, TimeUnit unit)
          Wait for the queues to die down.
 
Methods inherited from class net.spy.memcached.compat.SpyThread
getLogger
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

MemcachedClient

public MemcachedClient(InetSocketAddress... ia)
                throws IOException
Get a memcache client operating on the specified memcached locations.

Parameters:
ia - the memcached locations
Throws:
IOException - if connections cannot be established

MemcachedClient

public MemcachedClient(List<InetSocketAddress> addrs)
                throws IOException
Get a memcache client over the specified memcached locations.

Parameters:
addrs - the socket addrs
Throws:
IOException - if connections cannot be established

MemcachedClient

public MemcachedClient(ConnectionFactory cf,
                       List<InetSocketAddress> addrs)
                throws IOException
Get a memcache client over the specified memcached locations.

Parameters:
cf - the connection factory to configure connections for this client
addrs - the socket addresses
Throws:
IOException - if connections cannot be established

MemcachedClient

public MemcachedClient(List<URI> baseList,
                       String bucketName,
                       String usr,
                       String pwd)
                throws IOException,
                       ConfigurationException
Get a MemcachedClient based on the REST response from a Membase server where the username is different than the bucket name. To connect to the "default" special bucket for a given cluster, use an empty string as the password. If a password has not been assigned to the bucket, it is typically an empty string.

Parameters:
baseList - the URI list of one or more servers from the cluster
bucketName - the bucket name in the cluster you wish to use
usr - the username for the bucket; this nearly always be the same as the bucket name
pwd - the password for the bucket
Throws:
IOException - if connections could not be made
ConfigurationException - if the configuration provided by the server has issues or is not compatible

MemcachedClient

public MemcachedClient(List<URI> baseList,
                       String bucketName,
                       String pwd)
                throws IOException,
                       ConfigurationException
Get a MemcachedClient based on the REST response from a Membase server. This constructor is merely a convenience for situations where the bucket name is the same as the user name. This is commonly the case. To connect to the "default" special bucket for a given cluster, use an empty string as the password. If a password has not been assigned to the bucket, it is typically an empty string.

Parameters:
baseList - the URI list of one or more servers from the cluster
bucketName - the bucket name in the cluster you wish to use
pwd - the password for the bucket
Throws:
IOException - if connections could not be made
ConfigurationException - if the configuration provided by the server has issues or is not compatible
Method Detail

reconfigure

public void reconfigure(Bucket bucket)
Description copied from interface: Reconfigurable
Call on a configuration update

Specified by:
reconfigure in interface Reconfigurable
Parameters:
bucket - updated vbucket configuration

getAvailableServers

public Collection<SocketAddress> getAvailableServers()
Get the addresses of available servers.

This is based on a snapshot in time so shouldn't be considered completely accurate, but is a useful for getting a feel for what's working and what's not working.

Specified by:
getAvailableServers in interface MemcachedClientIF
Returns:
point-in-time view of currently available servers

getUnavailableServers

public Collection<SocketAddress> getUnavailableServers()
Get the addresses of unavailable servers.

This is based on a snapshot in time so shouldn't be considered completely accurate, but is a useful for getting a feel for what's working and what's not working.

Specified by:
getUnavailableServers in interface MemcachedClientIF
Returns:
point-in-time view of currently available servers

getNodeLocator

public NodeLocator getNodeLocator()
Get a read-only wrapper around the node locator wrapping this instance.

Specified by:
getNodeLocator in interface MemcachedClientIF
Returns:
this instance's NodeLocator

getTranscoder

public Transcoder<Object> getTranscoder()
Get the default transcoder that's in use.

Specified by:
getTranscoder in interface MemcachedClientIF
Returns:
this instance's Transcoder

touch

public <T> Future<Boolean> touch(String key,
                                 int exp)
Touch the given key to reset its expiration time with the default transcoder.

Parameters:
key - the key to fetch
exp - the new expiration to set for the given key
Returns:
a future that will hold the return value of whether or not the fetch succeeded
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

touch

public <T> Future<Boolean> touch(String key,
                                 int exp,
                                 Transcoder<T> tc)
Touch the given key to reset its expiration time.

Parameters:
key - the key to fetch
exp - the new expiration to set for the given key
tc - the transcoder to serialize and unserialize value
Returns:
a future that will hold the return value of whether or not the fetch succeeded
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

append

public Future<Boolean> append(long cas,
                              String key,
                              Object val)
Append to an existing value in the cache.

Note that the return will be false any time a mutation has not occurred.

Specified by:
append in interface MemcachedClientIF
Parameters:
cas - cas identifier (ignored in the ascii protocol)
key - the key to whose value will be appended
val - the value to append
Returns:
a future indicating success, false if there was no change to the value
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

append

public <T> Future<Boolean> append(long cas,
                                  String key,
                                  T val,
                                  Transcoder<T> tc)
Append to an existing value in the cache.

Note that the return will be false any time a mutation has not occurred.

Specified by:
append in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
cas - cas identifier (ignored in the ascii protocol)
key - the key to whose value will be appended
val - the value to append
tc - the transcoder to serialize and unserialize the value
Returns:
a future indicating success
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

prepend

public Future<Boolean> prepend(long cas,
                               String key,
                               Object val)
Prepend to an existing value in the cache.

Note that the return will be false any time a mutation has not occurred.

Specified by:
prepend in interface MemcachedClientIF
Parameters:
cas - cas identifier (ignored in the ascii protocol)
key - the key to whose value will be prepended
val - the value to append
Returns:
a future indicating success
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

prepend

public <T> Future<Boolean> prepend(long cas,
                                   String key,
                                   T val,
                                   Transcoder<T> tc)
Prepend to an existing value in the cache.

Note that the return will be false any time a mutation has not occurred.

Specified by:
prepend in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
cas - cas identifier (ignored in the ascii protocol)
key - the key to whose value will be prepended
val - the value to append
tc - the transcoder to serialize and unserialize the value
Returns:
a future indicating success
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncCAS

public <T> Future<CASResponse> asyncCAS(String key,
                                        long casId,
                                        T value,
                                        Transcoder<T> tc)
Asynchronous CAS operation.

Specified by:
asyncCAS in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
key - the key
casId - the CAS identifier (from a gets operation)
value - the new value
tc - the transcoder to serialize and unserialize the value
Returns:
a future that will indicate the status of the CAS
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncCAS

public <T> Future<CASResponse> asyncCAS(String key,
                                        long casId,
                                        int exp,
                                        T value,
                                        Transcoder<T> tc)
Asynchronous CAS operation.

Type Parameters:
T -
Parameters:
key - the key
casId - the CAS identifier (from a gets operation)
exp - the expiration of this object
value - the new value
tc - the transcoder to serialize and unserialize the value
Returns:
a future that will indicate the status of the CAS
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncCAS

public Future<CASResponse> asyncCAS(String key,
                                    long casId,
                                    Object value)
Asynchronous CAS operation using the default transcoder.

Specified by:
asyncCAS in interface MemcachedClientIF
Parameters:
key - the key
casId - the CAS identifier (from a gets operation)
value - the new value
Returns:
a future that will indicate the status of the CAS
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

cas

public <T> CASResponse cas(String key,
                           long casId,
                           T value,
                           Transcoder<T> tc)
Perform a synchronous CAS operation.

Specified by:
cas in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
key - the key
casId - the CAS identifier (from a gets operation)
value - the new value
tc - the transcoder to serialize and unserialize the value
Returns:
a CASResponse
Throws:
OperationTimeoutException - if global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

cas

public <T> CASResponse cas(String key,
                           long casId,
                           int exp,
                           T value,
                           Transcoder<T> tc)
Perform a synchronous CAS operation.

Type Parameters:
T -
Parameters:
key - the key
casId - the CAS identifier (from a gets operation)
exp - the expiration of this object
value - the new value
tc - the transcoder to serialize and unserialize the value
Returns:
a CASResponse
Throws:
OperationTimeoutException - if global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

cas

public CASResponse cas(String key,
                       long casId,
                       Object value)
Perform a synchronous CAS operation with the default transcoder.

Specified by:
cas in interface MemcachedClientIF
Parameters:
key - the key
casId - the CAS identifier (from a gets operation)
value - the new value
Returns:
a CASResponse
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

add

public <T> Future<Boolean> add(String key,
                               int exp,
                               T o,
                               Transcoder<T> tc)
Add an object to the cache iff it does not exist already.

The exp value is passed along to memcached exactly as given, and will be processed per the memcached protocol specification:

Note that the return will be false any time a mutation has not occurred.

The actual value sent may either be Unix time (number of seconds since January 1, 1970, as a 32-bit value), or a number of seconds starting from current time. In the latter case, this number of seconds may not exceed 60*60*24*30 (number of seconds in 30 days); if the number sent by a client is larger than that, the server will consider it to be real Unix time value rather than an offset from current time.

Specified by:
add in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
key - the key under which this object should be added.
exp - the expiration of this object
o - the object to store
tc - the transcoder to serialize and unserialize the value
Returns:
a future representing the processing of this operation
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

add

public Future<Boolean> add(String key,
                           int exp,
                           Object o)
Add an object to the cache (using the default transcoder) iff it does not exist already.

The exp value is passed along to memcached exactly as given, and will be processed per the memcached protocol specification:

Note that the return will be false any time a mutation has not occurred.

The actual value sent may either be Unix time (number of seconds since January 1, 1970, as a 32-bit value), or a number of seconds starting from current time. In the latter case, this number of seconds may not exceed 60*60*24*30 (number of seconds in 30 days); if the number sent by a client is larger than that, the server will consider it to be real Unix time value rather than an offset from current time.

Specified by:
add in interface MemcachedClientIF
Parameters:
key - the key under which this object should be added.
exp - the expiration of this object
o - the object to store
Returns:
a future representing the processing of this operation
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

set

public <T> Future<Boolean> set(String key,
                               int exp,
                               T o,
                               Transcoder<T> tc)
Set an object in the cache regardless of any existing value.

The exp value is passed along to memcached exactly as given, and will be processed per the memcached protocol specification:

Note that the return will be false any time a mutation has not occurred.

The actual value sent may either be Unix time (number of seconds since January 1, 1970, as a 32-bit value), or a number of seconds starting from current time. In the latter case, this number of seconds may not exceed 60*60*24*30 (number of seconds in 30 days); if the number sent by a client is larger than that, the server will consider it to be real Unix time value rather than an offset from current time.

Specified by:
set in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
key - the key under which this object should be added.
exp - the expiration of this object
o - the object to store
tc - the transcoder to serialize and unserialize the value
Returns:
a future representing the processing of this operation
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

set

public Future<Boolean> set(String key,
                           int exp,
                           Object o)
Set an object in the cache (using the default transcoder) regardless of any existing value.

The exp value is passed along to memcached exactly as given, and will be processed per the memcached protocol specification:

Note that the return will be false any time a mutation has not occurred.

The actual value sent may either be Unix time (number of seconds since January 1, 1970, as a 32-bit value), or a number of seconds starting from current time. In the latter case, this number of seconds may not exceed 60*60*24*30 (number of seconds in 30 days); if the number sent by a client is larger than that, the server will consider it to be real Unix time value rather than an offset from current time.

Specified by:
set in interface MemcachedClientIF
Parameters:
key - the key under which this object should be added.
exp - the expiration of this object
o - the object to store
Returns:
a future representing the processing of this operation
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

replace

public <T> Future<Boolean> replace(String key,
                                   int exp,
                                   T o,
                                   Transcoder<T> tc)
Replace an object with the given value iff there is already a value for the given key.

The exp value is passed along to memcached exactly as given, and will be processed per the memcached protocol specification:

Note that the return will be false any time a mutation has not occurred.

The actual value sent may either be Unix time (number of seconds since January 1, 1970, as a 32-bit value), or a number of seconds starting from current time. In the latter case, this number of seconds may not exceed 60*60*24*30 (number of seconds in 30 days); if the number sent by a client is larger than that, the server will consider it to be real Unix time value rather than an offset from current time.

Specified by:
replace in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
key - the key under which this object should be added.
exp - the expiration of this object
o - the object to store
tc - the transcoder to serialize and unserialize the value
Returns:
a future representing the processing of this operation
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

replace

public Future<Boolean> replace(String key,
                               int exp,
                               Object o)
Replace an object with the given value (transcoded with the default transcoder) iff there is already a value for the given key.

The exp value is passed along to memcached exactly as given, and will be processed per the memcached protocol specification:

Note that the return will be false any time a mutation has not occurred.

The actual value sent may either be Unix time (number of seconds since January 1, 1970, as a 32-bit value), or a number of seconds starting from current time. In the latter case, this number of seconds may not exceed 60*60*24*30 (number of seconds in 30 days); if the number sent by a client is larger than that, the server will consider it to be real Unix time value rather than an offset from current time.

Specified by:
replace in interface MemcachedClientIF
Parameters:
key - the key under which this object should be added.
exp - the expiration of this object
o - the object to store
Returns:
a future representing the processing of this operation
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncGet

public <T> Future<T> asyncGet(String key,
                              Transcoder<T> tc)
Get the given key asynchronously.

Specified by:
asyncGet in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
key - the key to fetch
tc - the transcoder to serialize and unserialize value
Returns:
a future that will hold the return value of the fetch
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncGet

public Future<Object> asyncGet(String key)
Get the given key asynchronously and decode with the default transcoder.

Specified by:
asyncGet in interface MemcachedClientIF
Parameters:
key - the key to fetch
Returns:
a future that will hold the return value of the fetch
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncGets

public <T> Future<CASValue<T>> asyncGets(String key,
                                         Transcoder<T> tc)
Gets (with CAS support) the given key asynchronously.

Specified by:
asyncGets in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
key - the key to fetch
tc - the transcoder to serialize and unserialize value
Returns:
a future that will hold the return value of the fetch
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncGets

public Future<CASValue<Object>> asyncGets(String key)
Gets (with CAS support) the given key asynchronously and decode using the default transcoder.

Specified by:
asyncGets in interface MemcachedClientIF
Parameters:
key - the key to fetch
Returns:
a future that will hold the return value of the fetch
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

gets

public <T> CASValue<T> gets(String key,
                            Transcoder<T> tc)
Gets (with CAS support) with a single key.

Specified by:
gets in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
key - the key to get
tc - the transcoder to serialize and unserialize value
Returns:
the result from the cache and CAS id (null if there is none)
Throws:
OperationTimeoutException - if global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

getAndTouch

public <T> CASValue<T> getAndTouch(String key,
                                   int exp,
                                   Transcoder<T> tc)
Get with a single key and reset its expiration.

Type Parameters:
T -
Parameters:
key - the key to get
exp - the new expiration for the key
tc - the transcoder to serialize and unserialize value
Returns:
the result from the cache (null if there is none)
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

getAndTouch

public CASValue<Object> getAndTouch(String key,
                                    int exp)
Get a single key and reset its expiration using the default transcoder.

Parameters:
key - the key to get
exp - the new expiration for the key
Returns:
the result from the cache and CAS id (null if there is none)
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

gets

public CASValue<Object> gets(String key)
Gets (with CAS support) with a single key using the default transcoder.

Specified by:
gets in interface MemcachedClientIF
Parameters:
key - the key to get
Returns:
the result from the cache and CAS id (null if there is none)
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

get

public <T> T get(String key,
                 Transcoder<T> tc)
Get with a single key.

Specified by:
get in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
key - the key to get
tc - the transcoder to serialize and unserialize value
Returns:
the result from the cache (null if there is none)
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

get

public Object get(String key)
Get with a single key and decode using the default transcoder.

Specified by:
get in interface MemcachedClientIF
Parameters:
key - the key to get
Returns:
the result from the cache (null if there is none)
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncGetAndLock

public <T> Future<CASValue<T>> asyncGetAndLock(String key,
                                               int exp,
                                               Transcoder<T> tc)
Gets and locks the given key asynchronously. By default the maximum allowed timeout is 30 seconds. Timeouts greater than this will be set to 30 seconds.

Parameters:
key - the key to fetch and lock
exp - the amount of time the lock should be valid for in seconds.
tc - the transcoder to serialize and unserialize value
Returns:
a future that will hold the return value of the fetch
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncGetAndLock

public Future<CASValue<Object>> asyncGetAndLock(String key,
                                                int exp)
Get and lock the given key asynchronously and decode with the default transcoder. By default the maximum allowed timeout is 30 seconds. Timeouts greater than this will be set to 30 seconds.

Parameters:
key - the key to fetch and lock
exp - the amount of time the lock should be valid for in seconds.
Returns:
a future that will hold the return value of the fetch
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncGetBulk

public <T> BulkFuture<Map<String,T>> asyncGetBulk(Collection<String> keys,
                                                  Iterator<Transcoder<T>> tc_iter)
Asynchronously get a bunch of objects from the cache.

Specified by:
asyncGetBulk in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
keys - the keys to request
tc_iter - an iterator of transcoders to serialize and unserialize values; the transcoders are matched with the keys in the same order. The minimum of the key collection length and number of transcoders is used and no exception is thrown if they do not match
Returns:
a Future result of that fetch
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncGetBulk

public <T> BulkFuture<Map<String,T>> asyncGetBulk(Collection<String> keys,
                                                  Transcoder<T> tc)
Asynchronously get a bunch of objects from the cache.

Specified by:
asyncGetBulk in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
keys - the keys to request
tc - the transcoder to serialize and unserialize values
Returns:
a Future result of that fetch
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncGetBulk

public BulkFuture<Map<String,Object>> asyncGetBulk(Collection<String> keys)
Asynchronously get a bunch of objects from the cache and decode them with the given transcoder.

Specified by:
asyncGetBulk in interface MemcachedClientIF
Parameters:
keys - the keys to request
Returns:
a Future result of that fetch
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncGetBulk

public <T> BulkFuture<Map<String,T>> asyncGetBulk(Transcoder<T> tc,
                                                  String... keys)
Varargs wrapper for asynchronous bulk gets.

Specified by:
asyncGetBulk in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
tc - the transcoder to serialize and unserialize value
keys - one more more keys to get
Returns:
the future values of those keys
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncGetBulk

public BulkFuture<Map<String,Object>> asyncGetBulk(String... keys)
Varargs wrapper for asynchronous bulk gets with the default transcoder.

Specified by:
asyncGetBulk in interface MemcachedClientIF
Parameters:
keys - one more more keys to get
Returns:
the future values of those keys
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncGetAndTouch

public Future<CASValue<Object>> asyncGetAndTouch(String key,
                                                 int exp)
Get the given key to reset its expiration time.

Parameters:
key - the key to fetch
exp - the new expiration to set for the given key
Returns:
a future that will hold the return value of the fetch
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncGetAndTouch

public <T> Future<CASValue<T>> asyncGetAndTouch(String key,
                                                int exp,
                                                Transcoder<T> tc)
Get the given key to reset its expiration time.

Parameters:
key - the key to fetch
exp - the new expiration to set for the given key
tc - the transcoder to serialize and unserialize value
Returns:
a future that will hold the return value of the fetch
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

getBulk

public <T> Map<String,T> getBulk(Collection<String> keys,
                                 Transcoder<T> tc)
Get the values for multiple keys from the cache.

Specified by:
getBulk in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
keys - the keys
tc - the transcoder to serialize and unserialize value
Returns:
a map of the values (for each value that exists)
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

getBulk

public Map<String,Object> getBulk(Collection<String> keys)
Get the values for multiple keys from the cache.

Specified by:
getBulk in interface MemcachedClientIF
Parameters:
keys - the keys
Returns:
a map of the values (for each value that exists)
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

getBulk

public <T> Map<String,T> getBulk(Transcoder<T> tc,
                                 String... keys)
Get the values for multiple keys from the cache.

Specified by:
getBulk in interface MemcachedClientIF
Type Parameters:
T -
Parameters:
tc - the transcoder to serialize and unserialize value
keys - the keys
Returns:
a map of the values (for each value that exists)
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

getBulk

public Map<String,Object> getBulk(String... keys)
Get the values for multiple keys from the cache.

Specified by:
getBulk in interface MemcachedClientIF
Parameters:
keys - the keys
Returns:
a map of the values (for each value that exists)
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

getVersions

public Map<SocketAddress,String> getVersions()
Get the versions of all of the connected memcacheds.

Specified by:
getVersions in interface MemcachedClientIF
Returns:
a Map of SocketAddress to String for connected servers
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

getStats

public Map<SocketAddress,Map<String,String>> getStats()
Get all of the stats from all of the connections.

Specified by:
getStats in interface MemcachedClientIF
Returns:
a Map of a Map of stats replies by SocketAddress
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

getStats

public Map<SocketAddress,Map<String,String>> getStats(String arg)
Get a set of stats from all connections.

Specified by:
getStats in interface MemcachedClientIF
Parameters:
arg - which stats to get
Returns:
a Map of the server SocketAddress to a map of String stat keys to String stat values.
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

getAndLock

public <T> CASValue<T> getAndLock(String key,
                                  int exp,
                                  Transcoder<T> tc)
Getl with a single key. By default the maximum allowed timeout is 30 seconds. Timeouts greater than this will be set to 30 seconds.

Parameters:
key - the key to get and lock
exp - the amount of time the lock should be valid for in seconds.
tc - the transcoder to serialize and unserialize value
Returns:
the result from the cache (null if there is none)
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

getAndLock

public CASValue<Object> getAndLock(String key,
                                   int exp)
Get and lock with a single key and decode using the default transcoder. By default the maximum allowed timeout is 30 seconds. Timeouts greater than this will be set to 30 seconds.

Parameters:
key - the key to get and lock
exp - the amount of time the lock should be valid for in seconds.
Returns:
the result from the cache (null if there is none)
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

incr

public long incr(String key,
                 int by)
Increment the given key by the given amount. Due to the way the memcached server operates on items, incremented and decremented items will be returned as Strings with any operations that return a value.

Specified by:
incr in interface MemcachedClientIF
Parameters:
key - the key
by - the amount to increment
Returns:
the new value (-1 if the key doesn't exist)
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

decr

public long decr(String key,
                 int by)
Decrement the given key by the given value. Due to the way the memcached server operates on items, incremented and decremented items will be returned as Strings with any operations that return a value.

Specified by:
decr in interface MemcachedClientIF
Parameters:
key - the key
by - the value
Returns:
the new value (-1 if the key doesn't exist)
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

incr

public long incr(String key,
                 int by,
                 long def,
                 int exp)
Increment the given counter, returning the new value. Due to the way the memcached server operates on items, incremented and decremented items will be returned as Strings with any operations that return a value.

Specified by:
incr in interface MemcachedClientIF
Parameters:
key - the key
by - the amount to increment
def - the default value (if the counter does not exist)
exp - the expiration of this object
Returns:
the new value, or -1 if we were unable to increment or add
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

decr

public long decr(String key,
                 int by,
                 long def,
                 int exp)
Decrement the given counter, returning the new value. Due to the way the memcached server operates on items, incremented and decremented items will be returned as Strings with any operations that return a value.

Specified by:
decr in interface MemcachedClientIF
Parameters:
key - the key
by - the amount to decrement
def - the default value (if the counter does not exist)
exp - the expiration of this object
Returns:
the new value, or -1 if we were unable to decrement or add
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncIncr

public Future<Long> asyncIncr(String key,
                              int by)
Asychronous increment.

Specified by:
asyncIncr in interface MemcachedClientIF
Parameters:
key - key to increment
by - the amount to increment the value by
Returns:
a future with the incremented value, or -1 if the increment failed.
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

asyncDecr

public Future<Long> asyncDecr(String key,
                              int by)
Asynchronous decrement.

Specified by:
asyncDecr in interface MemcachedClientIF
Parameters:
key - key to increment
by - the amount to increment the value by
Returns:
a future with the decremented value, or -1 if the increment failed.
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

incr

public long incr(String key,
                 int by,
                 long def)
Increment the given counter, returning the new value.

Specified by:
incr in interface MemcachedClientIF
Parameters:
key - the key
by - the amount to increment
def - the default value (if the counter does not exist)
Returns:
the new value, or -1 if we were unable to increment or add
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

decr

public long decr(String key,
                 int by,
                 long def)
Decrement the given counter, returning the new value.

Specified by:
decr in interface MemcachedClientIF
Parameters:
key - the key
by - the amount to decrement
def - the default value (if the counter does not exist)
Returns:
the new value, or -1 if we were unable to decrement or add
Throws:
OperationTimeoutException - if the global operation timeout is exceeded
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

delete

@Deprecated
public Future<Boolean> delete(String key,
                                         int hold)
Deprecated. Hold values are no longer honored.

Delete the given key from the cache.

The hold argument specifies the amount of time in seconds (or Unix time until which) the client wishes the server to refuse "add" and "replace" commands with this key. For this amount of item, the item is put into a delete queue, which means that it won't possible to retrieve it by the "get" command, but "add" and "replace" command with this key will also fail (the "set" command will succeed, however). After the time passes, the item is finally deleted from server memory.

Parameters:
key - the key to delete
hold - how long the key should be unavailable to add commands
Returns:
whether or not the operation was performed

delete

public Future<Boolean> delete(String key)
Delete the given key from the cache.

Specified by:
delete in interface MemcachedClientIF
Parameters:
key - the key to delete
Returns:
whether or not the operation was performed
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

flush

public Future<Boolean> flush(int delay)
Flush all caches from all servers with a delay of application.

Specified by:
flush in interface MemcachedClientIF
Parameters:
delay - the period of time to delay, in seconds
Returns:
whether or not the operation was accepted
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

flush

public Future<Boolean> flush()
Flush all caches from all servers immediately.

Specified by:
flush in interface MemcachedClientIF
Returns:
whether or not the operation was performed
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

listSaslMechanisms

public Set<String> listSaslMechanisms()
Description copied from interface: MemcachedClientIF
Get the set of SASL mechanisms supported by the servers.

Specified by:
listSaslMechanisms in interface MemcachedClientIF
Returns:
the union of all SASL mechanisms supported by the servers.

run

public void run()
Infinitely loop processing IO.

Specified by:
run in interface Runnable
Overrides:
run in class Thread

shutdown

public void shutdown()
Shut down immediately.

Specified by:
shutdown in interface MemcachedClientIF

shutdown

public boolean shutdown(long timeout,
                        TimeUnit unit)
Shut down this client gracefully.

Specified by:
shutdown in interface MemcachedClientIF
Parameters:
timeout - the amount of time time for shutdown
unit - the TimeUnit for the timeout
Returns:
result of the shutdown request

waitForQueues

public boolean waitForQueues(long timeout,
                             TimeUnit unit)
Wait for the queues to die down.

Specified by:
waitForQueues in interface MemcachedClientIF
Parameters:
timeout - the amount of time time for shutdown
unit - the TimeUnit for the timeout
Returns:
result of the request for the wait
Throws:
IllegalStateException - in the rare circumstance where queue is too full to accept any more requests

addObserver

public boolean addObserver(ConnectionObserver obs)
Add a connection observer. If connections are already established, your observer will be called with the address and -1.

Specified by:
addObserver in interface MemcachedClientIF
Parameters:
obs - the ConnectionObserver you wish to add
Returns:
true if the observer was added.

removeObserver

public boolean removeObserver(ConnectionObserver obs)
Remove a connection observer.

Specified by:
removeObserver in interface MemcachedClientIF
Parameters:
obs - the ConnectionObserver you wish to add
Returns:
true if the observer existed, but no longer does

connectionEstablished

public void connectionEstablished(SocketAddress sa,
                                  int reconnectCount)
Description copied from interface: ConnectionObserver
A connection has just successfully been established on the given socket.

Specified by:
connectionEstablished in interface ConnectionObserver
Parameters:
sa - the address of the node whose connection was established
reconnectCount - the number of attempts before the connection was established

connectionLost

public void connectionLost(SocketAddress sa)
Description copied from interface: ConnectionObserver
A connection was just lost on the given socket.

Specified by:
connectionLost in interface ConnectionObserver
Parameters:
sa - the address of the node whose connection was lost
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD