Class ReplicatedHashMap<K extends Serializable, V extends Serializable>

java.lang.Object

java.util.AbstractMap<K,V>

java.util.concurrent.ConcurrentHashMap<K,V>

org.jgroups.blocks.ReplicatedHashMap<K,V>

All Implemented Interfaces:

Serializable, ConcurrentMap<K,V>, Map<K,V>, ReplicatedMap<K,V>, ExtendedMembershipListener, ExtendedMessageListener, ExtendedReceiver, MembershipListener, MessageListener, Receiver

public class ReplicatedHashMap<K extends Serializable, V extends Serializable>
extends ConcurrentHashMap<K,V>
implements ExtendedReceiver, ReplicatedMap<K,V>

Subclass of a ConcurrentHashMap with replication of the contents across a cluster. Any change to the hashmap (clear(), put(), remove() etc) will transparently be propagated to all replicas in the group. All read-only methods will always access the local replica.

Keys and values added to the hashmap must be serializable, the reason being that they will be sent across the network to all replicas of the group. Having said this, it is now for example possible to add RMI remote objects to the hashtable as they are derived from java.rmi.server.RemoteObject which in turn is serializable. This allows to lookup shared distributed objects by their name and invoke methods on them, regardless of one's onw location. A ReplicatedHashMap thus allows to implement a distributed naming service in just a couple of lines.

An instance of this class will contact an existing member of the group to fetch its initial state.

This class combines both ReplicatedHashtable (asynchronous replication) and DistributedHashtable (synchronous replication) into one class

Version:

$Id: ReplicatedHashMap.java,v 1.12.2.3 2008/05/13 12:02:23 vlada Exp $

Author:

Bela Ban

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ReplicatedHashMap.Notification<K extends Serializable, V extends Serializable>

Nested classes/interfaces inherited from class ConcurrentHashMap

ConcurrentHashMap.KeySetView<K,V>

Nested classes/interfaces inherited from class AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface Map

Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field	Description
protected RpcDispatcher	disp
protected final org.apache.commons.logging.Log	log
protected static Map<Short,Method>	methods
protected final Promise<Boolean>	state_promise
protected long	timeout	For blocking updates only: the max time to wait (0 == forever)
protected int	update_mode	Whether updates across the cluster should be asynchronous (default) or synchronous)

Constructor Summary

Constructors

Constructor	Description
ReplicatedHashMap(String clustername, ChannelFactory factory, String properties, boolean persistent, long state_timeout)	Creates a ReplicatedHashMap.
ReplicatedHashMap(String clustername, ChannelFactory factory, String properties, long state_timeout)	Creates a ReplicatedHashMap
ReplicatedHashMap(Channel channel)
ReplicatedHashMap(Channel channel, boolean persistent)

Method Summary

Modifier and Type	Method	Description
void	_clear()
V	_put(K key, V value)
void	_putAll(Map<? extends K, ? extends V> map)
V	_putIfAbsent(K key, V value)
V	_remove(Object key)
boolean	_remove(Object key, Object value)
V	_replace(K key, V value)
boolean	_replace(K key, V oldValue, V newValue)
void	addNotifier(ReplicatedHashMap.Notification n)
void	block()	Block sending and receiving of messages until ViewAccepted is called
void	clear()	Removes all of the mappings from this map.
Channel	getChannel()
String	getClusterName()
Address	getLocalAddress()
boolean	getPersistent()
byte[]	getState()	Answers the group state; e.g., when joining.
void	getState(OutputStream ostream)	Allows an application to write a state through a provided OutputStream.
byte[]	getState(String state_id)	Allows an application to provide a partial state as a byte array
void	getState(String state_id, OutputStream ostream)	Allows an application to write a partial state through a provided OutputStream.
long	getTimeout()	The timeout (in milliseconds) for blocking updates
protected final void	init()
boolean	isBlockingUpdates()
V	put(K key, V value)	Maps the specified key to the specified value in this table.
void	putAll(Map<? extends K, ? extends V> m)	Copies all of the mappings from the specified map to this one.
V	putIfAbsent(K key, V value)
void	receive(Message msg)	Called when a message is received.
V	remove(Object key)	Removes the key (and its corresponding value) from this map.
boolean	remove(Object key, Object value)
void	removeNotifier(ReplicatedHashMap.Notification n)
V	replace(K key, V value)
boolean	replace(K key, V oldValue, V newValue)
void	setBlockingUpdates(boolean blocking_updates)	Whether updates across the cluster should be asynchronous (default) or synchronous)
void	setDeadlockDetection(boolean flag)
void	setPersistent(boolean p)
void	setState(byte[] new_state)	Sets the group state; e.g., when joining.
void	setState(InputStream istream)	Allows an application to read a state through a provided InputStream.
void	setState(String state_id, byte[] state)	Allows an application to read a partial state indicated by state_id from a given state byte array parameter.
void	setState(String state_id, InputStream istream)	Allows an application to read a partial state through a provided InputStream.
void	setTimeout(long timeout)	Sets the cluster call timeout (until all acks have been received)
final void	start(long state_timeout)	Fetches the state
void	stop()
void	suspect(Address suspected_mbr)	Called when a member is suspected
static <K extends Serializable, V extends Serializable> ReplicatedMap<K,V>	synchronizedMap(ReplicatedMap<K,V> map)	Creates a synchronized facade for a ReplicatedMap.
void	unblock()	Called after the FLUSH protocol has unblocked previously blocked senders, and messages can be sent again.
void	viewAccepted(View new_view)	Called when a change in membership has occurred.

Methods inherited from class ConcurrentHashMap

compute, computeIfAbsent, computeIfPresent, contains, containsKey, containsValue, elements, entrySet, equals, forEach, forEach, forEach, forEachEntry, forEachEntry, forEachKey, forEachKey, forEachValue, forEachValue, get, getOrDefault, hashCode, isEmpty, keys, keySet, keySet, mappingCount, merge, newKeySet, newKeySet, reduce, reduceEntries, reduceEntries, reduceEntriesToDouble, reduceEntriesToInt, reduceEntriesToLong, reduceKeys, reduceKeys, reduceKeysToDouble, reduceKeysToInt, reduceKeysToLong, reduceToDouble, reduceToInt, reduceToLong, reduceValues, reduceValues, reduceValuesToDouble, reduceValuesToInt, reduceValuesToLong, replaceAll, search, searchEntries, searchKeys, searchValues, size, toString, values

Methods inherited from class AbstractMap

clone

Methods inherited from class Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface ConcurrentMap

compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, replaceAll

Methods inherited from interface Map

containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, size, values

Field Details

methods

protected static Map<Short,Method> methods

disp

protected transient RpcDispatcher disp

state_promise

protected final transient Promise<Boolean> state_promise

update_mode

protected int update_mode

Whether updates across the cluster should be asynchronous (default) or synchronous)

timeout

protected long timeout

For blocking updates only: the max time to wait (0 == forever)

log

protected final org.apache.commons.logging.Log log

Constructor Details

ReplicatedHashMap

public ReplicatedHashMap(String clustername,
 ChannelFactory factory,
 String properties,
 long state_timeout)
                  throws ChannelException

Creates a ReplicatedHashMap

Parameters:

clustername - The name of the group to join

factory - The ChannelFactory which will be used to create a channel

properties - The property string to be used to define the channel. This will override the properties of the factory. If null, then the factory properties will be used

state_timeout - The time to wait until state is retrieved in milliseconds. A value of 0 means wait forever.

Throws:

ChannelException

ReplicatedHashMap

public ReplicatedHashMap(String clustername,
 ChannelFactory factory,
 String properties,
 boolean persistent,
 long state_timeout)
                  throws ChannelException

Creates a ReplicatedHashMap. Optionally the contents can be saved to persistemt storage using the PersistenceManager.

Parameters:

clustername - Name of the group to join

factory - Instance of a ChannelFactory to create the channel

properties - Protocol stack properties. This will override the properties of the factory. If null, then the factory properties will be used

persistent - Whether the contents should be persisted

state_timeout - Max number of milliseconds to wait until the state is retrieved

Throws:

ChannelException

ReplicatedHashMap

public ReplicatedHashMap(Channel channel)

ReplicatedHashMap

public ReplicatedHashMap(Channel channel,
 boolean persistent)

Method Details

init

protected final void init()

isBlockingUpdates

public boolean isBlockingUpdates()

setBlockingUpdates

public void setBlockingUpdates(boolean blocking_updates)

Whether updates across the cluster should be asynchronous (default) or synchronous)

Parameters:

blocking_updates -

getTimeout

public long getTimeout()

The timeout (in milliseconds) for blocking updates

setTimeout

public void setTimeout(long timeout)

Sets the cluster call timeout (until all acks have been received)

Parameters:

timeout - The timeout (in milliseconds) for blocking updates

start

public final void start(long state_timeout)
                 throws ChannelClosedException,
ChannelNotConnectedException

Fetches the state

Parameters:

state_timeout -

Throws:

ChannelClosedException

ChannelNotConnectedException

getLocalAddress

public Address getLocalAddress()

getClusterName

public String getClusterName()

getChannel

public Channel getChannel()

getPersistent

public boolean getPersistent()

setPersistent

public void setPersistent(boolean p)

setDeadlockDetection

public void setDeadlockDetection(boolean flag)

addNotifier

public void addNotifier(ReplicatedHashMap.Notification n)

removeNotifier

public void removeNotifier(ReplicatedHashMap.Notification n)

stop

public void stop()

put

public V put(K key,
 V value)

Maps the specified key to the specified value in this table. Neither the key nor the value can be null.

The value can be retrieved by calling the get method with a key that is equal to the original key.

Specified by:

put in interface Map<K extends Serializable, V extends Serializable>

Overrides:

put in class ConcurrentHashMap<K extends Serializable, V extends Serializable>

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

Returns:

the previous value associated with key, or null if there was no mapping for key

Throws:

NullPointerException - if the specified key or value is null

putIfAbsent

public V putIfAbsent(K key,
 V value)

Specified by:

putIfAbsent in interface ConcurrentMap<K extends Serializable, V extends Serializable>

Specified by:

putIfAbsent in interface Map<K extends Serializable, V extends Serializable>

Overrides:

putIfAbsent in class ConcurrentHashMap<K extends Serializable, V extends Serializable>

Returns:

the previous value associated with the specified key, or null if there was no mapping for the key

Throws:

NullPointerException - if the specified key or value is null

putAll

public void putAll(Map<? extends K, ? extends V> m)

Copies all of the mappings from the specified map to this one. These mappings replace any mappings that this map had for any of the keys currently in the specified map.

Specified by:

putAll in interface Map<K extends Serializable, V extends Serializable>

Overrides:

putAll in class ConcurrentHashMap<K extends Serializable, V extends Serializable>

Parameters:

m - mappings to be stored in this map

clear

public void clear()

Removes all of the mappings from this map.

Specified by:

clear in interface Map<K extends Serializable, V extends Serializable>

Overrides:

clear in class ConcurrentHashMap<K extends Serializable, V extends Serializable>

remove

public V remove(Object key)

Removes the key (and its corresponding value) from this map. This method does nothing if the key is not in the map.

Specified by:

remove in interface Map<K extends Serializable, V extends Serializable>

Overrides:

remove in class ConcurrentHashMap<K extends Serializable, V extends Serializable>

Parameters:

key - the key that needs to be removed

Returns:

the previous value associated with key, or null if there was no mapping for key

Throws:

NullPointerException - if the specified key is null

remove

public boolean remove(Object key,
 Object value)

Specified by:

remove in interface ConcurrentMap<K extends Serializable, V extends Serializable>

Specified by:

remove in interface Map<K extends Serializable, V extends Serializable>

Overrides:

remove in class ConcurrentHashMap<K extends Serializable, V extends Serializable>

Throws:

NullPointerException - if the specified key is null

replace

public boolean replace(K key,
 V oldValue,
 V newValue)

Specified by:

replace in interface ConcurrentMap<K extends Serializable, V extends Serializable>

Specified by:

replace in interface Map<K extends Serializable, V extends Serializable>

Overrides:

replace in class ConcurrentHashMap<K extends Serializable, V extends Serializable>

Throws:

NullPointerException - if any of the arguments are null

replace

public V replace(K key,
 V value)

Specified by:

replace in interface ConcurrentMap<K extends Serializable, V extends Serializable>

Specified by:

replace in interface Map<K extends Serializable, V extends Serializable>

Overrides:

replace in class ConcurrentHashMap<K extends Serializable, V extends Serializable>

Returns:

the previous value associated with the specified key, or null if there was no mapping for the key

Throws:

NullPointerException - if the specified key or value is null

_put

public V _put(K key,
 V value)

Specified by:

_put in interface ReplicatedMap<K extends Serializable, V extends Serializable>

_putIfAbsent

public V _putIfAbsent(K key,
 V value)

Specified by:

_putIfAbsent in interface ReplicatedMap<K extends Serializable, V extends Serializable>

_putAll

public void _putAll(Map<? extends K, ? extends V> map)

Specified by:

_putAll in interface ReplicatedMap<K extends Serializable, V extends Serializable>

See Also:

• Map.putAll(java.util.Map)

_clear

public void _clear()

Specified by:

_clear in interface ReplicatedMap<K extends Serializable, V extends Serializable>

_remove

public V _remove(Object key)

Specified by:

_remove in interface ReplicatedMap<K extends Serializable, V extends Serializable>

_remove

public boolean _remove(Object key,
 Object value)

Specified by:

_remove in interface ReplicatedMap<K extends Serializable, V extends Serializable>

_replace

public boolean _replace(K key,
 V oldValue,
 V newValue)

Specified by:

_replace in interface ReplicatedMap<K extends Serializable, V extends Serializable>

_replace

public V _replace(K key,
 V value)

Specified by:

_replace in interface ReplicatedMap<K extends Serializable, V extends Serializable>

receive

public void receive(Message msg)

Description copied from interface: MessageListener

Called when a message is received.

Specified by:

receive in interface MessageListener

Parameters:

msg -

getState

public byte[] getState()

Description copied from interface: MessageListener

Answers the group state; e.g., when joining.

Specified by:

getState in interface MessageListener

Returns:

byte[]

setState

public void setState(byte[] new_state)

Description copied from interface: MessageListener

Sets the group state; e.g., when joining.

Specified by:

setState in interface MessageListener

Parameters:

new_state -

viewAccepted

public void viewAccepted(View new_view)

Description copied from interface: MembershipListener

Called when a change in membership has occurred. No long running actions or sending of messages should be done in this callback. If some long running action needs to be performed, it should be done in a separate thread.

Note that on reception of the first view (a new member just joined), the channel will not yet be in the connected state. This only happens when Channel.connect(String) returns.

Specified by:

viewAccepted in interface MembershipListener

suspect

public void suspect(Address suspected_mbr)

Called when a member is suspected

Specified by:

suspect in interface MembershipListener

block

public void block()

Block sending and receiving of messages until ViewAccepted is called

Specified by:

block in interface MembershipListener

getState

public byte[] getState(String state_id)

Description copied from interface: ExtendedMessageListener

Allows an application to provide a partial state as a byte array

Specified by:

getState in interface ExtendedMessageListener

Parameters:

state_id - id of the partial state requested

Returns:

partial state for the given state_id

getState

public void getState(OutputStream ostream)

Description copied from interface: ExtendedMessageListener

Allows an application to write a state through a provided OutputStream. An application is obligated to always close the given OutputStream reference.

Specified by:

getState in interface ExtendedMessageListener

Parameters:

ostream - the OutputStream

See Also:

• OutputStream.close()

getState

public void getState(String state_id,
 OutputStream ostream)

Description copied from interface: ExtendedMessageListener

Allows an application to write a partial state through a provided OutputStream. An application is obligated to always close the given OutputStream reference.

Specified by:

getState in interface ExtendedMessageListener

Parameters:

state_id - id of the partial state requested

ostream - the OutputStream

See Also:

• OutputStream.close()

setState

public void setState(String state_id,
 byte[] state)

Description copied from interface: ExtendedMessageListener

Allows an application to read a partial state indicated by state_id from a given state byte array parameter.

Specified by:

setState in interface ExtendedMessageListener

Parameters:

state_id - id of the partial state requested

state - partial state for the given state_id

setState

public void setState(InputStream istream)

Description copied from interface: ExtendedMessageListener

Allows an application to read a state through a provided InputStream. An application is obligated to always close the given InputStream reference.

Specified by:

setState in interface ExtendedMessageListener

Parameters:

istream - the InputStream

See Also:

• InputStream.close()

setState

public void setState(String state_id,
 InputStream istream)

Description copied from interface: ExtendedMessageListener

Allows an application to read a partial state through a provided InputStream. An application is obligated to always close the given InputStream reference.

Specified by:

setState in interface ExtendedMessageListener

Parameters:

state_id - id of the partial state requested

istream - the InputStream

See Also:

• InputStream.close()

unblock

public void unblock()

Description copied from interface: ExtendedMembershipListener

Called after the FLUSH protocol has unblocked previously blocked senders, and messages can be sent again. This callback only needs to be implemented if we require a notification of that.

Specified by:

unblock in interface ExtendedMembershipListener

synchronizedMap

public static <K extends Serializable, V extends Serializable>
ReplicatedMap<K,V> synchronizedMap(ReplicatedMap<K,V> map)

Creates a synchronized facade for a ReplicatedMap. All methods which change state are invoked through a monitor. This is similar to , but also includes the replication methods (starting with an underscore).

Parameters:

map -

Returns: