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.

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 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. 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:

    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


    Copyright © 2009 JBoss, a division of Red Hat. All Rights Reserved.