@ThreadSafe public interface Cache<K,V> extends Lifecycle
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.
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.Node,
CacheFactory| Modifier and Type | Method and Description |
|---|---|
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)
|
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)
|
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.
|
Configuration getConfiguration()
void addCacheListener(Object listener)
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.listener - listener to addvoid removeCacheListener(Object listener)
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.listener - listener to removeSet<Object> getCacheListeners()
List of objects annotated as CacheListeners attached to the cache.List of objects annotated as CacheListeners attached to the cache.V put(Fqn fqn, K key, V value)
Node in this cache.
If the Node previously contained a mapping for this key, the old value is replaced by the specified value.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.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.IllegalStateException - if the cache is not in a started state.V put(String fqn, K key, V value)
put(Fqn, Object, Object)fqn - String representation of the Fqnkey - key with which the specified value is to be associated.value - value to be associated with the specified key.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.IllegalStateException - if the cache is not in a started statevoid putForExternalRead(Fqn fqn, K key, V value)
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.IllegalStateException - if getCacheStatus() would not return CacheStatus.STARTED.void put(Fqn fqn, Map<? extends K,? extends V> data)
Node.fqn - absolute Fqn to the Node to copy the data todata - mappings to copyIllegalStateException - if the cache is not in a started statevoid put(String fqn, Map<? extends K,? extends V> data)
put(Fqn, java.util.Map)fqn - String representation of the Fqndata - data map to insertIllegalStateException - if the cache is not in a started stateV remove(Fqn fqn, K key)
null if the Node contained no mapping for this key.fqn - absolute Fqn to the Node to be accessed.key - key whose mapping is to be removed from the NodeIllegalStateException - if the cache is not in a started stateV remove(String fqn, K key)
remove(Fqn, Object)fqn - string representation of the Fqn to retrievekey - key to removeIllegalStateException - if the cache is not in a started stateboolean removeNode(Fqn fqn)
fqn - Node to removeIllegalStateException - if the cache is not in a started stateboolean removeNode(String fqn)
removeNode(Fqn)fqn - string representation of the Fqn to retrieveIllegalStateException - if the cache is not in a started stateNode<K,V> getNode(Fqn fqn)
fqn - fqn of the node to retrieveIllegalStateException - if the cache is not in a started stateNode<K,V> getNode(String fqn)
getNode(Fqn)fqn - string representation of the Fqn to retrieveIllegalStateException - if the cache is not in a started stateSet<Object> getChildrenNames(Fqn fqn)
fqn - The fully qualified name of the nodeSet<String> getChildrenNames(String fqn)
getChildrenNames(Fqn)fqn - as a stringboolean isLeaf(Fqn fqn)
fqn - fqn to testboolean isLeaf(String fqn)
fqn - fqn to testV get(Fqn fqn, K key)
Node.fqn - absolute Fqn to the Node to be accessed.key - key under which value is to be retrieved.Node denoted by specified Fqn.IllegalStateException - if the cache is not in a started stateV get(String fqn, K key)
get(Fqn, Object)fqn - string representation of the Fqn to retrievekey - key to fetchIllegalStateException - if the cache is not in a started statevoid evict(Fqn fqn, boolean recursive)
Node from memory.fqn - absolute Fqn to the Node to be evicted.recursive - evicts children as wellIllegalStateException - if the cache is not in a started statevoid evict(Fqn fqn)
Node from memory. Not recursive.fqn - absolute Fqn to the Node to be evicted.IllegalStateException - if the cache is not in a started stateRegion getRegion(Fqn fqn, boolean createIfAbsent)
Region for a given Fqn. If the region does not exist,
and fqn - Fqn that is contained in a region.createIfAbsent - If true, will create a new associated region if not found.Regionboolean removeRegion(Fqn fqn)
fqn - of the region to removevoid create()
throws CacheException
create in interface LifecycleCacheException - if there are creation problemsvoid start()
throws CacheException
start in interface LifecycleCacheException - if there are startup problemsvoid stop()
void destroy()
CacheStatus getCacheStatus()
null.InvocationContext getInvocationContext()
IllegalStateException - if the cache has been destroyed.void setInvocationContext(InvocationContext ctx)
InvocationContext as current.ctx - invocation context to useIllegalStateException - if the cache has been destroyed.org.jgroups.Address getLocalAddress()
null
if running in local mode.null
if running in local mode.List<org.jgroups.Address> getMembers()
null
if running in local mode.List of members in the cluster, or null
if running in local mode.void move(Fqn nodeToMove, Fqn newParent) throws NodeNotExistsException
/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/eand 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/eNo-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:
nodeToMove - the Fqn of the node to move.newParent - new location under which to attach the node being moved.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.void move(String nodeToMove, String newParent) throws NodeNotExistsException
move(Fqn, Fqn)IllegalStateException - if getCacheStatus() would not return CacheStatus.STARTED.NodeNotExistsExceptionString getVersion()
Version.printVersion()Map<K,V> getData(Fqn fqn)
fqn - CacheExceptionIllegalStateException - if getCacheStatus() would not return CacheStatus.STARTED.Set<K> getKeys(String fqn)
getKeys(Fqn).Set<K> getKeys(Fqn fqn)
fqn - name of the nodeIllegalStateException - if getCacheStatus() would not return CacheStatus.STARTED.void clearData(String fqn)
clearData(Fqn).IllegalStateException - if getCacheStatus() would not return CacheStatus.STARTED.void clearData(Fqn fqn)
fqn - name of the nodeIllegalStateException - if getCacheStatus() would not return CacheStatus.STARTED.void startBatch()
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.
endBatch(boolean)void endBatch(boolean successful)
startBatch() and endBatch(boolean) are ignored and treated as no-ops.
successful - if true, changes made in the batch are committed. If false, they are discarded.startBatch()void addInterceptor(CommandInterceptor i, int position)
i - the interceptor to addposition - the position to add the interceptorvoid addInterceptor(CommandInterceptor i, Class<? extends CommandInterceptor> afterInterceptor)
i - interceptor to addafterInterceptor - interceptor type after which to place custom interceptorvoid removeInterceptor(int position)
position - the position at which to remove an interceptorvoid removeInterceptor(Class<? extends CommandInterceptor> interceptorType)
interceptorType - type of interceptor to removeCopyright © 2012 JBoss, a division of Red Hat. All Rights Reserved.