MemcachedClient Class Reference

Inherits net::spy::SpyThread.

Collaboration diagram for MemcachedClient:

Collaboration graph
[legend]

List of all members.

Public Member Functions

Future< Boolean > add (String key, int exp, Object o)
Future< Boolean > append (long cas, String key, Object val)
Future< CASResponseasyncCAS (String key, long casId, Object value)
Future< Object > asyncGet (final String key)
Future< Map< String, Object > > asyncGetBulk (String...keys)
Future< Map< String, Object > > asyncGetBulk (Collection< String > keys)
Future< CASValue< Object > > asyncGets (final String key)
CASResponse cas (String key, long casId, Object value) throws OperationTimeoutException
long decr (String key, int by, long def) throws OperationTimeoutException
long decr (String key, int by) throws OperationTimeoutException
Future< Boolean > delete (String key)
Future< Boolean > delete (String key, int hold)
Future< Boolean > flush ()
Future< Boolean > flush (final int delay)
Object get (String key) throws OperationTimeoutException
Collection< SocketAddress > getAvailableServers ()
Map< String, Object > getBulk (String...keys) throws OperationTimeoutException
Map< String, Object > getBulk (Collection< String > keys) throws OperationTimeoutException
CASValue< Object > gets (String key) throws OperationTimeoutException
Map< SocketAddress, Map
< String, String > > 
getStats ()
Transcoder< Object > getTranscoder ()
Collection< SocketAddress > getUnavailableServers ()
Map< SocketAddress, StringgetVersions ()
long incr (String key, int by, int def) throws OperationTimeoutException
long incr (String key, int by) throws OperationTimeoutException
 MemcachedClient (ConnectionFactory cf, List< InetSocketAddress > addrs) throws IOException
 MemcachedClient (List< InetSocketAddress > addrs) throws IOException
 MemcachedClient (InetSocketAddress...ia) throws IOException
Future< Boolean > prepend (long cas, String key, Object val)
Future< Boolean > replace (String key, int exp, Object o)
void run ()
Future< Boolean > set (String key, int exp, Object o)
void setTranscoder (Transcoder< Object > tc)
boolean shutdown (long timeout, TimeUnit unit)
void shutdown ()
boolean waitForQueues (long timeout, TimeUnit unit)

Static Public Attributes

static final int MAX_KEY_LENGTH = 250

Package Functions

public< T > Future< Boolean > add (String key, int exp, T o, Transcoder< T > tc)
Operation addOp (final String key, final Operation op)
public< T > Future< Boolean > append (long cas, String key, T val, Transcoder< T > tc)
public< T > Future< CASResponseasyncCAS (String key, long casId, T value, Transcoder< T > tc)
private< T > Future< Boolean > asyncCat (ConcatenationType catType, long cas, String key, T value, Transcoder< T > tc)
public< T > Future< T > asyncGet (final String key, final Transcoder< T > tc)
public< T > Future< Map
< String, T > > 
asyncGetBulk (Transcoder< T > tc, String...keys)
public< T > Future< Map
< String, T > > 
asyncGetBulk (Collection< String > keys, final Transcoder< T > tc)
public< T > Future< CASValue< T > > asyncGets (final String key, final Transcoder< T > tc)
private< T > Future< Boolean > asyncStore (StoreType storeType, String key, int exp, T value, Transcoder< T > tc)
CountDownLatch broadcastOp (final BroadcastOpFactory of)
public< T > CASResponse cas (String key, long casId, T value, Transcoder< T > tc) throws OperationTimeoutException
public< T > T get (String key, Transcoder< T > tc) throws OperationTimeoutException
public< T > Map< String, T > getBulk (Transcoder< T > tc, String...keys) throws OperationTimeoutException
public< T > Map< String, T > getBulk (Collection< String > keys, Transcoder< T > tc) throws OperationTimeoutException
public< T > CASValue< T > gets (String key, Transcoder< T > tc) throws OperationTimeoutException
public< T > Future< Boolean > prepend (long cas, String key, T val, Transcoder< T > tc)
public< T > Future< Boolean > replace (String key, int exp, T o, Transcoder< T > tc)
public< T > Future< Boolean > set (String key, int exp, T o, Transcoder< T > tc)

Package Attributes

final OperationFactory opFact
Transcoder< Object > transcoder = null

Private Member Functions

Future< Boolean > asyncStore (StoreType storeType, String key, int exp, Object value)
CountDownLatch broadcastOp (BroadcastOpFactory of, boolean checkShuttingDown)
void checkState ()
Map< SocketAddress, Map
< String, String > > 
getStats (final String arg)
void logRunException (Exception e)
long mutate (Mutator m, String key, int by, long def, int exp) throws OperationTimeoutException
long mutateWithDefault (Mutator t, String key, int by, long def, int exp) throws OperationTimeoutException
void validateKey (String key)

Private Attributes

final MemcachedConnection conn
final long operationTimeout
volatile boolean running = true
volatile boolean shuttingDown = false


Detailed Description

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
  MemcachedClient c=new MemcachedClient(
      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);
  } catch(TimeoutException 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.
      f.cancel();
      // Do other timeout related stuff
  }
 

Constructor & Destructor Documentation

MemcachedClient ( InetSocketAddress...  ia  )  throws IOException

Get a memcache client operating on the specified memcached locations.

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

MemcachedClient ( List< InetSocketAddress >  addrs  )  throws IOException

Get a memcache client over the specified memcached locations.

Parameters:
addrs the socket addrs
Exceptions:
IOException if connections cannot be established

MemcachedClient ( ConnectionFactory  cf,
List< InetSocketAddress >  addrs 
) throws IOException

Get a memcache client over the specified memcached locations.

Parameters:
bufSize read buffer size per connection (in bytes)
addrs the socket addresses
Exceptions:
IOException if connections cannot be established


Member Function Documentation

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:

<blockquote>

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. </blockquote>

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

public<T> Future<Boolean> add ( String  key,
int  exp,
o,
Transcoder< T >  tc 
) [package]

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:

<blockquote>

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. </blockquote>

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

Operation addOp ( final String  key,
final Operation  op 
) [package]

(internal use) Add a raw operation to a numbered connection. This method is exposed for testing.

Parameters:
which server number
op the operation to perform
Returns:
the Operation

public<T> Future<Boolean> append ( long  cas,
String  key,
val,
Transcoder< T >  tc 
) [package]

Append to an existing value in the cache.

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

Future<Boolean> append ( long  cas,
String  key,
Object  val 
)

Append to an existing value in the cache.

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

Future<CASResponse> asyncCAS ( String  key,
long  casId,
Object  value 
)

Asynchronous CAS operation using the default transcoder.

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

public<T> Future<CASResponse> asyncCAS ( String  key,
long  casId,
value,
Transcoder< T >  tc 
) [package]

Asynchronous CAS operation.

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

private<T> Future<Boolean> asyncCat ( ConcatenationType  catType,
long  cas,
String  key,
value,
Transcoder< T >  tc 
) [package]

Future<Object> asyncGet ( final String  key  ) 

Get the given key asynchronously and decode with the default transcoder.

Parameters:
key the key to fetch
Returns:
a future that will hold the return value of the fetch

public<T> Future<T> asyncGet ( final String  key,
final Transcoder< T >  tc 
) [package]

Get the given key asynchronously.

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

Future<Map<String, Object> > asyncGetBulk ( String...  keys  ) 

Varargs wrapper for asynchronous bulk gets with the default transcoder.

Parameters:
keys one more more keys to get
Returns:
the future values of those keys

public<T> Future<Map<String, T> > asyncGetBulk ( Transcoder< T >  tc,
String...  keys 
) [package]

Varargs wrapper for asynchronous bulk gets.

Parameters:
tc the transcoder to serialize and unserialize value
keys one more more keys to get
Returns:
the future values of those keys

Future<Map<String, Object> > asyncGetBulk ( Collection< String keys  ) 

Asynchronously get a bunch of objects from the cache and decode them with the given transcoder.

Parameters:
keys the keys to request
Returns:
a Future result of that fetch

public<T> Future<Map<String, T> > asyncGetBulk ( Collection< String keys,
final Transcoder< T >  tc 
) [package]

Asynchronously get a bunch of objects from the cache.

Parameters:
keys the keys to request
tc the transcoder to serialize and unserialize value
Returns:
a Future result of that fetch

Future<CASValue<Object> > asyncGets ( final String  key  ) 

Gets (with CAS support) the given key asynchronously and decode using the default transcoder.

Parameters:
key the key to fetch
Returns:
a future that will hold the return value of the fetch

public<T> Future<CASValue<T> > asyncGets ( final String  key,
final Transcoder< T >  tc 
) [package]

Gets (with CAS support) the given key asynchronously.

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

Future<Boolean> asyncStore ( StoreType  storeType,
String  key,
int  exp,
Object  value 
) [private]

private<T> Future<Boolean> asyncStore ( StoreType  storeType,
String  key,
int  exp,
value,
Transcoder< T >  tc 
) [package]

CountDownLatch broadcastOp ( BroadcastOpFactory  of,
boolean  checkShuttingDown 
) [private]

CountDownLatch broadcastOp ( final BroadcastOpFactory  of  )  [package]

CASResponse cas ( String  key,
long  casId,
Object  value 
) throws OperationTimeoutException

Perform a synchronous CAS operation with the default transcoder.

Parameters:
key the key
casId the CAS identifier (from a gets operation)
value the new value
Returns:
a CASResponse
Exceptions:
OperationTimeoutException if the global operation timeout is exceeded

public<T> CASResponse cas ( String  key,
long  casId,
value,
Transcoder< T >  tc 
) throws OperationTimeoutException [package]

Perform a synchronous CAS operation.

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
Exceptions:
OperationTimeoutException if global operation timeout is exceeded

void checkState (  )  [private]

long decr ( String  key,
int  by,
long  def 
) throws OperationTimeoutException

Decrement the given counter, returning the new value.

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
Exceptions:
OperationTimeoutException if the global operation timeout is exceeded

long decr ( String  key,
int  by 
) throws OperationTimeoutException

Decrement the given key by the given value.

Parameters:
key the key
by the value
Returns:
the new value (-1 if the key doesn't exist)
Exceptions:
OperationTimeoutException if the global operation timeout is exceeded

Future<Boolean> delete ( String  key  ) 

Shortcut to delete that doesn't put a hold on the key.

Future<Boolean> delete ( String  key,
int  hold 
)

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

Future<Boolean> flush (  ) 

Flush all caches from all servers immediately.

Future<Boolean> flush ( final int  delay  ) 

Flush all caches from all servers with a delay of application.

Object get ( String  key  )  throws OperationTimeoutException

Get with a single key and decode using the default transcoder.

Parameters:
key the key to get
Returns:
the result from the cache (null if there is none)
Exceptions:
OperationTimeoutException if the global operation timeout is exceeded

public<T> T get ( String  key,
Transcoder< T >  tc 
) throws OperationTimeoutException [package]

Get with a single key.

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)
Exceptions:
OperationTimeoutException if the global operation timeout is exceeded

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.

Map<String, Object> getBulk ( String...  keys  )  throws OperationTimeoutException

Get the values for multiple keys from the cache.

Parameters:
keys the keys
Returns:
a map of the values (for each value that exists)
Exceptions:
OperationTimeoutException if the global operation timeout is exceeded

public<T> Map<String, T> getBulk ( Transcoder< T >  tc,
String...  keys 
) throws OperationTimeoutException [package]

Get the values for multiple keys from the cache.

Parameters:
tc the transcoder to serialize and unserialize value
keys the keys
Returns:
a map of the values (for each value that exists)
Exceptions:
OperationTimeoutException if the global operation timeout is exceeded

Map<String, Object> getBulk ( Collection< String keys  )  throws OperationTimeoutException

Get the values for multiple keys from the cache.

Parameters:
keys the keys
Returns:
a map of the values (for each value that exists)
Exceptions:
OperationTimeoutException if the global operation timeout is exceeded

public<T> Map<String, T> getBulk ( Collection< String keys,
Transcoder< T >  tc 
) throws OperationTimeoutException [package]

Get the values for multiple keys from the cache.

Parameters:
keys the keys
tc the transcoder to serialize and unserialize value
Returns:
a map of the values (for each value that exists)
Exceptions:
OperationTimeoutException if the global operation timeout is exceeded

CASValue<Object> gets ( String  key  )  throws OperationTimeoutException

Gets (with CAS support) with a single key using the default transcoder.

Parameters:
key the key to get
Returns:
the result from the cache and CAS id (null if there is none)
Exceptions:
OperationTimeoutException if the global operation timeout is exceeded

public<T> CASValue<T> gets ( String  key,
Transcoder< T >  tc 
) throws OperationTimeoutException [package]

Gets (with CAS support) with a single key.

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)
Exceptions:
OperationTimeoutException if global operation timeout is exceeded

Map<SocketAddress, Map<String, String> > getStats ( final String  arg  )  [private]

Map<SocketAddress, Map<String, String> > getStats (  ) 

Get all of the stats from all of the connections.

Transcoder<Object> getTranscoder (  ) 

Get the default transcoder that's in use.

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.

Map<SocketAddress, String> getVersions (  ) 

Get the versions of all of the connected memcacheds.

long incr ( String  key,
int  by,
int  def 
) throws OperationTimeoutException

Increment the given counter, returning the new value.

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
Exceptions:
OperationTimeoutException if the global operation timeout is exceeded

long incr ( String  key,
int  by 
) throws OperationTimeoutException

Increment the given key by the given amount.

Parameters:
key the key
by the amount to increment
Returns:
the new value (-1 if the key doesn't exist)
Exceptions:
OperationTimeoutException if the global operation timeout is exceeded

void logRunException ( Exception  e  )  [private]

long mutate ( Mutator  m,
String  key,
int  by,
long  def,
int  exp 
) throws OperationTimeoutException [private]

long mutateWithDefault ( Mutator  t,
String  key,
int  by,
long  def,
int  exp 
) throws OperationTimeoutException [private]

public<T> Future<Boolean> prepend ( long  cas,
String  key,
val,
Transcoder< T >  tc 
) [package]

Prepend to an existing value in the cache.

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

Future<Boolean> prepend ( long  cas,
String  key,
Object  val 
)

Prepend to an existing value in the cache.

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

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:

<blockquote>

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. </blockquote>

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

public<T> Future<Boolean> replace ( String  key,
int  exp,
o,
Transcoder< T >  tc 
) [package]

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:

<blockquote>

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. </blockquote>

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

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.

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

<blockquote>

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. </blockquote>

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

public<T> Future<Boolean> set ( String  key,
int  exp,
o,
Transcoder< T >  tc 
) [package]

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:

<blockquote>

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. </blockquote>

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

void setTranscoder ( Transcoder< Object >  tc  ) 

Set the default transcoder for managing the cache representations of objects going in and out of the cache.

boolean shutdown ( long  timeout,
TimeUnit  unit 
)

Shut down this client gracefully.

void shutdown (  ) 

Shut down immediately.

void validateKey ( String  key  )  [private]

boolean waitForQueues ( long  timeout,
TimeUnit  unit 
)

Wait for the queues to die down.


Member Data Documentation

final MemcachedConnection conn [private]

final int MAX_KEY_LENGTH = 250 [static]

Maximum supported key length.

final long operationTimeout [private]

final OperationFactory opFact [package]

volatile boolean running = true [private]

volatile boolean shuttingDown = false [private]

Transcoder<Object> transcoder = null [package]


The documentation for this class was generated from the following file:

Generated on Sat May 26 06:43:37 2012 for Project Wonder by  doxygen 1.5.8