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

All Known Subinterfaces:

CacheSPI<K,V>

All Known Implementing Classes:

CacheImpl

@ThreadSafe
public interface Cache<K,V>

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 = 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 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@jboss.org)

See Also:

Node, CacheFactory

Method Summary

void	addCacheListener(Fqn<?> region, java.lang.Object listener) Adds a @org.jboss.cache.notifications.annotation.CacheListener-annotated object to a given region.
void	addCacheListener(java.lang.Object listener) Adds a @org.jboss.cache.notifications.annotation.CacheListener-annotated object to the entire cache.
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	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.
java.util.Set<java.lang.Object>	getCacheListeners() Retrieves an immutable List of objects annotated as CacheListeners attached to the cache.
java.util.Set<java.lang.Object>	getCacheListeners(Fqn<?> region) Retrieves an immutable List of objects annotated as CacheListeners attached to a specific region.
CacheStatus	getCacheStatus() Gets where the cache currently is its lifecycle transitions.
Configuration	getConfiguration() Retrieves the configuration of this cache.
InvocationContext	getInvocationContext()
org.jgroups.Address	getLocalAddress() Returns the local address of this cache in a cluster, or null if running in local mode.
java.util.List<org.jgroups.Address>	getMembers() Returns a list of members in the cluster, or null if running in local mode.
Region	getRegion(Fqn<?> fqn, boolean createIfAbsent) Retrieves a Region for a given Fqn.
Node<K,V>	getRoot() Returns the root node of this cache.
java.lang.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.
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, java.util.Map<K,V> data) Copies all of the mappings from the specified map to a Node.
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.
void	removeCacheListener(Fqn<?> region, java.lang.Object listener) Removes a @org.jboss.cache.notifications.annotation.CacheListener-annotated object from a given region.
void	removeCacheListener(java.lang.Object listener) Removes a @org.jboss.cache.notifications.annotation.CacheListener-annotated object from the cache.
boolean	removeNode(Fqn<?> fqn) Removes a Node indicated by absolute 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	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(java.lang.Object listener)

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

Parameters:

listener - listener to add

addCacheListener

void addCacheListener(Fqn<?> region,
                      java.lang.Object listener)

Adds a @org.jboss.cache.notifications.annotation.CacheListener-annotated object to a given region. The object passed in needs to be properly annotated with the @org.jboss.cache.notifications.annotation.CacheListener annotation otherwise an IncorrectCacheListenerException will be thrown.

Parameters:

region - region to add listener to

listener - listener to add

removeCacheListener

void removeCacheListener(java.lang.Object listener)

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

Parameters:

listener - listener to remove

removeCacheListener

void removeCacheListener(Fqn<?> region,
                         java.lang.Object listener)

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

Parameters:

region - region from which to remove listener

listener - listener to remove

getCacheListeners

java.util.Set<java.lang.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.

getCacheListeners

java.util.Set<java.lang.Object> getCacheListeners(Fqn<?> region)

Retrieves an immutable List of objects annotated as CacheListeners attached to a specific region.

Returns:

an immutable List of objects annotated as CacheListeners attached to a specific region.

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.

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 or invalidation to prevent any blocking.
• 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.

put

void put(Fqn<?> fqn,
         java.util.Map<K,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

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

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

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.

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

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.

Throws:

java.lang.UnsupportedOperationException - if the region cannot be defined.

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.

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.

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.

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().

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.

See Also:

InvocationContext

setInvocationContext

void setInvocationContext(InvocationContext ctx)

Sets the passed in InvocationContext as current.

Parameters:

ctx - invocation context to use

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

java.util.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.

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.

getVersion

java.lang.String getVersion()

Returns the version of the cache as a string.

Returns:

the version string of the cache.

See Also:

Version.printVersion()