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

All Superinterfaces:
Cache<K,V>
All Known Implementing Classes:
CacheInvocationDelegate, RemoteCacheInvocationDelegate

@ThreadSafe
public interface CacheSPI<K,V>
extends Cache<K,V>

A more detailed interface to Cache, which is used when writing plugins for or extending JBoss Cache. A reference to this interface should only be obtained when it is passed in to your code, for example when you write an Interceptor or CacheLoader.

You should NEVER attempt to directly cast a Cache instance to this interface. In future, the implementation may not allow it.

This interface contains overridden method signatures of some methods from Cache, overridden to ensure return types of Node are replaced with NodeSPI.

Since:
2.0.0
Author:
Manik Surtani (manik@jboss.org)
See Also:
NodeSPI, Cache, CacheLoader, Interceptor

Method Summary
 void addInterceptor(Interceptor i, Class<? extends Interceptor> afterInterceptor)
          Adds a custom interceptor to the interceptor chain, after an instance of the specified interceptor type.
 void addInterceptor(Interceptor 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.
 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.
 BuddyManager getBuddyManager()
          Retrieves the current BuddyManager instance associated with the current Cache instance.
 CacheLoaderManager getCacheLoaderManager()
          Retrieves the current CacheCacheLoaderManager instance associated with the current Cache instance.
 String getClusterName()
           
 GlobalTransaction getCurrentTransaction()
          Returns the transaction associated with the current thread.
 GlobalTransaction getCurrentTransaction(Transaction tx, boolean createIfNotExists)
          Returns the global transaction for this local transaction.
<E> Set<E>
getChildrenNames(Fqn<E> fqn)
          Returns all children of a given node.
 Set getChildrenNames(String fqn)
          Convenience method that takes a String representation of an Fqn.
 List<Interceptor> 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.
 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.
 NodeSPI<K,V> getNode(Fqn<?> f)
          Overrides Cache.getNode(Fqn) to return a NodeSPI instead of a Node.
 NodeSPI<K,V> getNode(String s)
          Overrides Cache.getNode(String) to return a NodeSPI instead of a Node.
 Notifier getNotifier()
          Retrieves the current Notifier instance associated with the current Cache instance.
 int getNumberOfAttributes()
           
 int getNumberOfLocksHeld()
           
 int getNumberOfNodes()
           
 RegionManager getRegionManager()
          Retrieves the current RegionManager instance associated with the current Cache instance.
 NodeSPI<K,V> getRoot()
          Overrides Cache.getRoot() to return a NodeSPI instead of a Node.
 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.
 GravitateResult gravitateData(Fqn<?> fqn, boolean searchBuddyBackupSubtrees)
          Used with buddy replication's data gravitation interceptor.
 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).
 void removeInterceptor(Class<? extends Interceptor> 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.
 
Methods inherited from interface org.jboss.cache.Cache
addCacheListener, addCacheListener, clearData, clearData, create, destroy, evict, evict, get, get, getCacheListeners, getCacheListeners, getCacheStatus, getConfiguration, getData, getInvocationContext, getKeys, getKeys, getLocalAddress, getMembers, getRegion, getVersion, move, move, put, put, put, put, putForExternalRead, remove, remove, removeCacheListener, removeCacheListener, removeNode, removeNode, removeRegion, setInvocationContext, start, stop
 

Method Detail

getRoot

NodeSPI<K,V> getRoot()
Overrides Cache.getRoot() to return a NodeSPI instead of a Node.

Specified by:
getRoot in interface Cache<K,V>
Returns:
the root node

getNode

NodeSPI<K,V> getNode(String s)
Overrides Cache.getNode(String) to return a NodeSPI instead of a Node.

Specified by:
getNode in interface Cache<K,V>
Parameters:
s - string representation of an Fqn
Returns:
a NodeSPI

getNode

NodeSPI<K,V> getNode(Fqn<?> f)
Overrides Cache.getNode(Fqn) to return a NodeSPI instead of a Node.

Specified by:
getNode in interface Cache<K,V>
Parameters:
f - an Fqn
Returns:
a NodeSPI

getTransactionManager

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

Returns:
a TransactionManager

getInterceptorChain

List<Interceptor> getInterceptorChain()
Retrieves the current Interceptor chain.

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

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

getMarshaller

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.

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.

Returns:
an instance of Marshaller

addInterceptor

void addInterceptor(Interceptor 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

addInterceptor

void addInterceptor(Interceptor i,
                    Class<? extends Interceptor> 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

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

removeInterceptor

void removeInterceptor(Class<? extends Interceptor> interceptorType)
Removes the interceptor of specified type.

Parameters:
interceptorType - type of interceptor to remove

getCacheLoaderManager

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

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

getBuddyManager

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

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

getTransactionTable

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

Returns:
the current TransactionTable

getRPCManager

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

Returns:
the RPCManager configured.

getStateTransferManager

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

Returns:
the current StateTransferManager

getRegionManager

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

Returns:
the RegionManager

getNotifier

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

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

getClusterName

String getClusterName()
Returns:
the name of the cluster. Null if running in local mode.

getNumberOfAttributes

int getNumberOfAttributes()
Returns:
the number of attributes in the cache.

getNumberOfNodes

int getNumberOfNodes()
Returns:
the number of nodes in the cache.

getCurrentTransaction

GlobalTransaction getCurrentTransaction(Transaction tx,
                                        boolean createIfNotExists)
Returns the global transaction for this local transaction. Optionally creates a new global transaction if it does not exist.

Parameters:
tx - the current transaction
createIfNotExists - if true creates a new transaction if none exists
Returns:
a GlobalTransaction

getCurrentTransaction

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

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

peek

NodeSPI<K,V> peek(Fqn<?> fqn,
                  boolean includeDeletedNodes)
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.

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

peek

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

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

gravitateData

GravitateResult gravitateData(Fqn<?> fqn,
                              boolean searchBuddyBackupSubtrees)
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.

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

getInternalFqns

Set<Fqn> getInternalFqns()
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.

Returns:
an unmodifiable Set. Will not return null.

getNumberOfLocksHeld

int getNumberOfLocksHeld()

exists

boolean exists(Fqn<?> fqn)
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.

Parameters:
fqn - Fqn to peek
Returns:
true if the peek returns a non-null value.

exists

boolean exists(String fqn)
A convenience method that takes a String representation of an Fqn. Otherwise identical to 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.


getChildrenNames

<E> Set<E> getChildrenNames(Fqn<E> 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 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.


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