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

java.lang.Object
  java.util.AbstractMap<K,V>
      org.jgroups.blocks.ReplicatedHashMap<K,V>

All Implemented Interfaces:

java.util.concurrent.ConcurrentMap<K,V>, java.util.Map<K,V>, ReplicatedMap<K,V>, MembershipListener, MessageListener, Receiver

public class ReplicatedHashMap<K,V>
extends java.util.AbstractMap<K,V>
implements java.util.concurrent.ConcurrentMap<K,V>, Receiver, ReplicatedMap<K,V>

Implementation of a ConcurrentMap 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.

A ReplicatedHashMap allows one 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.

Author:

Bela Ban

Nested Class Summary

static interface

ReplicatedHashMap.Notification<K,V>

Nested classes/interfaces inherited from class java.util.AbstractMap

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

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Field Summary

protected RequestOptions	call_options
protected RpcDispatcher	disp
protected Log	log
protected java.util.concurrent.ConcurrentMap<K,V>	map wrapped map instance
protected static java.util.Map<java.lang.Short,java.lang.reflect.Method>	methods

Constructor Summary

ReplicatedHashMap(Channel channel)
Constructs a new ReplicatedHashMap with channel.

ReplicatedHashMap(java.util.concurrent.ConcurrentMap<K,V> map, Channel channel)
Constructs a new ReplicatedHashMap using provided map instance.

Method Summary

void	_clear()
V	_put(K key, V value)
void	_putAll(java.util.Map<? extends K,? extends V> map)
V	_putIfAbsent(K key, V value)
V	_remove(java.lang.Object key)
boolean	_remove(java.lang.Object key, java.lang.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.
boolean	containsKey(java.lang.Object key)
boolean	containsValue(java.lang.Object value)
java.util.Set<java.util.Map.Entry<K,V>>	entrySet()
V	get(java.lang.Object key)
Channel	getChannel()
java.lang.String	getClusterName()
Address	getLocalAddress()
void	getState(java.io.OutputStream ostream) Allows an application to write a state through a provided OutputStream.
long	getTimeout() The timeout (in milliseconds) for blocking updates
protected void	init()
boolean	isBlockingUpdates()
java.util.Set<K>	keySet()
V	put(K key, V value) Maps the specified key to the specified value in this table.
void	putAll(java.util.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(java.lang.Object key) Removes the key (and its corresponding value) from this map.
boolean	remove(java.lang.Object key, java.lang.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	setState(java.io.InputStream istream) Allows an application to read a state through a provided InputStream.
void	setTimeout(long timeout) Sets the cluster call timeout (until all acks have been received)
int	size()
void	start(long state_timeout) Fetches the state
void	stop()
void	suspect(Address suspected_mbr) Called when a member is suspected
static <K,V> 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.
java.util.Collection<V>	values()
void	viewAccepted(View new_view) Called when a change in membership has occurred.

Methods inherited from class java.util.AbstractMap

clone, equals, hashCode, isEmpty, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

equals, hashCode, isEmpty

Field Detail

methods

protected static java.util.Map<java.lang.Short,java.lang.reflect.Method> methods

disp

protected RpcDispatcher disp

call_options

protected final RequestOptions call_options

log

protected final Log log

map

protected java.util.concurrent.ConcurrentMap<K,V> map

wrapped map instance

Constructor Detail

ReplicatedHashMap

public ReplicatedHashMap(Channel channel)

Constructs a new ReplicatedHashMap with channel. Call start(long) to start this map.

ReplicatedHashMap

public ReplicatedHashMap(java.util.concurrent.ConcurrentMap<K,V> map,
                         Channel channel)

Constructs a new ReplicatedHashMap using provided map instance.

Method Detail

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 java.lang.Exception

Fetches the state

Parameters:

state_timeout -

Throws:

java.lang.Exception

getLocalAddress

public Address getLocalAddress()

getClusterName

public java.lang.String getClusterName()

getChannel

public Channel getChannel()

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 java.util.Map<K,V>

Overrides:

put in class java.util.AbstractMap<K,V>

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:

java.lang.NullPointerException - if the specified key or value is null

putIfAbsent

public V putIfAbsent(K key,
                     V value)

Specified by:

putIfAbsent in interface java.util.concurrent.ConcurrentMap<K,V>

Returns:

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

Throws:

java.lang.NullPointerException - if the specified key or value is null

putAll

public void putAll(java.util.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 java.util.Map<K,V>

Overrides:

putAll in class java.util.AbstractMap<K,V>

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 java.util.Map<K,V>

Overrides:

clear in class java.util.AbstractMap<K,V>

remove

public V remove(java.lang.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 java.util.Map<K,V>

Overrides:

remove in class java.util.AbstractMap<K,V>

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:

java.lang.NullPointerException - if the specified key is null

remove

public boolean remove(java.lang.Object key,
                      java.lang.Object value)

Specified by:

remove in interface java.util.concurrent.ConcurrentMap<K,V>

Throws:

java.lang.NullPointerException - if the specified key is null

replace

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

Specified by:

replace in interface java.util.concurrent.ConcurrentMap<K,V>

Throws:

java.lang.NullPointerException - if any of the arguments are null

replace

public V replace(K key,
                 V value)

Specified by:

replace in interface java.util.concurrent.ConcurrentMap<K,V>

Returns:

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

Throws:

java.lang.NullPointerException - if the specified key or value is null

_put

public V _put(K key,
              V value)

Specified by:

_put in interface ReplicatedMap<K,V>

_putIfAbsent

public V _putIfAbsent(K key,
                      V value)

Specified by:

_putIfAbsent in interface ReplicatedMap<K,V>

_putAll

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

Specified by:

_putAll in interface ReplicatedMap<K,V>

See Also:

Map.putAll(java.util.Map)

_clear

public void _clear()

Specified by:

_clear in interface ReplicatedMap<K,V>

_remove

public V _remove(java.lang.Object key)

Specified by:

_remove in interface ReplicatedMap<K,V>

_remove

public boolean _remove(java.lang.Object key,
                       java.lang.Object value)

Specified by:

_remove in interface ReplicatedMap<K,V>

_replace

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

Specified by:

_replace in interface ReplicatedMap<K,V>

_replace

public V _replace(K key,
                  V value)

Specified by:

_replace in interface ReplicatedMap<K,V>

receive

public void receive(Message msg)

Description copied from interface: MessageListener

Called when a message is received.

Specified by:

receive in interface MessageListener

getState

public void getState(java.io.OutputStream ostream)
              throws java.lang.Exception

Description copied from interface: MessageListener

Allows an application to write a state through a provided OutputStream. After the state has been written the OutputStream doesn't need to be closed as stream closing is automatically done when a calling thread returns from this callback.

Specified by:

getState in interface MessageListener

Parameters:

ostream - the OutputStream

Throws:

java.lang.Exception - if the streaming fails, any exceptions should be thrown so that the state requester can re-throw them and let the caller know what happened

See Also:

OutputStream.close()

setState

public void setState(java.io.InputStream istream)
              throws java.lang.Exception

Description copied from interface: MessageListener

Allows an application to read a state through a provided InputStream. After the state has been read the InputStream doesn't need to be closed as stream closing is automatically done when a calling thread returns from this callback.

Specified by:

setState in interface MessageListener

Parameters:

istream - the InputStream

Throws:

java.lang.Exception - if the streaming fails, any exceptions should be thrown so that the state requester can catch them and thus know what happened

See Also:

InputStream.close()

viewAccepted

public void viewAccepted(View new_view)

Description copied from interface: MembershipListener

Called when a change in membership has occurred. No long running actions, sending of messages or anything that could block 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

unblock

public void unblock()

Description copied from interface: MembershipListener

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.

Note that during new view installation we provide guarantee that unblock invocation strictly follows view installation at some node A belonging to that view . However, some other message M may squeeze in between view and unblock callbacks. For more details see https://jira.jboss.org/jira/browse/JGRP-986

Specified by:

unblock in interface MembershipListener

synchronizedMap

public static <K,V> 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:

containsKey

public boolean containsKey(java.lang.Object key)

Specified by:

containsKey in interface java.util.Map<K,V>

Overrides:

containsKey in class java.util.AbstractMap<K,V>

containsValue

public boolean containsValue(java.lang.Object value)

Specified by:

containsValue in interface java.util.Map<K,V>

Overrides:

containsValue in class java.util.AbstractMap<K,V>

entrySet

public java.util.Set<java.util.Map.Entry<K,V>> entrySet()

Specified by:

entrySet in interface java.util.Map<K,V>

Specified by:

entrySet in class java.util.AbstractMap<K,V>

get

public V get(java.lang.Object key)

Specified by:

get in interface java.util.Map<K,V>

Overrides:

get in class java.util.AbstractMap<K,V>

keySet

public java.util.Set<K> keySet()

Specified by:

keySet in interface java.util.Map<K,V>

Overrides:

keySet in class java.util.AbstractMap<K,V>

size

public int size()

Specified by:

size in interface java.util.Map<K,V>

Overrides:

size in class java.util.AbstractMap<K,V>

values

public java.util.Collection<V> values()

Specified by:

values in interface java.util.Map<K,V>

Overrides:

values in class java.util.AbstractMap<K,V>