org.jboss.cache.invocation
Class CacheInvocationDelegate<K,V>

java.lang.Object
  org.jboss.cache.invocation.AbstractInvocationDelegate
      org.jboss.cache.invocation.CacheInvocationDelegate<K,V>

All Implemented Interfaces:

Cache<K,V>, CacheSPI<K,V>, Lifecycle

public class CacheInvocationDelegate<K,V>
extends AbstractInvocationDelegate
implements CacheSPI<K,V>

The delegate that users (and ChainedInterceptor authors) interact with when they create a cache by using a cache factory. This wrapper delegates calls down the interceptor chain.

Since:

2.1.0

Author:

Manik Surtani (manik AT jboss DOT org)

Field Summary

Fields inherited from class org.jboss.cache.invocation.AbstractInvocationDelegate

componentRegistry, configuration, invocationContextContainer, invoker, originLocal

Constructor Summary

CacheInvocationDelegate()

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.
protected void	cacheStatusCheck(InvocationContext ctx)
void	clearData(Fqn fqn) Removes the keys and properties from a named node.
void	clearData(String fqn) Removes the keys and properties from a node.
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.
boolean	exists(Fqn fqn) Helper method that does a peek and ensures that the result of the peek is not null.
boolean	exists(String fqn) A convenience method that takes a String representation of an Fqn.
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.
BuddyManager	getBuddyManager() Retrieves the current BuddyManager instance associated with the current Cache instance.
Set<Object>	getCacheListeners() Retrieves an immutable List of objects annotated as CacheListeners attached to the cache.
CacheLoaderManager	getCacheLoaderManager() Retrieves the current CacheCacheLoaderManager instance associated with the current Cache instance.
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.
String	getClusterName()
ComponentRegistry	getComponentRegistry() Returns the component registry associated with this cache instance.
Configuration	getConfiguration() Retrieves the configuration of this cache.
GlobalTransaction	getCurrentTransaction() Returns the transaction associated with the current thread.
GlobalTransaction	getCurrentTransaction(Transaction tx, boolean createIfNotExists) Returns the global transaction for this local transaction.
Map<K,V>	getData(Fqn fqn) Retrieves a defensively copied data map of the underlying node.
DataContainer	getDataContainer()
List<CommandInterceptor>	getInterceptorChain() Retrieves the current Interceptor chain.
Set<Fqn>	getInternalFqns() Returns a Set of Fqns of the topmost node of internal regions that should not included in standard state transfers.
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.
Marshaller	getMarshaller() Retrieves an instance of a Marshaller, which is capable of converting Java objects to bytestreams and back in an efficient manner, which is also interoperable with bytestreams produced/consumed by other versions of JBoss Cache.
List<org.jgroups.Address>	getMembers() Returns a list of members in the cluster, or null if running in local mode.
NodeSPI<K,V>	getNode(Fqn fqn) A convenience method to retrieve a node directly from the cache.
NodeSPI<K,V>	getNode(String fqn) Convenience method that takes a string representation of an Fqn.
Notifier	getNotifier() Retrieves the current Notifier instance associated with the current Cache instance.
int	getNumberOfAttributes()
int	getNumberOfLocksHeld()
int	getNumberOfNodes()
Region	getRegion(Fqn fqn, boolean createIfAbsent) Retrieves a Region for a given Fqn.
RegionManager	getRegionManager() Retrieves the current RegionManager instance associated with the current Cache instance.
NodeSPI<K,V>	getRoot() Returns the root node of this cache.
RPCManager	getRPCManager() Gets a handle of the RPC manager.
StateTransferManager	getStateTransferManager() Retrieves the current StateTransferManager instance associated with the current Cache instance.
TransactionManager	getTransactionManager() Retrieves a reference to a running TransactionManager, if one is configured.
TransactionTable	getTransactionTable() Retrieves the current TransactionTable instance associated with the current Cache instance.
String	getVersion() Returns the version of the cache as a string.
GravitateResult	gravitateData(Fqn fqn, boolean searchBuddyBackupSubtrees, InvocationContext ctx) Used with buddy replication's data gravitation interceptor.
void	initialize(StateTransferManager stateTransferManager, CacheLoaderManager cacheLoaderManager, Notifier notifier, TransactionManager transactionManager, BuddyManager buddyManager, TransactionTable transactionTable, RPCManager rpcManager, RegionManager regionManager, Marshaller marshaller, CommandsFactory commandsFactory, DataContainer dataContainer, MVCCNodeHelper mvccHelper, BatchContainer batchContainer)
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.
NodeSPI<K,V>	peek(Fqn fqn, boolean includeDeletedNodes) Returns a node without accessing the interceptor chain.
NodeSPI<K,V>	peek(Fqn fqn, boolean includeDeletedNodes, boolean includeInvalidNodes) Returns a node without accessing the interceptor chain, optionally returning nodes that are marked as invalid (Node.isValid() == false).
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.
String	toString()

Methods inherited from class org.jboss.cache.invocation.AbstractInvocationDelegate

assertIsConstructed, initialize

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CacheInvocationDelegate

public CacheInvocationDelegate()

Method Detail

initialize

public void initialize(StateTransferManager stateTransferManager,
                       CacheLoaderManager cacheLoaderManager,
                       Notifier notifier,
                       TransactionManager transactionManager,
                       BuddyManager buddyManager,
                       TransactionTable transactionTable,
                       RPCManager rpcManager,
                       RegionManager regionManager,
                       Marshaller marshaller,
                       CommandsFactory commandsFactory,
                       DataContainer dataContainer,
                       MVCCNodeHelper mvccHelper,
                       BatchContainer batchContainer)

toString

public String toString()

Overrides:

toString in class Object

getConfiguration

public Configuration getConfiguration()

Description copied from interface: Cache

Retrieves the configuration of this cache.

Specified by:

getConfiguration in interface Cache<K,V>

Returns:

the configuration.

getRoot

public NodeSPI<K,V> getRoot()

Description copied from interface: Cache

Returns the root node of this cache.

Specified by:

getRoot in interface Cache<K,V>

Specified by:

getRoot in interface CacheSPI<K,V>

Returns:

the root node

getTransactionManager

public TransactionManager getTransactionManager()

Description copied from interface: CacheSPI

Retrieves a reference to a running TransactionManager, if one is configured.

From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the Inject annotation.

Specified by:

getTransactionManager in interface CacheSPI<K,V>

Returns:

a TransactionManager

addInterceptor

public void addInterceptor(CommandInterceptor i,
                           int position)

Description copied from interface: Cache

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.

Specified by:

addInterceptor in interface Cache<K,V>

Parameters:

i - the interceptor to add

position - the position to add the interceptor

addInterceptor

public void addInterceptor(CommandInterceptor i,
                           Class<? extends CommandInterceptor> afterInterceptor)

Description copied from interface: Cache

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.

Specified by:

addInterceptor in interface Cache<K,V>

Parameters:

i - interceptor to add

afterInterceptor - interceptor type after which to place custom interceptor

getInterceptorChain

public List<CommandInterceptor> getInterceptorChain()

Description copied from interface: CacheSPI

Retrieves the current Interceptor chain.

From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the Inject annotation.

Specified by:

getInterceptorChain in interface CacheSPI<K,V>

Returns:

an immutable List of CommandInterceptors configured for this cache, or null if create() has not been invoked and the interceptors thus do not exist.

removeInterceptor

public void removeInterceptor(int position)

Description copied from interface: Cache

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.

Specified by:

removeInterceptor in interface Cache<K,V>

Parameters:

position - the position at which to remove an interceptor

removeInterceptor

public void removeInterceptor(Class<? extends CommandInterceptor> interceptorType)

Description copied from interface: Cache

Removes the interceptor of specified type.

Specified by:

removeInterceptor in interface Cache<K,V>

Parameters:

interceptorType - type of interceptor to remove

getCacheLoaderManager

public CacheLoaderManager getCacheLoaderManager()

Description copied from interface: CacheSPI

Retrieves the current CacheCacheLoaderManager instance associated with the current Cache instance.

From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the Inject annotation.

Specified by:

getCacheLoaderManager in interface CacheSPI<K,V>

Returns:

Retrieves a reference to the currently configured CacheLoaderManager if one or more cache loaders are configured, null otherwise.

getBuddyManager

public BuddyManager getBuddyManager()

Description copied from interface: CacheSPI

Retrieves the current BuddyManager instance associated with the current Cache instance.

From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the Inject annotation.

Specified by:

getBuddyManager in interface CacheSPI<K,V>

Returns:

an instance of BuddyManager if buddy replication is enabled, null otherwise.

getTransactionTable

public TransactionTable getTransactionTable()

Description copied from interface: CacheSPI

Retrieves the current TransactionTable instance associated with the current Cache instance.

From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the Inject annotation.

Specified by:

getTransactionTable in interface CacheSPI<K,V>

Returns:

the current TransactionTable

getRPCManager

public RPCManager getRPCManager()

Description copied from interface: CacheSPI

Gets a handle of the RPC manager.

From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the Inject annotation.

Specified by:

getRPCManager in interface CacheSPI<K,V>

Returns:

the RPCManager configured.

getStateTransferManager

public StateTransferManager getStateTransferManager()

Description copied from interface: CacheSPI

Retrieves the current StateTransferManager instance associated with the current Cache instance.

From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the Inject annotation.

Specified by:

getStateTransferManager in interface CacheSPI<K,V>

Returns:

the current StateTransferManager

getClusterName

public String getClusterName()

Specified by:

getClusterName in interface CacheSPI<K,V>

Returns:

the name of the cluster. Null if running in local mode.

getNumberOfAttributes

public int getNumberOfAttributes()

Specified by:

getNumberOfAttributes in interface CacheSPI<K,V>

Returns:

the number of attributes in the cache.

getNumberOfNodes

public int getNumberOfNodes()

Specified by:

getNumberOfNodes in interface CacheSPI<K,V>

Returns:

the number of nodes in the cache.

getRegionManager

public RegionManager getRegionManager()

Description copied from interface: CacheSPI

Retrieves the current RegionManager instance associated with the current Cache instance.

From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the Inject annotation.

Specified by:

getRegionManager in interface CacheSPI<K,V>

Returns:

the RegionManager

getCurrentTransaction

public GlobalTransaction getCurrentTransaction(Transaction tx,
                                               boolean createIfNotExists)

Description copied from interface: CacheSPI

Returns the global transaction for this local transaction. Optionally creates a new global transaction if it does not exist.

Specified by:

getCurrentTransaction in interface CacheSPI<K,V>

Parameters:

tx - the current transaction

createIfNotExists - if true creates a new transaction if none exists

Returns:

a GlobalTransaction

getCurrentTransaction

public GlobalTransaction getCurrentTransaction()

Description copied from interface: CacheSPI

Returns the transaction associated with the current thread. If a local transaction exists, but doesn't yet have a mapping to a GlobalTransaction, a new GlobalTransaction will be created and mapped to the local transaction. Note that if a local transaction exists, but is not ACTIVE or PREPARING, null is returned.

Specified by:

getCurrentTransaction in interface CacheSPI<K,V>

Returns:

A GlobalTransaction, or null if no (local) transaction was associated with the current thread

getInternalFqns

public Set<Fqn> getInternalFqns()

Description copied from interface: CacheSPI

Returns a Set of Fqns of the topmost node of internal regions that should not included in standard state transfers. Will include BuddyManager.BUDDY_BACKUP_SUBTREE if buddy replication is enabled.

Specified by:

getInternalFqns in interface CacheSPI<K,V>

Returns:

an unmodifiable Set. Will not return null.

getNumberOfLocksHeld

public int getNumberOfLocksHeld()

Specified by:

getNumberOfLocksHeld in interface CacheSPI<K,V>

exists

public boolean exists(String fqn)

Description copied from interface: CacheSPI

A convenience method that takes a String representation of an Fqn. Otherwise identical to CacheSPI.exists(Fqn). Note that this call works directly on the cache data structure and will not pass through the interceptor chain. Hence node locking, cache loading or activation does not take place, and so the results of this call should not be treated as definitive.

Specified by:

exists in interface CacheSPI<K,V>

exists

public boolean exists(Fqn fqn)

Description copied from interface: CacheSPI

Helper method that does a peek and ensures that the result of the peek is not null. Note that this call works directly on the cache data structure and will not pass through the interceptor chain. Hence node locking, cache loading or activation does not take place, and so the results of this call should not be treated as definitive.

Specified by:

exists in interface CacheSPI<K,V>

Parameters:

fqn - Fqn to peek

Returns:

true if the peek returns a non-null value.

getNotifier

public Notifier getNotifier()

Description copied from interface: CacheSPI

Retrieves the current Notifier instance associated with the current Cache instance.

From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the Inject annotation.

Specified by:

getNotifier in interface CacheSPI<K,V>

Returns:

the notifier attached with this instance of the cache. See Notifier, a class that is responsible for emitting notifications to registered CacheListeners.

getMarshaller

public Marshaller getMarshaller()

Description copied from interface: CacheSPI

Retrieves an instance of a Marshaller, which is capable of converting Java objects to bytestreams and back in an efficient manner, which is also interoperable with bytestreams produced/consumed by other versions of JBoss Cache.

The use of this marshaller is the recommended way of creating efficient, compatible, byte streams from objects.

From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the Inject annotation.

Specified by:

getMarshaller in interface CacheSPI<K,V>

Returns:

an instance of Marshaller

gravitateData

public GravitateResult gravitateData(Fqn fqn,
                                     boolean searchBuddyBackupSubtrees,
                                     InvocationContext ctx)

Description copied from interface: CacheSPI

Used with buddy replication's data gravitation interceptor. If marshalling is necessary, ensure that the cache is configured to use Configuration.useRegionBasedMarshalling and the Region pertaining to the Fqn passed in is activated, and has an appropriate ClassLoader.

Specified by:

gravitateData in interface CacheSPI<K,V>

Parameters:

fqn - the fqn to gravitate

searchBuddyBackupSubtrees - if true, buddy backup subtrees are searched and if false, they are not.

Returns:

a GravitateResult which contains the data for the gravitation

peek

public NodeSPI<K,V> peek(Fqn fqn,
                         boolean includeDeletedNodes,
                         boolean includeInvalidNodes)

Description copied from interface: CacheSPI

Returns a node without accessing the interceptor chain, optionally returning nodes that are marked as invalid (Node.isValid() == false). Note that this call works directly on the cache data structure and will not pass through the interceptor chain. Hence node locking, cache loading or activation does not take place, and so the results of this call should not be treated as definitive. Concurrent node removal, passivation, etc. may affect the results of this call.

Specified by:

peek in interface CacheSPI<K,V>

Parameters:

fqn - the Fqn to look up.

includeDeletedNodes - if you intend to see nodes marked as deleted within the current tx, set this to true

includeInvalidNodes - if true, nodes marked as being invalid are also returned.

Returns:

a node if one exists or null

peek

public NodeSPI<K,V> peek(Fqn fqn,
                         boolean includeDeletedNodes)

Description copied from interface: CacheSPI

Returns a node without accessing the interceptor chain. Does not return any nodes marked as invalid. Note that this call works directly on the cache data structure and will not pass through the interceptor chain. Hence node locking, cache loading or activation does not take place, and so the results of this call should not be treated as definitive. Concurrent node removal, passivation, etc. may affect the results of this call.

Specified by:

peek in interface CacheSPI<K,V>

Parameters:

fqn - the Fqn to look up.

includeDeletedNodes - if you intend to see nodes marked as deleted within the current tx, set this to true

Returns:

a node if one exists or null

addCacheListener

public void addCacheListener(Object listener)

Description copied from interface: Cache

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.

Specified by:

addCacheListener in interface Cache<K,V>

Parameters:

listener - listener to add

removeCacheListener

public void removeCacheListener(Object listener)

Description copied from interface: Cache

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.

Specified by:

removeCacheListener in interface Cache<K,V>

Parameters:

listener - listener to remove

getCacheListeners

public Set<Object> getCacheListeners()

Description copied from interface: Cache

Retrieves an immutable List of objects annotated as CacheListeners attached to the cache.

Specified by:

getCacheListeners in interface Cache<K,V>

Returns:

an immutable List of objects annotated as CacheListeners attached to the cache.

create

public void create()
            throws CacheException

Description copied from interface: Cache

Lifecycle method that initializes configuration state, the root node, etc.

Specified by:

create in interface Cache<K,V>

Specified by:

create in interface Lifecycle

Throws:

CacheException - if there are creation problems

start

public void start()
           throws CacheException

Description copied from interface: Cache

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 Cache<K,V>

Specified by:

start in interface Lifecycle

Throws:

CacheException - if there are startup problems

stop

public void stop()

Description copied from interface: Cache

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 Cache<K,V>

Specified by:

stop in interface Lifecycle

destroy

public void destroy()

Description copied from interface: Cache

Lifecycle method that destroys the cache and removes any interceptors/configuration elements. Cache can then be restarted (potentially after reconfiguring) using Cache.create() and Cache.start().

Specified by:

destroy in interface Cache<K,V>

Specified by:

destroy in interface Lifecycle

getCacheStatus

public CacheStatus getCacheStatus()

Description copied from interface: Cache

Gets where the cache currently is its lifecycle transitions.

Specified by:

getCacheStatus in interface Cache<K,V>

Returns:

the CacheStatus. Will not return null.

getInvocationContext

public InvocationContext getInvocationContext()

Specified by:

getInvocationContext in interface Cache<K,V>

Returns:

the current invocation context for the current invocation and cache instance.

setInvocationContext

public void setInvocationContext(InvocationContext ctx)

Description copied from interface: Cache

Sets the passed in InvocationContext as current.

Specified by:

setInvocationContext in interface Cache<K,V>

Parameters:

ctx - invocation context to use

getLocalAddress

public org.jgroups.Address getLocalAddress()

Description copied from interface: Cache

Returns the local address of this cache in a cluster, or null if running in local mode.

Specified by:

getLocalAddress in interface Cache<K,V>

Returns:

the local address of this cache in a cluster, or null if running in local mode.

getMembers

public List<org.jgroups.Address> getMembers()

Description copied from interface: Cache

Returns a list of members in the cluster, or null if running in local mode.

Specified by:

getMembers in interface Cache<K,V>

Returns:

a List of members in the cluster, or null if running in local mode.

getVersion

public String getVersion()

Description copied from interface: Cache

Returns the version of the cache as a string.

Specified by:

getVersion in interface Cache<K,V>

Returns:

the version string of the cache.

See Also:

Version.printVersion()

move

public void move(Fqn nodeToMove,
                 Fqn newParent)
          throws NodeNotExistsException

Description copied from interface: Cache

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:

• A no-op if the node is moved unto itself. E.g., move(fqn, fqn.getParent()) will not do anything.
• If a target node does not exist it will be created silently, to be more consistent with other APIs such as put() on a nonexistent node.
• If the source node does not exist this is a no-op, to be more consistent with other APIs such as get() on a nonexistent node.

Specified by:

move in interface Cache<K,V>

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.

move

public void move(String nodeToMove,
                 String newParent)
          throws NodeNotExistsException

Description copied from interface: Cache

Convenience method that takes in string representations of Fqns. Otherwise identical to Cache.move(Fqn, Fqn)

Specified by:

move in interface Cache<K,V>

Throws:

NodeNotExistsException

removeRegion

public boolean removeRegion(Fqn fqn)

Description copied from interface: Cache

Removes a region denoted by the Fqn passed in.

Specified by:

removeRegion in interface Cache<K,V>

Parameters:

fqn - of the region to remove

Returns:

true if a region did exist and was removed; false otherwise.

getRegion

public Region getRegion(Fqn fqn,
                        boolean createIfAbsent)

Description copied from interface: Cache

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.

Specified by:

getRegion in interface Cache<K,V>

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

evict

public void evict(Fqn fqn,
                  boolean recursive)

Description copied from interface: Cache

Eviction call that evicts the specified Node from memory.

Specified by:

evict in interface Cache<K,V>

Parameters:

fqn - absolute Fqn to the Node to be evicted.

recursive - evicts children as well

evict

public void evict(Fqn fqn)

Description copied from interface: Cache

Eviction call that evicts the specified Node from memory. Not recursive.

Specified by:

evict in interface Cache<K,V>

Parameters:

fqn - absolute Fqn to the Node to be evicted.

get

public V get(Fqn fqn,
             K key)

Description copied from interface: Cache

Convenience method that allows for direct access to the data in a Node.

Specified by:

get in interface Cache<K,V>

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.

get

public V get(String fqn,
             K key)

Description copied from interface: Cache

Convenience method that takes a string representation of an Fqn. Otherwise identical to Cache.get(Fqn, Object)

Specified by:

get in interface Cache<K,V>

Parameters:

fqn - string representation of the Fqn to retrieve

key - key to fetch

Returns:

value, or null if the fqn does not exist.

removeNode

public boolean removeNode(Fqn fqn)

Description copied from interface: Cache

Removes a Node indicated by absolute Fqn.

Specified by:

removeNode in interface Cache<K,V>

Parameters:

fqn - Node to remove

Returns:

true if the node was removed, false if the node was not found

removeNode

public boolean removeNode(String fqn)

Description copied from interface: Cache

Convenience method that takes a string representation of an Fqn. Otherwise identical to Cache.removeNode(Fqn)

Specified by:

removeNode in interface Cache<K,V>

Parameters:

fqn - string representation of the Fqn to retrieve

Returns:

true if the node was found and removed, false otherwise

getNode

public NodeSPI<K,V> getNode(Fqn fqn)

Description copied from interface: Cache

A convenience method to retrieve a node directly from the cache. Equivalent to calling cache.getRoot().getChild(fqn).

Specified by:

getNode in interface Cache<K,V>

Specified by:

getNode in interface CacheSPI<K,V>

Parameters:

fqn - fqn of the node to retrieve

Returns:

a Node object, or a null if the node does not exist.

getNode

public NodeSPI<K,V> getNode(String fqn)

Description copied from interface: Cache

Convenience method that takes a string representation of an Fqn. Otherwise identical to Cache.getNode(Fqn)

Specified by:

getNode in interface Cache<K,V>

Specified by:

getNode in interface CacheSPI<K,V>

Parameters:

fqn - string representation of the Fqn to retrieve

Returns:

node, or null if the node does not exist

remove

public V remove(Fqn fqn,
                K key)
         throws CacheException

Description copied from interface: Cache

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.

Specified by:

remove in interface Cache<K,V>

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:

CacheException

remove

public V remove(String fqn,
                K key)

Description copied from interface: Cache

Convenience method that takes a string representation of an Fqn. Otherwise identical to Cache.remove(Fqn, Object)

Specified by:

remove in interface Cache<K,V>

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

put

public void put(Fqn fqn,
                Map<? extends K,? extends V> data)

Description copied from interface: Cache

Copies all of the mappings from the specified map to a Node.

Specified by:

put in interface Cache<K,V>

Parameters:

fqn - absolute Fqn to the Node to copy the data to

data - mappings to copy

put

public void put(String fqn,
                Map<? extends K,? extends V> data)

Description copied from interface: Cache

Convenience method that takes a string representation of an Fqn. Otherwise identical to Cache.put(Fqn, java.util.Map)

Specified by:

put in interface Cache<K,V>

Parameters:

fqn - String representation of the Fqn

data - data map to insert

putForExternalRead

public void putForExternalRead(Fqn fqn,
                               K key,
                               V value)

Description copied from interface: Cache

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 to prevent any blocking.
• invalidation does not take place.
• 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.

Specified by:

putForExternalRead in interface Cache<K,V>

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

public V put(Fqn fqn,
             K key,
             V value)

Description copied from interface: Cache

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.

Specified by:

put in interface Cache<K,V>

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.

put

public V put(String fqn,
             K key,
             V value)

Description copied from interface: Cache

Convenience method that takes a string representation of an Fqn. Otherwise identical to Cache.put(Fqn, Object, Object)

Specified by:

put in interface Cache<K,V>

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.

getData

public Map<K,V> getData(Fqn fqn)

Description copied from interface: Cache

Retrieves a defensively copied data map of the underlying node. A convenience method to retrieving a node and getting data from the node directly.

Specified by:

getData in interface Cache<K,V>

Returns:

map of data, or an empty map

getKeys

public Set<K> getKeys(String fqn)

Description copied from interface: Cache

Convenience method that takes in a String represenation of the Fqn. Otherwise identical to Cache.getKeys(Fqn).

Specified by:

getKeys in interface Cache<K,V>

getKeys

public Set<K> getKeys(Fqn fqn)

Description copied from interface: Cache

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.

Specified by:

getKeys in interface Cache<K,V>

Parameters:

fqn - name of the node

clearData

public void clearData(String fqn)
               throws CacheException

Removes the keys and properties from a node.

Specified by:

clearData in interface Cache<K,V>

Throws:

CacheException

clearData

public void clearData(Fqn fqn)

Removes the keys and properties from a named node.

Specified by:

clearData in interface Cache<K,V>

Parameters:

fqn - name of the node

startBatch

public void startBatch()

Description copied from interface: Cache

Starts a batch. This is a lightweight batching mechanism that groups cache writes together and finally performs the write, persistence and/or replication when Cache.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 Cache.startBatch() and Cache.endBatch(boolean) are ignored and treated as no-ops.

Specified by:

startBatch in interface Cache<K,V>

See Also:

Cache.endBatch(boolean)

endBatch

public void endBatch(boolean successful)

Description copied from interface: Cache

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 Cache.startBatch() and Cache.endBatch(boolean) are ignored and treated as no-ops.

Specified by:

endBatch in interface Cache<K,V>

Parameters:

successful - if true, changes made in the batch are committed. If false, they are discarded.

See Also:

Cache.startBatch()

isLeaf

public boolean isLeaf(String fqn)
               throws NodeNotExistsException

Description copied from interface: Cache

Tests if a node is a leaf, i.e., doesn't have any children

Specified by:

isLeaf in interface Cache<K,V>

Parameters:

fqn - fqn to test

Returns:

true if it is a leaf, false otherwise

Throws:

NodeNotExistsException

isLeaf

public boolean isLeaf(Fqn fqn)
               throws NodeNotExistsException

Description copied from interface: Cache

Tests if a node is a leaf, i.e., doesn't have any children

Specified by:

isLeaf in interface Cache<K,V>

Parameters:

fqn - fqn to test

Returns:

true if it is a leaf, false otherwise

Throws:

NodeNotExistsException

getChildrenNames

public Set<Object> getChildrenNames(Fqn fqn)

Description copied from interface: Cache

Returns all children of a given node. Returns an empty set if there are no children. The set is unmodifiable.

Specified by:

getChildrenNames in interface Cache<K,V>

Parameters:

fqn - The fully qualified name of the node

Returns:

Set an unmodifiable set of children names, Object.

getChildrenNames

public Set<String> getChildrenNames(String fqn)

Description copied from interface: Cache

Convenience method that takes a String representation of an Fqn. Otherwise identical to Cache.getChildrenNames(Fqn)

Specified by:

getChildrenNames in interface Cache<K,V>

Parameters:

fqn - as a string

Returns:

Set an unmodifiable set of children names, Object.

getComponentRegistry

public ComponentRegistry getComponentRegistry()

Description copied from interface: CacheSPI

Returns the component registry associated with this cache instance.

Specified by:

getComponentRegistry in interface CacheSPI<K,V>

See Also:

ComponentRegistry

getDataContainer

public DataContainer getDataContainer()

cacheStatusCheck

protected void cacheStatusCheck(InvocationContext ctx)