org.jboss.cache
Interface Cache<K,V>

All Superinterfaces:

Lifecycle

All Known Subinterfaces:

CacheSPI<K,V>

All Known Implementing Classes:

CacheInvocationDelegate

@ThreadSafe
public interface Cache<K,V>
extends Lifecycle

Interface for a Cache where data mappings are grouped and stored in a tree data structure consisting of Nodes.

This is the central construct and basic client API of JBoss Cache and is used for cache-wide operations.

The cache is constructed using a CacheFactory and is started using start(), if not already started by the CacheFactory.

Once constructed, the Cache interface can be used to create or access Nodes, which contain data. Once references to Nodes are obtained, data can be stored in them,

As a convenience (and mainly to provide a familiar API to the older JBoss Cache 1.x.x releases) methods are provided that operate directly on nodes.

• put(Fqn,Object,Object)
• put(Fqn,java.util.Map)
• get(Fqn,Object)
• remove(Fqn,Object)
• removeNode(Fqn)

A simple example of usage:

    // creates with default settings and starts the cache
    Cache cache = new DefaultCacheFactory().createCache();
    Fqn personRecords = Fqn.fromString("/org/mycompany/personRecords");
 

    Node rootNode = cache.getRoot();
    Node personRecordsNode = rootNode.addChild(personRecords);
 

    // now add some person records.
    Fqn peterGriffin = Fqn.fromString("/peterGriffin");
    Fqn stewieGriffin = Fqn.fromString("/stewieGriffin");
 

    // the addChild() API uses relative Fqns
    Node peter = personRecordsNode.addChild(peterGriffin);
    Node stewie = personRecordsNode.addChild(stewieGriffin);
 

    peter.put("name", "Peter Griffin");
    peter.put("ageGroup", "MidLifeCrisis");
    peter.put("homicidal", Boolean.FALSE);
 

    stewie.put("name", "Stewie Griffin");
    stewie.put("ageGroup", "Infant");
    stewie.put("homicidal", Boolean.TRUE);
 

    peter.getFqn().toString(); // will print out /org/mycompany/personRecords/peterGriffin
    stewie.getFqn().toString(); // will print out /org/mycompany/personRecords/stewieGriffin
 

    peter.getFqn().getParent().equals(stewie.getFqn().getParent()); // will return true
 

 

For more information, please read the JBoss Cache user guide and tutorial, available on the JBoss Cache documentation site, and look through the examples shipped with the JBoss Cache distribution.

Since:

2.0.0

Author:

Manik Surtani (manik AT jboss DOT org)

See Also:

Node, CacheFactory

Method Summary

void	addCacheListener(Object listener) Adds a CacheListener-annotated object to the entire cache.
void	addInterceptor(CommandInterceptor i, Class<? extends CommandInterceptor> afterInterceptor) Adds a custom interceptor to the interceptor chain, after an instance of the specified interceptor type.
void	addInterceptor(CommandInterceptor i, int position) Adds a custom interceptor to the interceptor chain, at specified position, where the first interceptor in the chain is at position 0 and the last one at getInterceptorChain().size() - 1.
void	clearData(Fqn fqn) Removes the keys and properties from a named node.
void	clearData(String fqn) Convenience method that takes in a String represenation of the Fqn.
void	create() Lifecycle method that initializes configuration state, the root node, etc.
void	destroy() Lifecycle method that destroys the cache and removes any interceptors/configuration elements.
void	endBatch(boolean successful) Ends an existing ongoing batch.
void	evict(Fqn fqn) Eviction call that evicts the specified Node from memory.
void	evict(Fqn fqn, boolean recursive) Eviction call that evicts the specified Node from memory.
V	get(Fqn fqn, K key) Convenience method that allows for direct access to the data in a Node.
V	get(String fqn, K key) Convenience method that takes a string representation of an Fqn.
Set<Object>	getCacheListeners() Retrieves an immutable List of objects annotated as CacheListeners attached to the cache.
CacheStatus	getCacheStatus() Gets where the cache currently is its lifecycle transitions.
Set<Object>	getChildrenNames(Fqn fqn) Returns all children of a given node.
Set<String>	getChildrenNames(String fqn) Convenience method that takes a String representation of an Fqn.
Configuration	getConfiguration() Retrieves the configuration of this cache.
Map<K,V>	getData(Fqn fqn) Retrieves a defensively copied data map of the underlying node.
InvocationContext	getInvocationContext()
Set<K>	getKeys(Fqn fqn) Returns a set of attribute keys for the Fqn.
Set<K>	getKeys(String fqn) Convenience method that takes in a String represenation of the Fqn.
org.jgroups.Address	getLocalAddress() Returns the local address of this cache in a cluster, or null if running in local mode.
List<org.jgroups.Address>	getMembers() Returns a list of members in the cluster, or null if running in local mode.
Node<K,V>	getNode(Fqn fqn) A convenience method to retrieve a node directly from the cache.
Node<K,V>	getNode(String fqn) Convenience method that takes a string representation of an Fqn.
Region	getRegion(Fqn fqn, boolean createIfAbsent) Retrieves a Region for a given Fqn.
Node<K,V>	getRoot() Returns the root node of this cache.
String	getVersion() Returns the version of the cache as a string.
boolean	isLeaf(Fqn fqn) Tests if a node is a leaf, i.e., doesn't have any children
boolean	isLeaf(String fqn) Tests if a node is a leaf, i.e., doesn't have any children
void	move(Fqn nodeToMove, Fqn newParent) Moves a part of the cache to a different subtree.
void	move(String nodeToMove, String newParent) Convenience method that takes in string representations of Fqns.
V	put(Fqn fqn, K key, V value) Associates the specified value with the specified key for a Node in this cache.
void	put(Fqn fqn, Map<? extends K,? extends V> data) Copies all of the mappings from the specified map to a Node.
V	put(String fqn, K key, V value) Convenience method that takes a string representation of an Fqn.
void	put(String fqn, Map<? extends K,? extends V> data) Convenience method that takes a string representation of an Fqn.
void	putForExternalRead(Fqn fqn, K key, V value) Under special operating behavior, associates the value with the specified key for a node identified by the Fqn passed in.
V	remove(Fqn fqn, K key) Removes the mapping for this key from a Node.
V	remove(String fqn, K key) Convenience method that takes a string representation of an Fqn.
void	removeCacheListener(Object listener) Removes a CacheListener-annotated object from the cache.
void	removeInterceptor(Class<? extends CommandInterceptor> interceptorType) Removes the interceptor of specified type.
void	removeInterceptor(int position) Removes the interceptor at a specified position, where the first interceptor in the chain is at position 0 and the last one at getInterceptorChain().size() - 1.
boolean	removeNode(Fqn fqn) Removes a Node indicated by absolute Fqn.
boolean	removeNode(String fqn) Convenience method that takes a string representation of an Fqn.
boolean	removeRegion(Fqn fqn) Removes a region denoted by the Fqn passed in.
void	setInvocationContext(InvocationContext ctx) Sets the passed in InvocationContext as current.
void	start() Lifecycle method that starts the cache loader, starts cache replication, starts the region manager, etc., and (if configured) warms the cache using a state transfer or cache loader preload.
void	startBatch() Starts a batch.
void	stop() Lifecycle method that stops the cache, including replication, clustering, cache loading, notifications, etc., and clears all cache in-memory state.

Method Detail

getConfiguration

Configuration getConfiguration()

Retrieves the configuration of this cache.

Returns:

the configuration.

getRoot

Node<K,V> getRoot()

Returns the root node of this cache.

Returns:

the root node

addCacheListener

void addCacheListener(Object listener)

Adds a CacheListener-annotated object to the entire cache. The object passed in needs to be properly annotated with the CacheListener annotation otherwise an IncorrectCacheListenerException will be thrown.

Parameters:

listener - listener to add

removeCacheListener

void removeCacheListener(Object listener)

Removes a CacheListener-annotated object from the cache. The object passed in needs to be properly annotated with the CacheListener annotation otherwise an IncorrectCacheListenerException will be thrown.

Parameters:

listener - listener to remove

getCacheListeners

Set<Object> getCacheListeners()

Retrieves an immutable List of objects annotated as CacheListeners attached to the cache.

Returns:

an immutable List of objects annotated as CacheListeners attached to the cache.

put

V put(Fqn fqn,
      K key,
      V value)

Associates the specified value with the specified key for a Node in this cache. If the Node previously contained a mapping for this key, the old value is replaced by the specified value.

Parameters:

fqn - absolute Fqn to the Node to be accessed.

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the Node previously associated null with the specified key, if the implementation supports null values.

Throws:

IllegalStateException - if the cache is not in a started state.

put

V put(String fqn,
      K key,
      V value)

Convenience method that takes a string representation of an Fqn. Otherwise identical to put(Fqn, Object, Object)

Parameters:

fqn - String representation of the Fqn

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the Node previously associated null with the specified key, if the implementation supports null values.

Throws:

IllegalStateException - if the cache is not in a started state

putForExternalRead

void putForExternalRead(Fqn fqn,
                        K key,
                        V value)

Under special operating behavior, associates the value with the specified key for a node identified by the Fqn passed in.

• Only goes through if the node specified does not exist; no-op otherwise.
• Force asynchronous mode for replication to prevent any blocking.
• invalidation does not take place.
• 0ms lock timeout to prevent any blocking here either. If the lock is not acquired, this method is a no-op, and swallows the timeout exception.
• Ongoing transactions are suspended before this call, so failures here will not affect any ongoing transactions.
• Errors and exceptions are 'silent' - logged at a much lower level than normal, and this method does not throw exceptions

This method is for caching data that has an external representation in storage, where, concurrent modification and transactions are not a consideration, and failure to put the data in the cache should be treated as a 'suboptimal outcome' rather than a 'failing outcome'.

An example of when this method is useful is when data is read from, for example, a legacy datastore, and is cached before returning the data to the caller. Subsequent calls would prefer to get the data from the cache and if the data doesn't exist in the cache, fetch again from the legacy datastore.

See JBCACHE-848 for details around this feature.

Parameters:

fqn - absolute Fqn to the Node to be accessed.

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Throws:

IllegalStateException - if getCacheStatus() would not return CacheStatus.STARTED.

put

void put(Fqn fqn,
         Map<? extends K,? extends V> data)

Copies all of the mappings from the specified map to a Node.

Parameters:

fqn - absolute Fqn to the Node to copy the data to

data - mappings to copy

Throws:

IllegalStateException - if the cache is not in a started state

put

void put(String fqn,
         Map<? extends K,? extends V> data)

Convenience method that takes a string representation of an Fqn. Otherwise identical to put(Fqn, java.util.Map)

Parameters:

fqn - String representation of the Fqn

data - data map to insert

Throws:

IllegalStateException - if the cache is not in a started state

remove

V remove(Fqn fqn,
         K key)

Removes the mapping for this key from a Node. Returns the value to which the Node previously associated the key, or null if the Node contained no mapping for this key.

Parameters:

fqn - absolute Fqn to the Node to be accessed.

key - key whose mapping is to be removed from the Node

Returns:

previous value associated with specified Node's key

Throws:

IllegalStateException - if the cache is not in a started state

remove

V remove(String fqn,
         K key)

Convenience method that takes a string representation of an Fqn. Otherwise identical to remove(Fqn, Object)

Parameters:

fqn - string representation of the Fqn to retrieve

key - key to remove

Returns:

old value removed, or null if the fqn does not exist

Throws:

IllegalStateException - if the cache is not in a started state

removeNode

boolean removeNode(Fqn fqn)

Removes a Node indicated by absolute Fqn.

Parameters:

fqn - Node to remove

Returns:

true if the node was removed, false if the node was not found

Throws:

IllegalStateException - if the cache is not in a started state

removeNode

boolean removeNode(String fqn)

Convenience method that takes a string representation of an Fqn. Otherwise identical to removeNode(Fqn)

Parameters:

fqn - string representation of the Fqn to retrieve

Returns:

true if the node was found and removed, false otherwise

Throws:

IllegalStateException - if the cache is not in a started state

getNode

Node<K,V> getNode(Fqn fqn)

A convenience method to retrieve a node directly from the cache. Equivalent to calling cache.getRoot().getChild(fqn).

Parameters:

fqn - fqn of the node to retrieve

Returns:

a Node object, or a null if the node does not exist.

Throws:

IllegalStateException - if the cache is not in a started state

getNode

Node<K,V> getNode(String fqn)

Convenience method that takes a string representation of an Fqn. Otherwise identical to getNode(Fqn)

Parameters:

fqn - string representation of the Fqn to retrieve

Returns:

node, or null if the node does not exist

Throws:

IllegalStateException - if the cache is not in a started state

getChildrenNames

Set<Object> getChildrenNames(Fqn fqn)

Returns all children of a given node. Returns an empty set if there are no children. The set is unmodifiable.

Parameters:

fqn - The fully qualified name of the node

Returns:

Set an unmodifiable set of children names, Object.

getChildrenNames

Set<String> getChildrenNames(String fqn)

Convenience method that takes a String representation of an Fqn. Otherwise identical to getChildrenNames(Fqn)

Parameters:

fqn - as a string

Returns:

Set an unmodifiable set of children names, Object.

isLeaf

boolean isLeaf(Fqn fqn)

Tests if a node is a leaf, i.e., doesn't have any children

Parameters:

fqn - fqn to test

Returns:

true if it is a leaf, false otherwise

isLeaf

boolean isLeaf(String fqn)

Tests if a node is a leaf, i.e., doesn't have any children

Parameters:

fqn - fqn to test

Returns:

true if it is a leaf, false otherwise

get

V get(Fqn fqn,
      K key)

Convenience method that allows for direct access to the data in a Node.

Parameters:

fqn - absolute Fqn to the Node to be accessed.

key - key under which value is to be retrieved.

Returns:

returns data held under specified key in Node denoted by specified Fqn.

Throws:

IllegalStateException - if the cache is not in a started state

get

V get(String fqn,
      K key)

Convenience method that takes a string representation of an Fqn. Otherwise identical to get(Fqn, Object)

Parameters:

fqn - string representation of the Fqn to retrieve

key - key to fetch

Returns:

value, or null if the fqn does not exist.

Throws:

IllegalStateException - if the cache is not in a started state

evict

void evict(Fqn fqn,
           boolean recursive)

Eviction call that evicts the specified Node from memory.

Parameters:

fqn - absolute Fqn to the Node to be evicted.

recursive - evicts children as well

Throws:

IllegalStateException - if the cache is not in a started state

evict

void evict(Fqn fqn)

Eviction call that evicts the specified Node from memory. Not recursive.

Parameters:

fqn - absolute Fqn to the Node to be evicted.

Throws:

IllegalStateException - if the cache is not in a started state

getRegion

Region getRegion(Fqn fqn,
                 boolean createIfAbsent)

Retrieves a Region for a given Fqn. If the region does not exist, and

createIfAbsent

is true, then one is created.

If not, parent Fqns will be consulted in turn for registered regions, gradually working up to Fqn.ROOT. If no regions are defined in any of the parents either, a null is returned.

Parameters:

fqn - Fqn that is contained in a region.

createIfAbsent - If true, will create a new associated region if not found.

Returns:

a MarshRegion. Null if none is found.

See Also:

Region

removeRegion

boolean removeRegion(Fqn fqn)

Removes a region denoted by the Fqn passed in.

Parameters:

fqn - of the region to remove

Returns:

true if a region did exist and was removed; false otherwise.

create

void create()
            throws CacheException

Lifecycle method that initializes configuration state, the root node, etc.

Specified by:

create in interface Lifecycle

Throws:

CacheException - if there are creation problems

start

void start()
           throws CacheException

Lifecycle method that starts the cache loader, starts cache replication, starts the region manager, etc., and (if configured) warms the cache using a state transfer or cache loader preload.

Specified by:

start in interface Lifecycle

Throws:

CacheException - if there are startup problems

stop

void stop()

Lifecycle method that stops the cache, including replication, clustering, cache loading, notifications, etc., and clears all cache in-memory state.

State can be reconstituted by using either a cache loader or state transfer when the cache starts again.

Specified by:

stop in interface Lifecycle

destroy

void destroy()

Lifecycle method that destroys the cache and removes any interceptors/configuration elements. Cache can then be restarted (potentially after reconfiguring) using create() and start().

Specified by:

destroy in interface Lifecycle

getCacheStatus

CacheStatus getCacheStatus()

Gets where the cache currently is its lifecycle transitions.

Returns:

the CacheStatus. Will not return null.

getInvocationContext

InvocationContext getInvocationContext()

Returns:

the current invocation context for the current invocation and cache instance.

Throws:

IllegalStateException - if the cache has been destroyed.

setInvocationContext

void setInvocationContext(InvocationContext ctx)

Sets the passed in InvocationContext as current.

Parameters:

ctx - invocation context to use

Throws:

IllegalStateException - if the cache has been destroyed.

getLocalAddress

org.jgroups.Address getLocalAddress()

Returns the local address of this cache in a cluster, or null if running in local mode.

Returns:

the local address of this cache in a cluster, or null if running in local mode.

getMembers

List<org.jgroups.Address> getMembers()

Returns a list of members in the cluster, or null if running in local mode.

Returns:

a List of members in the cluster, or null if running in local mode.

move

void move(Fqn nodeToMove,
          Fqn newParent)
          throws NodeNotExistsException

Moves a part of the cache to a different subtree.

E.g.:

assume a cache structure such as:

  /a/b/c
  /a/b/d
  /a/b/e
 

 

  Fqn f1 = Fqn.fromString("/a/b/c");
  Fqn f2 = Fqn.fromString("/a/b/d");
 

  cache.move(f1, f2);
 

Will result in:

 

 /a/b/d/c
 /a/b/e
 

 

and now

  Fqn f3 = Fqn.fromString("/a/b/e");
  Fqn f4 = Fqn.fromString("/a");
  cache.move(f3, f4);
 

will result in:

 /a/b/d/c
 /a/e
 

No-op if the node to be moved is the root node.

Note: As of 3.0.0 and when using MVCC locking, more specific behaviour is defined as follows:

• A no-op if the node is moved unto itself. E.g., move(fqn, fqn.getParent()) will not do anything.
• If a target node does not exist it will be created silently, to be more consistent with other APIs such as put() on a nonexistent node.
• If the source node does not exist this is a no-op, to be more consistent with other APIs such as get() on a nonexistent node.

Parameters:

nodeToMove - the Fqn of the node to move.

newParent - new location under which to attach the node being moved.

Throws:

NodeNotExistsException - may throw one of these if the target node does not exist or if a different thread has moved this node elsewhere already.

IllegalStateException - if getCacheStatus() would not return CacheStatus.STARTED.

move

void move(String nodeToMove,
          String newParent)
          throws NodeNotExistsException

Convenience method that takes in string representations of Fqns. Otherwise identical to move(Fqn, Fqn)

Throws:

IllegalStateException - if getCacheStatus() would not return CacheStatus.STARTED.

NodeNotExistsException

getVersion

String getVersion()

Returns the version of the cache as a string.

Returns:

the version string of the cache.

See Also:

Version.printVersion()

getData

Map<K,V> getData(Fqn fqn)

Retrieves a defensively copied data map of the underlying node. A convenience method to retrieving a node and getting data from the node directly.

Parameters:

fqn -

Returns:

map of data, or an empty map

Throws:

CacheException

IllegalStateException - if getCacheStatus() would not return CacheStatus.STARTED.

getKeys

Set<K> getKeys(String fqn)

Convenience method that takes in a String represenation of the Fqn. Otherwise identical to getKeys(Fqn).

getKeys

Set<K> getKeys(Fqn fqn)

Returns a set of attribute keys for the Fqn. Returns null if the node is not found, otherwise a Set. The set is a copy of the actual keys for this node.

A convenience method to retrieving a node and getting keys from the node directly.

Parameters:

fqn - name of the node

Throws:

IllegalStateException - if getCacheStatus() would not return CacheStatus.STARTED.

clearData

void clearData(String fqn)

Convenience method that takes in a String represenation of the Fqn. Otherwise identical to clearData(Fqn).

Throws:

IllegalStateException - if getCacheStatus() would not return CacheStatus.STARTED.

clearData

void clearData(Fqn fqn)

Removes the keys and properties from a named node.

A convenience method to retrieving a node and getting keys from the node directly.

Parameters:

fqn - name of the node

Throws:

IllegalStateException - if getCacheStatus() would not return CacheStatus.STARTED.

startBatch

void startBatch()

Starts a batch. This is a lightweight batching mechanism that groups cache writes together and finally performs the write, persistence and/or replication when endBatch(boolean) is called rather than for each invocation on the cache.

Note that if there is an existing transaction in scope and the cache has been configured to use a JTA compliant transaction manager, calls to startBatch() and endBatch(boolean) are ignored and treated as no-ops.

Since:

3.0

See Also:

endBatch(boolean)

endBatch

void endBatch(boolean successful)

Ends an existing ongoing batch. A no-op if a batch has not been started yet.

Note that if there is an existing transaction in scope and the cache has been configured to use a JTA compliant transaction manager, calls to startBatch() and endBatch(boolean) are ignored and treated as no-ops.

Parameters:

successful - if true, changes made in the batch are committed. If false, they are discarded.

Since:

3.0

See Also:

startBatch()

addInterceptor

void addInterceptor(CommandInterceptor i,
                    int position)

Adds a custom interceptor to the interceptor chain, at specified position, where the first interceptor in the chain is at position 0 and the last one at getInterceptorChain().size() - 1.

Parameters:

i - the interceptor to add

position - the position to add the interceptor

Since:

3.0

addInterceptor

void addInterceptor(CommandInterceptor i,
                    Class<? extends CommandInterceptor> afterInterceptor)

Adds a custom interceptor to the interceptor chain, after an instance of the specified interceptor type. Throws a cache exception if it cannot find an interceptor of the specified type.

Parameters:

i - interceptor to add

afterInterceptor - interceptor type after which to place custom interceptor

Since:

3.0

removeInterceptor

void removeInterceptor(int position)

Removes the interceptor at a specified position, where the first interceptor in the chain is at position 0 and the last one at getInterceptorChain().size() - 1.

Parameters:

position - the position at which to remove an interceptor

Since:

3.0

removeInterceptor

void removeInterceptor(Class<? extends CommandInterceptor> interceptorType)

Removes the interceptor of specified type.

Parameters:

interceptorType - type of interceptor to remove

Since:

3.0