@ThreadSafe public interface Cache<K,V> extends Lifecycle
Node
s.
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 Node
s, which contain data. Once references
to Node
s 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 trueFor 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 CacheListener s 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 CacheListener
s attached to the cache.List
of objects annotated as CacheListener
s 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.Region
boolean removeRegion(Fqn fqn)
fqn
- of the region to removevoid create() throws CacheException
create
in interface Lifecycle
CacheException
- if there are creation problemsvoid start() throws CacheException
start
in interface Lifecycle
CacheException
- 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
.NodeNotExistsException
String getVersion()
Version.printVersion()
Map<K,V> getData(Fqn fqn)
fqn
- CacheException
IllegalStateException
- 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.