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

All Known Subinterfaces:
CacheSPI<K,V>
All Known Implementing Classes:
CacheInvocationDelegate

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

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(Object listener)
          Adds a CacheListener-annotated object to the entire cache.
 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 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.
 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<K,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<K,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.
 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 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<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
Throws:
IllegalStateException - if the cache is not in a started state

put

void put(String fqn,
         Map<K,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

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

    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.


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