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

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

@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 CommandInterceptor 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 AT jboss DOT org)
See Also:
NodeSPI, Cache, CacheLoader

Method Summary
 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()
           
 ComponentRegistry getComponentRegistry()
          Returns the component registry associated with this cache instance.
 GlobalTransaction getCurrentTransaction()
          Returns the transaction associated with the current thread.
 GlobalTransaction getCurrentTransaction(Transaction tx, boolean createIfNotExists)
          Returns the global transaction for this local transaction.
 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.
 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, InvocationContext ctx)
          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).
 
Methods inherited from interface org.jboss.cache.Cache
addCacheListener, addInterceptor, addInterceptor, clearData, clearData, create, destroy, endBatch, evict, evict, get, get, getCacheListeners, getCacheStatus, getChildrenNames, getChildrenNames, getConfiguration, getData, getInvocationContext, getKeys, getKeys, getLocalAddress, getMembers, getRegion, getVersion, isLeaf, isLeaf, move, move, put, put, put, put, putForExternalRead, remove, remove, removeCacheListener, removeInterceptor, removeInterceptor, removeNode, removeNode, removeRegion, setInvocationContext, start, startBatch, 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<CommandInterceptor> 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 CommandInterceptors 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

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,
                              InvocationContext ctx)
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.
ctx -
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.


getComponentRegistry

ComponentRegistry getComponentRegistry()
Returns the component registry associated with this cache instance.

See Also:
ComponentRegistry


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