org.jgroups.blocks

## Class ReplicatedHashMap<K extends java.io.Serializable,V extends java.io.Serializable>

- 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>, ExtendedMembershipListener, ExtendedMessageListener, ExtendedReceiver, MembershipListener, MessageListener, Receiver

    public class ReplicatedHashMap<K extends java.io.Serializable,V extends java.io.Serializable>
    extends java.util.AbstractMap<K,V>
    implements java.util.concurrent.ConcurrentMap<K,V>, 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 `org.jgroups.blocks.ReplicatedHashtable` (asynchronous replication) and `org.jgroups.blocks.DistributedHashtable` (synchronous replication) into one class

Author:
  Bela Ban

### Nested Class Summary

Nested Classes
`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

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

Constructors
Constructor and Description
`ReplicatedHashMap(Channel channel)` Constructs a new ReplicatedHashMap with channel.
`ReplicatedHashMap(Channel channel, boolean persistent)` Constructs a new ReplicatedHashMap with channel and persistence option.
`ReplicatedHashMap(java.util.concurrent.ConcurrentMap<K,V> map, Channel channel, boolean persistent)` Constructs a new ReplicatedHashMap using provided map instance.
`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

Methods
`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` `contains(java.lang.Object value)` Deprecated.
`boolean` `containsKey(java.lang.Object key)`
`boolean` `containsValue(java.lang.Object value)`
`java.util.Enumeration<V>` `elements()` Deprecated.
`java.util.Set<java.util.Map.Entry<K,V>>` `entrySet()`
`V` `get(java.lang.Object key)`
`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()`
`java.util.Enumeration<K>` `keys()` Deprecated.
`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` `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)
`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 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.
`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

#### state_promise

    protected final 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 Log log

#### map

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

Wrapped map instance.

### 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 persistent 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)

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

#### ReplicatedHashMap

    public ReplicatedHashMap(Channel channel,
                     boolean persistent)

Constructs a new ReplicatedHashMap with channel and persistence option. Call `start(long)` to start this map.

#### ReplicatedHashMap

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

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 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.AbstractMap<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>`
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.AbstractMap<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.AbstractMap<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.AbstractMap<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>`
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>`
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>`
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`

#### 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()`

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

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

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

#### containsKey

    public boolean containsKey(java.lang.Object key)

Specified by:
  `containsKey` in interface `java.util.Map<K extends java.io.Serializable,V extends java.io.Serializable>`
Overrides:
  `containsKey` in class `java.util.AbstractMap<K extends java.io.Serializable,V extends java.io.Serializable>`

#### containsValue

    public boolean containsValue(java.lang.Object value)

Specified by:
  `containsValue` in interface `java.util.Map<K extends java.io.Serializable,V extends java.io.Serializable>`
Overrides:
  `containsValue` in class `java.util.AbstractMap<K extends java.io.Serializable,V extends java.io.Serializable>`

#### entrySet

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

Specified by:
  `entrySet` in interface `java.util.Map<K extends java.io.Serializable,V extends java.io.Serializable>`
Specified by:
  `entrySet` in class `java.util.AbstractMap<K extends java.io.Serializable,V extends java.io.Serializable>`

#### get

    public V get(java.lang.Object key)

Specified by:
  `get` in interface `java.util.Map<K extends java.io.Serializable,V extends java.io.Serializable>`
Overrides:
  `get` in class `java.util.AbstractMap<K extends java.io.Serializable,V extends java.io.Serializable>`

#### keySet

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

Specified by:
  `keySet` in interface `java.util.Map<K extends java.io.Serializable,V extends java.io.Serializable>`
Overrides:
  `keySet` in class `java.util.AbstractMap<K extends java.io.Serializable,V extends java.io.Serializable>`

#### size

    public int size()

Specified by:
  `size` in interface `java.util.Map<K extends java.io.Serializable,V extends java.io.Serializable>`
Overrides:
  `size` in class `java.util.AbstractMap<K extends java.io.Serializable,V extends java.io.Serializable>`

#### values

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

Specified by:
  `values` in interface `java.util.Map<K extends java.io.Serializable,V extends java.io.Serializable>`
Overrides:
  `values` in class `java.util.AbstractMap<K extends java.io.Serializable,V extends java.io.Serializable>`

#### contains

    public boolean contains(java.lang.Object value)

Deprecated.
Legacy method.

#### keys

    public java.util.Enumeration<K> keys()

Deprecated.
Legacy method.

#### elements

    public java.util.Enumeration<V> elements()

Deprecated.
Legacy method.