org.infinispan.distribution
Interface DistributionManager

All Known Implementing Classes:

DistributionManagerImpl

public interface DistributionManager

A component that manages the distribution of elements across a cache cluster

Since:

4.0

Author:

Manik Surtani, Mircea.Markus@jboss.com, Vladimir Blagojevic

Method Summary

void	abortJoin(Address sender)
void	applyRemoteTxLog(List<WriteCommand> modifications) Applies an ordered list of modifications to the current node.
void	applyState(ConsistentHash newConsistentHash, Map<Object,InternalCacheValue> state, RemoteTransactionLogger transactionLogger, boolean forLeave)
List<Address>	getAffectedNodes(Set<Object> affectedKeys) A helper method that retrieves a list of nodes affected by operations on a set of keys.
CacheStore	getCacheStoreForRehashing() Retrieves a cache store if one is available and set up for use in rehashing.
ConsistentHash	getConsistentHash() Retrieves the consistent hash instance currently in use, which may be an instance of the configured ConsistentHash instance (which defaults to DefaultConsistentHash, or an instance of UnionConsistentHash if a rehash is in progress.
DataLocality	getLocality(Object key) Returns the data locality characteristics of a given key.
TopologyInfo	getTopologyInfo()
TransactionLogger	getTransactionLogger() Retrieves the transaction logger instance associated with this DistributionManager
NodeTopologyInfo	informRehashOnJoin(Address joiner, boolean starting, NodeTopologyInfo nodeTopologyInfo) This will cause all nodes to add the joiner to their consistent hash instance (usually by creating a UnionConsistentHash
void	informRehashOnLeave(Address sender)
boolean	isAffectedByRehash(Object key) Tests whether a given key is affected by a rehash that may be in progress.
boolean	isInFinalJoinPhase()
boolean	isJoinComplete() Tests whether the current instance has completed joining the cluster
boolean	isLocal(Object key) Deprecated.
boolean	isRehashInProgress() Tests whether a rehash is in progress
List<Address>	locate(Object key) Locates a key in a cluster.
Map<Object,List<Address>>	locateAll(Collection<Object> keys) Locates a list of keys in a cluster.
Map<Object,List<Address>>	locateAll(Collection<Object> keys, int numOwners) Same as locateAll(java.util.Collection), but the list of addresses only contains numOwners owners.
Set<Address>	requestPermissionToJoin(Address joiner) "Asks" a coordinator if a joiner may join.
InternalCacheEntry	retrieveFromRemoteSource(Object key, InvocationContext ctx) Retrieves a cache entry from a remote source.
void	setConsistentHash(ConsistentHash consistentHash) Sets the consistent hash implementation in use.
void	setJoinComplete(boolean value)
void	setRehashInProgress(boolean value)
void	setTopologyInfo(TopologyInfo ti)
void	transformForL1(CacheEntry entry) Transforms a cache entry so it is marked for L1 rather than the primary cache data structure.
void	waitForFinalJoin()

Method Detail

isLocal

@Deprecated
boolean isLocal(Object key)

Deprecated.

Checks whether a key is mapped to the local node.

Do not use! This API is buggy in that it doesn't take into account changing ownerships and can introduce race conditions if results are relied upon. Please use getLocality(Object) instead.

Parameters:

key - key to test

Returns:

true if local, false otherwise.

getLocality

DataLocality getLocality(Object key)

Returns the data locality characteristics of a given key.

Parameters:

key - key to test

Returns:

a DataLocality that allows you to test whether a key is mapped to the local node or not, and the degree of certainty of such a result.

locate

List<Address> locate(Object key)

Locates a key in a cluster. The returned addresses may not be owners of the keys if a rehash happens to be in progress or is pending, so when querying these servers, invalid responses should be checked for and the next address checked accordingly.

Parameters:

key - key to test

Returns:

a list of addresses where the key may reside

locateAll

Map<Object,List<Address>> locateAll(Collection<Object> keys)

Locates a list of keys in a cluster. Like locate(Object) the returned addresses may not be owners of the keys if a rehash happens to be in progress or is pending, so when querying these servers, invalid responses should be checked for and the next address checked accordingly.

Parameters:

keys - list of keys to test

Returns:

a list of addresses where the key may reside

locateAll

Map<Object,List<Address>> locateAll(Collection<Object> keys,
                                    int numOwners)

Same as locateAll(java.util.Collection), but the list of addresses only contains numOwners owners.

transformForL1

void transformForL1(CacheEntry entry)

Transforms a cache entry so it is marked for L1 rather than the primary cache data structure. This should be done if it is deemed that the entry is targeted for L1 storage rather than storage in the primary data container.

Parameters:

entry - entry to transform

retrieveFromRemoteSource

InternalCacheEntry retrieveFromRemoteSource(Object key,
                                            InvocationContext ctx)
                                            throws Exception

Retrieves a cache entry from a remote source. Would typically involve an RPC call using a ClusteredGetCommand and some form of quorum of responses if the responses returned are inconsistent - often the case if there is a rehash in progress, involving nodes that the key maps to.

Parameters:

key - key to look up

ctx -

Returns:

an internal cache entry, or null if it cannot be located

Throws:

Exception - if something bad happens

getConsistentHash

ConsistentHash getConsistentHash()

Retrieves the consistent hash instance currently in use, which may be an instance of the configured ConsistentHash instance (which defaults to DefaultConsistentHash, or an instance of UnionConsistentHash if a rehash is in progress.

Returns:

a ConsistentHash instance

setConsistentHash

void setConsistentHash(ConsistentHash consistentHash)

Sets the consistent hash implementation in use.

Parameters:

consistentHash - consistent hash to set to

isAffectedByRehash

boolean isAffectedByRehash(Object key)

Tests whether a given key is affected by a rehash that may be in progress. If no rehash is in progress, this method returns false. Helps determine whether additional steps are necessary in handling an operation with a given key.

Parameters:

key - key to test

Returns:

whether a key is affected by a rehash

getTransactionLogger

TransactionLogger getTransactionLogger()

Retrieves the transaction logger instance associated with this DistributionManager

Returns:

a TransactionLogger

requestPermissionToJoin

Set<Address> requestPermissionToJoin(Address joiner)

"Asks" a coordinator if a joiner may join. Used to serialize joins such that only a single joiner comes in at any given time.

Parameters:

joiner - joiner who wants to join

Returns:

a consistent hash prior to the joiner joining (if the joiner is allowed to join), otherwise null.

informRehashOnJoin

NodeTopologyInfo informRehashOnJoin(Address joiner,
                                    boolean starting,
                                    NodeTopologyInfo nodeTopologyInfo)

This will cause all nodes to add the joiner to their consistent hash instance (usually by creating a UnionConsistentHash

Parameters:

joiner - address of joiner

starting - if true, the joiner is reporting that it is starting the join process. If false, the joiner is

nodeTopologyInfo -

getCacheStoreForRehashing

CacheStore getCacheStoreForRehashing()

Retrieves a cache store if one is available and set up for use in rehashing. May return null!

Returns:

a cache store is one is available and configured for use in rehashing, or null otherwise.

isRehashInProgress

boolean isRehashInProgress()

Tests whether a rehash is in progress

Returns:

true if a rehash is in progress, false otherwise

isJoinComplete

boolean isJoinComplete()

Tests whether the current instance has completed joining the cluster

Returns:

true if join is in progress, false otherwise

isInFinalJoinPhase

boolean isInFinalJoinPhase()

waitForFinalJoin

void waitForFinalJoin()

getAffectedNodes

List<Address> getAffectedNodes(Set<Object> affectedKeys)

A helper method that retrieves a list of nodes affected by operations on a set of keys. This helper will in turn call locateAll(java.util.Collection) and then combine the result addresses.

Parameters:

affectedKeys - keys to locate

Returns:

a list of addresses which represent a combined set of all addresses affected by the set of keys.

applyRemoteTxLog

void applyRemoteTxLog(List<WriteCommand> modifications)

Applies an ordered list of modifications to the current node. Typically used when state is pushed to the node (i.e., anotehr node leaves the cluster) and the transaction log needs to be flushed after pushing state.

Parameters:

modifications - ordered list of mods

informRehashOnLeave

void informRehashOnLeave(Address sender)

applyState

void applyState(ConsistentHash newConsistentHash,
                Map<Object,InternalCacheValue> state,
                RemoteTransactionLogger transactionLogger,
                boolean forLeave)

setRehashInProgress

void setRehashInProgress(boolean value)

getTopologyInfo

TopologyInfo getTopologyInfo()

setJoinComplete

void setJoinComplete(boolean value)

abortJoin

void abortJoin(Address sender)

setTopologyInfo

void setTopologyInfo(TopologyInfo ti)