|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
@ThreadSafe public interface Cache<K,V>
Interface for a Cache where data mappings are grouped and stored in a tree data
structure consisting of Node
s.
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 = DefaultCacheFactory.getInstance().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
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 CacheListener s attached to the cache. |
CacheStatus |
getCacheStatus()
Gets where the cache currently is its lifecycle transitions. |
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. |
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 |
---|
Configuration getConfiguration()
Node<K,V> getRoot()
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 copy
IllegalStateException
- 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 insert
IllegalStateException
- 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 Node
IllegalStateException
- 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 remove
IllegalStateException
- if the cache is not in a started stateboolean removeNode(Fqn fqn)
Node
indicated by absolute Fqn
.
fqn
- Node
to remove
IllegalStateException
- if the cache is not in a started stateboolean removeNode(String fqn)
removeNode(Fqn)
fqn
- string representation of the Fqn to retrieve
IllegalStateException
- if the cache is not in a started stateNode<K,V> getNode(Fqn fqn)
fqn
- fqn of the node to retrieve
IllegalStateException
- if the cache is not in a started stateNode<K,V> getNode(String fqn)
getNode(Fqn)
fqn
- string representation of the Fqn to retrieve
IllegalStateException
- if the cache is not in a started stateV 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 fetch
IllegalStateException
- 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 well
IllegalStateException
- 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 remove
void 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()
stop
in interface Lifecycle
void destroy()
create()
and start()
.
destroy
in interface Lifecycle
CacheStatus getCacheStatus()
null
.InvocationContext getInvocationContext()
IllegalStateException
- if the cache has been destroyed.void setInvocationContext(InvocationContext ctx)
InvocationContext
as current.
ctx
- invocation context to use
IllegalStateException
- 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 node
IllegalStateException
- 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 node
IllegalStateException
- 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 remove
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |