com.stackmob.sdkapi.caching
Class CachingService

java.lang.Object
  com.stackmob.sdkapi.caching.CachingService

public abstract class CachingService
extends Object

CachingService provides fast, distributed, in memory access to data. Since your custom code can run on different machines, you can use CachingService to store the results of operations that take a long time to run (like DataService queries) and then get those results from any other machine. Here's an example showing some common usage of CachingService:

     CachingService cachingService = sdkServiceProvider.getCachingService();
     String json =  null;
     try {
         json = cachingService.getString("largeQuery", CachingService.utf8Charset());
     } finally {}
     if(json == null) {
         json = executeLargeDatastoreQuery();
         //cache the result of the large query for 5 seconds
         cachingService.setString("largeQuery", json, CachingService.utf8Charset, 5000);
     }
 

A few things to notice:

1. each value has a key associated with it, and the cache stores the 2 together
2. to get the data back by calling get and passing in the key
3. each key/value pair has a TTL (time-to-live) assigned to it. the TTL value tells the cache how long you want that value to last (in milliseconds)
4. the cache might evict your data at any time to free up memory, so your data might not be there even before the TTL
5. if the cache evicts your data, CachingService will treat it as if it's missing
6. CachingService puts size limits on keys and values, and rate limits on cache operations

Field Summary

static Charset

utf8Charset

Constructor Summary

CachingService()

Method Summary

abstract void	deleteEventually(String key) delete the given key in the background.
abstract byte[]	getBytes(String key) get the value for the given key, in raw byte format
String	getString(String key) alias for getString(key, CachingService.utf8Charset());
String	getString(String key, Charset charset) get the value for the given key, in String format
abstract Boolean	setBytes(String key, byte[] value, long ttlMilliseconds) store the given key/value pair
Boolean	setString(String key, String value, Charset charset, long ttlMilliseconds) store the given key/value pair.
Boolean	setString(String key, String value, long ttlMilliseconds) alias for setString(key, value, CachingService.utf8Charset(), ttlMilliseconds)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

utf8Charset

public static final Charset utf8Charset

Constructor Detail

CachingService

public CachingService()

Method Detail

getString

public String getString(String key,
                        Charset charset)
                 throws TimeoutException,
                        RateLimitedException,
                        DataSizeException

get the value for the given key, in String format

Parameters:

key - the key to get

charset - the charset to use to build the resultant

Returns:

the String for that key, or null if the key didn't exist

Throws:

TimeoutException - if there was a timeout communicating with the cache

RateLimitedException - if there was a rate limit imposed on the cache get request

DataSizeException - if the size of the key or its value in the cache was over the Stackmob-defined limit

getString

public String getString(String key)
                 throws TimeoutException,
                        RateLimitedException,
                        DataSizeException

alias for getString(key, CachingService.utf8Charset());

Parameters:

key - the key to fetch

Returns:

the value for key

Throws:

TimeoutException - if there was a timeout communicating with the cache

RateLimitedException - if there was a rate limit imposed on the cache get request

DataSizeException - if the size of the key or its value in the cache was over the Stackmob-defined limit

getBytes

public abstract byte[] getBytes(String key)
                         throws TimeoutException,
                                RateLimitedException,
                                DataSizeException

get the value for the given key, in raw byte format

Parameters:

key - the key to get

Returns:

the byte array for that key, or null if the key didn't exist

Throws:

TimeoutException - if there was a timeout communicating with the cache

RateLimitedException - if there was a rate limit imposed on the cache get request

DataSizeException - if the size of the key or its value in the cache was over the Stackmob-defined limit

setString

public Boolean setString(String key,
                         String value,
                         Charset charset,
                         long ttlMilliseconds)
                  throws TimeoutException,
                         RateLimitedException,
                         DataSizeException,
                         TTLTooBigException

store the given key/value pair. convenience method for setBytes(key, value.getBytes(charset), ttlMilliseconds)

Parameters:

key - the key to store

value - the value to store for the given key

charset - the charset to use

ttlMilliseconds - the TTL for this key/value pair, in milliseconds. if ttlMillseconds <= 0, it's equivalent to passing the longest available TTL

Returns:

true if the set succeeded, false otherwise

Throws:

TimeoutException - if there was a timeout communicating with the cache

RateLimitedException - if there was a rate limit imposed1 on this cache get request

TTLTooBigException - if the given TTL was too big for our caching system to handle

DataSizeException

setString

public Boolean setString(String key,
                         String value,
                         long ttlMilliseconds)
                  throws TimeoutException,
                         RateLimitedException,
                         DataSizeException,
                         TTLTooBigException

alias for setString(key, value, CachingService.utf8Charset(), ttlMilliseconds)

Parameters:

key - the key to store

value - the value to store for the given key

ttlMilliseconds - the TTL for this key/value pair, in milliseconds. if ttlMillseconds <= 0, it's equivalent to passing the longest available TTL

Returns:

true if the set succeeded, false otherwise

Throws:

TimeoutException - if there was a timeout communicating with the cache

RateLimitedException - if there was a rate limit imposed1 on this cache get request

TTLTooBigException - if the given TTL was too big for our caching system to handle

DataSizeException

setBytes

public abstract Boolean setBytes(String key,
                                 byte[] value,
                                 long ttlMilliseconds)
                          throws TimeoutException,
                                 RateLimitedException,
                                 DataSizeException,
                                 TTLTooBigException

store the given key/value pair

Parameters:

key - the key to store

value - the value to store for key

ttlMilliseconds - the TTL for this key/value pair, in milliseconds. if ttlMillseconds <= 0, it's equivalent to passing the longest available TTL

Returns:

true if the set succeeded, false otherwise

Throws:

TimeoutException - if there was a timeout communicating with the cache

RateLimitedException - if there was a rate limit imposed1 on this cache get request

TTLTooBigException - if the given TTL was too big for our caching system to handle

DataSizeException

deleteEventually

public abstract void deleteEventually(String key)
                               throws DataSizeException

delete the given key in the background. note that the key may not be deleted immediately after this method returns

Parameters:

key - the key to delete

Throws:

DataSizeException - if the given key is too big