org.craftercms.core.cache

Interface Cache

All Known Implementing Classes:

CacheImpl

public interface Cache

Crafter's Cache API.

Author:

Sumer Jabri, Alfonso Vásquez

Method Summary

Modifier and Type	Method and Description
void	addScope(String scope, int maxItemsInMemory) Adds a new scope to the cache.
void	clearAll() Clears the contents of the entire cache.
void	clearScope(String scope) Clears the contents of the specified scope in the cache.
CacheItem	get(String scope, Object key) Retrieves an item from a scope.
Collection<Object>	getKeys(String scope) Returns a list of the keys of the items present in the specified scope.
Collection<String>	getScopes() Returns the list of scopes this cache manages.
int	getSize(String scope) Returns the quantity of items present in the specified scope.
CacheStatistics	getStatistics(String scope) Returns the statistics of the specified scope in the cache.
boolean	hasKey(String scope, Object key) Returns true if there's and item with the specified key in the specified scope.
boolean	hasScope(String scope) Returns true if the specified scope exists in the cache.
void	put(String scope, Object key, Object value) Puts an item in a scope.
void	put(String scope, Object key, Object value, long expireAfter, long refreshFrequency, CacheLoader loader, Object... loaderParams) Puts and item in a scope.
boolean	remove(String scope, Object key) Removes an item from a scope.
void	removeScope(String scope) Removes an existing scope and all the items that are in it.

Method Detail

hasScope

boolean hasScope(String scope)
          throws InternalCacheEngineException

Returns true if the specified scope exists in the cache.

Parameters:

scope - the name of the scope

Returns:

true if the specified scope exists in the cache

Throws:

InternalCacheEngineException - if an error occurred in the underlying cache implementation

getScopes

Collection<String> getScopes()
                      throws InternalCacheEngineException

Returns the list of scopes this cache manages.

Returns:

the list of available scopes in the cache

Throws:

InternalCacheEngineException - if an error occurred in the underlying cache implementation

addScope

void addScope(String scope,
              int maxItemsInMemory)
       throws InternalCacheEngineException

Adds a new scope to the cache.

Parameters:

scope - the name of the scope

maxItemsInMemory - the maximum number of items in memory, before they are evicted

Throws:

InternalCacheEngineException - if an error occurred in the underlying cache implementation

removeScope

void removeScope(String scope)
          throws InvalidScopeException,
                 InternalCacheEngineException

Removes an existing scope and all the items that are in it.

Parameters:

scope - scope to remove

Throws:

InvalidScopeException - if the specified scope isn't a registered one

InternalCacheEngineException - if an error occurred in the underlying cache implementation

getSize

int getSize(String scope)
     throws InvalidScopeException,
            InternalCacheEngineException

Returns the quantity of items present in the specified scope.

Returns:

the size of the scope (quantity of items)

Throws:

InvalidScopeException - if the specified scope isn't a registered one

InternalCacheEngineException - if an error occurred in the underlying cache implementation

getKeys

Collection<Object> getKeys(String scope)
                    throws InvalidScopeException,
                           InternalCacheEngineException

Returns a list of the keys of the items present in the specified scope.

Returns:

a list of the keys of the available items in the scope

Throws:

InvalidScopeException - if the specified scope isn't a registered one

InternalCacheEngineException - if an error occurred in the underlying cache implementation

hasKey

boolean hasKey(String scope,
               Object key)
        throws InvalidScopeException,
               InternalCacheEngineException

Returns true if there's and item with the specified key in the specified scope.

Returns:

true if the key exists in the scope, false otherwise

Throws:

InvalidScopeException - if the specified scope isn't a registered one

InternalCacheEngineException - if an error occurred in the underlying cache implementation

get

CacheItem get(String scope,
              Object key)
       throws InvalidScopeException,
              InternalCacheEngineException

Retrieves an item from a scope.

Parameters:

scope - scope to get the item from

key - unique key for the item within this scope

Returns:

the requested item if found, null otherwise

Throws:

InvalidScopeException - if the specified scope isn't a registered one

InternalCacheEngineException - if an error occurred in the underlying cache implementation

put

void put(String scope,
         Object key,
         Object value)
  throws InvalidScopeException,
         InternalCacheEngineException

Puts an item in a scope.

Parameters:

scope - scope to add the item to

key - unique key for the item within this scope

value - value to store in the cache

Throws:

InvalidScopeException - if the specified scope isn't a registered one

InternalCacheEngineException - if an error occurred in the underlying cache implementation

put

void put(String scope,
         Object key,
         Object value,
         long expireAfter,
         long refreshFrequency,
         CacheLoader loader,
         Object... loaderParams)
  throws InvalidScopeException,
         InternalCacheEngineException

Puts and item in a scope.

Parameters:

scope - scope to add the item to

key - unique key for the item within this scope

value - value to store in the cache

expireAfter - the amount of time (in ticks, where the tick time span is defined at runtime) before the item can be removed from cache. Use CacheItem.NEVER_EXPIRE to indicate that there's no expiration time.

refreshFrequency - the amount of time (in ticks, where the tick time span is defined at runtime) before items are reloaded into the cache. Use CacheItem.NEVER_REFRESH to indicate that there's no need for the item to be refreshed. Note that when refreshing, there's almost always an old value for the item in the cache before the new value is loaded into the cache. The loader param is also required in order for the item to be refreshed.

loader - the cache loader used to load a new value when the item needs to be refreshed. If not specified and the refreshFrequency is not CacheItem.NEVER_REFRESH, the cache will use a default one.

loaderParams - additional parameters the loader could need

Throws:

InvalidScopeException - if the specified scope isn't a registered one

InternalCacheEngineException - if an error occurred in the underlying cache implementation

remove

boolean remove(String scope,
               Object key)
        throws InvalidScopeException,
               InternalCacheEngineException

Removes an item from a scope.

Parameters:

scope - scope to remove the item from

key - unique key for the item within this scope

Returns:

true if the removal was successful, false otherwise

Throws:

InvalidScopeException - if the specified scope isn't a registered one

InternalCacheEngineException - if an error occurred in the underlying cache implementation

clearAll

void clearAll()
       throws InternalCacheEngineException

Clears the contents of the entire cache.

Throws:

InternalCacheEngineException - if an error occurred in the underlying cache implementation

clearScope

void clearScope(String scope)
         throws InvalidScopeException,
                InternalCacheEngineException

Clears the contents of the specified scope in the cache.

Parameters:

scope - scope to clear

Throws:

InvalidScopeException - if the specified scope isn't a registered one

InternalCacheEngineException - if an error occurred in the underlying cache implementation

getStatistics

CacheStatistics getStatistics(String scope)

Returns the statistics of the specified scope in the cache.

Parameters:

scope - scope to inspect

Returns:

the statistics