org.jgroups.blocks
Class ReplicatedHashMap<K extends java.io.Serializable,V extends java.io.Serializable>

java.lang.Object
  extended by java.util.AbstractMap<K,V>
      extended by java.util.concurrent.ConcurrentHashMap<K,V>
          extended by org.jgroups.blocks.ReplicatedHashMap<K,V>
All Implemented Interfaces:
java.io.Serializable, java.util.concurrent.ConcurrentMap<K,V>, java.util.Map<K,V>, ReplicatedMap<K,V>, ExtendedMembershipListener, ExtendedMessageListener, ExtendedReceiver, MembershipListener, MessageListener, Receiver

public class ReplicatedHashMap<K extends java.io.Serializable,V extends java.io.Serializable>
extends java.util.concurrent.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
static interface ReplicatedHashMap.Notification<K extends java.io.Serializable,V extends java.io.Serializable>
           
 
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  RpcDispatcher disp
           
protected  org.apache.commons.logging.Log log
           
protected static java.util.Map<java.lang.Short,java.lang.reflect.Method> methods
           
protected  Promise<java.lang.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
ReplicatedHashMap(Channel channel)
           
ReplicatedHashMap(Channel channel, boolean persistent)
           
ReplicatedHashMap(java.lang.String clustername, ChannelFactory factory, java.lang.String properties, boolean persistent, long state_timeout)
          Creates a ReplicatedHashMap.
ReplicatedHashMap(java.lang.String clustername, ChannelFactory factory, java.lang.String properties, long state_timeout)
          Creates a ReplicatedHashMap
 
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.
 Channel getChannel()
           
 java.lang.String getClusterName()
           
 Address getLocalAddress()
           
 boolean getPersistent()
           
 byte[] getState()
          Answers the group state; e.g., when joining.
 void getState(java.io.OutputStream ostream)
          Allows an application to write a state through a provided OutputStream.
 byte[] getState(java.lang.String state_id)
          Allows an application to provide a partial state as a byte array
 void getState(java.lang.String state_id, java.io.OutputStream ostream)
          Allows an application to write a partial state through a provided OutputStream.
 long getTimeout()
          The timeout (in milliseconds) for blocking updates
protected  void init()
           
 boolean isBlockingUpdates()
           
 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 setDeadlockDetection(boolean flag)
           
 void setPersistent(boolean p)
           
 void setState(byte[] new_state)
          Sets the group state; e.g., when joining.
 void setState(java.io.InputStream istream)
          Allows an application to read a state through a provided InputStream.
 void setState(java.lang.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(java.lang.String state_id, java.io.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)
 void start(long state_timeout)
          Fetches the state
 void stop()
           
 void suspect(Address suspected_mbr)
          Called when a member is suspected
static
<K extends java.io.Serializable,V extends java.io.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 java.util.concurrent.ConcurrentHashMap
contains, containsKey, containsValue, elements, entrySet, get, isEmpty, keys, keySet, size, values
 
Methods inherited from class java.util.AbstractMap
clone, equals, hashCode, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Map
containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, size, values
 

Field Detail

methods

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

disp

protected transient RpcDispatcher disp

state_promise

protected final transient Promise<java.lang.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 Detail

ReplicatedHashMap

public ReplicatedHashMap(java.lang.String clustername,
                         ChannelFactory factory,
                         java.lang.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(java.lang.String clustername,
                         ChannelFactory factory,
                         java.lang.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 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 ChannelClosedException,
                        ChannelNotConnectedException
Fetches the state

Parameters:
state_timeout -
Throws:
ChannelClosedException
ChannelNotConnectedException

getLocalAddress

public Address getLocalAddress()

getClusterName

public java.lang.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 java.util.Map<K extends java.io.Serializable,V extends java.io.Serializable>
Overrides:
put in class java.util.concurrent.ConcurrentHashMap<K extends java.io.Serializable,V extends java.io.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:
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 extends java.io.Serializable,V extends java.io.Serializable>
Overrides:
putIfAbsent in class java.util.concurrent.ConcurrentHashMap<K extends java.io.Serializable,V extends java.io.Serializable>
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 extends java.io.Serializable,V extends java.io.Serializable>
Overrides:
putAll in class java.util.concurrent.ConcurrentHashMap<K extends java.io.Serializable,V extends java.io.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 java.util.Map<K extends java.io.Serializable,V extends java.io.Serializable>
Overrides:
clear in class java.util.concurrent.ConcurrentHashMap<K extends java.io.Serializable,V extends java.io.Serializable>

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 extends java.io.Serializable,V extends java.io.Serializable>
Overrides:
remove in class java.util.concurrent.ConcurrentHashMap<K extends java.io.Serializable,V extends java.io.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:
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 extends java.io.Serializable,V extends java.io.Serializable>
Overrides:
remove in class java.util.concurrent.ConcurrentHashMap<K extends java.io.Serializable,V extends java.io.Serializable>
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 extends java.io.Serializable,V extends java.io.Serializable>
Overrides:
replace in class java.util.concurrent.ConcurrentHashMap<K extends java.io.Serializable,V extends java.io.Serializable>
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 extends java.io.Serializable,V extends java.io.Serializable>
Overrides:
replace in class java.util.concurrent.ConcurrentHashMap<K extends java.io.Serializable,V extends java.io.Serializable>
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 extends java.io.Serializable,V extends java.io.Serializable>

_putIfAbsent

public V _putIfAbsent(K key,
                      V value)
Specified by:
_putIfAbsent in interface ReplicatedMap<K extends java.io.Serializable,V extends java.io.Serializable>

_putAll

public void _putAll(java.util.Map<? extends K,? extends V> map)
Specified by:
_putAll in interface ReplicatedMap<K extends java.io.Serializable,V extends java.io.Serializable>
See Also:
Map.putAll(java.util.Map)

_clear

public void _clear()
Specified by:
_clear in interface ReplicatedMap<K extends java.io.Serializable,V extends java.io.Serializable>

_remove

public V _remove(java.lang.Object key)
Specified by:
_remove in interface ReplicatedMap<K extends java.io.Serializable,V extends java.io.Serializable>

_remove

public boolean _remove(java.lang.Object key,
                       java.lang.Object value)
Specified by:
_remove in interface ReplicatedMap<K extends java.io.Serializable,V extends java.io.Serializable>

_replace

public boolean _replace(K key,
                        V oldValue,
                        V newValue)
Specified by:
_replace in interface ReplicatedMap<K extends java.io.Serializable,V extends java.io.Serializable>

_replace

public V _replace(K key,
                  V value)
Specified by:
_replace in interface ReplicatedMap<K extends java.io.Serializable,V extends java.io.Serializable>

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

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(java.lang.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(java.io.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(java.lang.String state_id,
                     java.io.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(java.lang.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(java.io.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(java.lang.String state_id,
                     java.io.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 java.io.Serializable,V extends java.io.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:


Copyright © 1998-2008 Bela Ban. All Rights Reserved.