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
    Modifier and Type | Class and Description
    --- | ---
    `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
    Modifier and Type | Field and Description
    --- | ---
    `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
    Modifier and Type | Method and Description
    --- | ---
    `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.

Copyright © 1998-2009 Bela Ban / Red Hat. All Rights Reserved.