org.jgroups.blocks

Class DistributedHashtable

Implemented Interfaces:
Cloneable, MembershipListener, MessageListener

public class DistributedHashtable
extends Hashtable
implements MessageListener, MembershipListener, Cloneable

Provides the abstraction of a java.util.Hashtable that is replicated at several locations. Any change to the hashtable (clear, put, remove etc) will transparently be propagated to all replicas in the group. All read-only methods will always access the local replica.

Both keys and values added to the hashtable 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 DistributedHashtable 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 (using the state exchange funclet StateExchangeFunclet.

Version:
$Id: DistributedHashtable.java,v 1.13 2004/07/30 08:31:14 rds13 Exp $

Authors:
Bela Ban
Alfonso Olias-Sanz

Nested Class Summary

static interface
DistributedHashtable.Notification

Field Summary

protected Log
log
protected Promise
state_promise

Constructor Summary

DistributedHashtable(String groupname, ChannelFactory factory, String properties, boolean persistent, long state_timeout)
Creates a DisttributedHashtable.
DistributedHashtable(String groupname, ChannelFactory factory, String properties, long state_timeout)
Creates a DistributedHashtable
DistributedHashtable(JChannel channel, boolean persistent, long state_timeout)
DistributedHashtable(JChannel channel, long state_timeout)
DistributedHashtable(PullPushAdapter adapter, Serializable id)
DistributedHashtable(PullPushAdapter adapter, Serializable id, long state_timeout)
Uses a user-provided PullPushAdapter to create the dispatcher rather than a Channel.

Method Summary

void
_clear()
Object
_put(Object key, Object value)
void
_putAll(Map m)
Object
_remove(Object key)
void
addNotifier(DistributedHashtable.Notification n)
void
block()
Block sending and receiving of messages until ViewAccepted is called
void
clear()
Clears this hashtable so that it contains no keys
Channel
getChannel()
String
getGroupName()
Address
getLocalAddress()
boolean
getPersistent()
byte[]
getState()
protected void
init(long state_timeout)
static void
main(String[] args)
Object
put(Object key, Object value)
Maps the specified key to the specified value in the hashtable.
void
putAll(Map m)
Copies all of the mappings from the specified Map to this Hashtable These mappings will replace any mappings that this Hashtable had for any of the keys currently in the specified Map.
void
receive(Message msg)
Object
remove(Object key)
Removes the key (and its corresponding value) from the Hashtable.
void
removeNotifier(DistributedHashtable.Notification n)
void
setPersistent(boolean p)
void
setState(byte[] new_state)
void
start(long state_timeout)
Fetches the state
void
stop()
void
suspect(Address suspected_mbr)
Called when a member is suspected
void
viewAccepted(View new_view)
Called by JGroups to notify the target object of a change of membership.

Field Details

log

protected Log log


state_promise

protected Promise state_promise

Constructor Details

DistributedHashtable

public DistributedHashtable(String groupname,
                            ChannelFactory factory,
                            String properties,
                            boolean persistent,
                            long state_timeout)
            throws ChannelException
Creates a DisttributedHashtable. Optionally the contents can be saved to persistemt storage using the PersistenceManager.

Parameters:
groupname - Name of the group to join
factory - Instance of a ChannelFactory to create the channel
properties - Protocol stack properties
persistent - Whether the contents should be persisted
state_timeout - Max number of milliseconds to wait until state is retrieved


DistributedHashtable

public DistributedHashtable(String groupname,
                            ChannelFactory factory,
                            String properties,
                            long state_timeout)
            throws ChannelException
Creates a DistributedHashtable

Parameters:
groupname - 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
state_timeout - The time to wait until state is retrieved in milliseconds. A value of 0 means wait forever.


DistributedHashtable

public DistributedHashtable(JChannel channel,
                            boolean persistent,
                            long state_timeout)
            throws ChannelNotConnectedException,
                   ChannelClosedException


DistributedHashtable

public DistributedHashtable(JChannel channel,
                            long state_timeout)
            throws ChannelNotConnectedException,
                   ChannelClosedException


DistributedHashtable

public DistributedHashtable(PullPushAdapter adapter,
                            Serializable id)


DistributedHashtable

public DistributedHashtable(PullPushAdapter adapter,
                            Serializable id,
                            long state_timeout)
            throws ChannelNotConnectedException,
                   ChannelClosedException
Uses a user-provided PullPushAdapter to create the dispatcher rather than a Channel. If id is non-null, it will be used to register under that id. This is typically used when another building block is already using PullPushAdapter, and we want to add this building block in addition. The id is the used to discriminate between messages for the various blocks on top of PullPushAdapter. If null, we will assume we are the first block created on PullPushAdapter.

Parameters:
adapter - The PullPushAdapter which to use as underlying transport
id - A serializable object (e.g. an Integer) used to discriminate (multiplex/demultiplex) between requests/responses for different building blocks on top of PullPushAdapter.
state_timeout - Max number of milliseconds to wait until state is retrieved

Method Details

_clear

public void _clear()


_put

public Object _put(Object key,
                   Object value)


_putAll

public void _putAll(Map m)

See Also:
java.util.Map.putAll(java.util.Map)


_remove

public Object _remove(Object key)


addNotifier

public void addNotifier(DistributedHashtable.Notification n)


block

public void block()
Block sending and receiving of messages until ViewAccepted is called
Specified by:
block in interface MembershipListener


clear

public void clear()
Clears this hashtable so that it contains no keys


getChannel

public Channel getChannel()


getGroupName

public String getGroupName()


getLocalAddress

public Address getLocalAddress()


getPersistent

public boolean getPersistent()


getState

public byte[] getState()
Specified by:
getState in interface MessageListener


init

protected void init(long state_timeout)
            throws ChannelClosedException,
                   ChannelNotConnectedException


main

public static void main(String[] args)


put

public Object put(Object key,
                  Object value)
Maps the specified key to the specified value in the hashtable. Neither of both parameters can be null

Parameters:
key - - the hashtable key
value - - the value

Returns:
the previous value of the specified key in this hashtable, or null if it did not have one


putAll

public void putAll(Map m)
Copies all of the mappings from the specified Map to this Hashtable These mappings will replace any mappings that this Hashtable had for any of the keys currently in the specified Map.

Parameters:
m - - Mappings to be stored in this map


receive

public void receive(Message msg)
Specified by:
receive in interface MessageListener


remove

public Object remove(Object key)
Removes the key (and its corresponding value) from the Hashtable.

Parameters:
key - - the key to be removed.

Returns:
the value to which the key had been mapped in this hashtable, or null if the key did not have a mapping.


removeNotifier

public void removeNotifier(DistributedHashtable.Notification n)


setPersistent

public void setPersistent(boolean p)


setState

public void setState(byte[] new_state)
Specified by:
setState in interface MessageListener


start

public void start(long state_timeout)
            throws ChannelClosedException,
                   ChannelNotConnectedException
Fetches the state

Parameters:
state_timeout -

Throws:
ChannelClosedException -
ChannelNotConnectedException -


stop

public void stop()


suspect

public void suspect(Address suspected_mbr)
Called when a member is suspected
Specified by:
suspect in interface MembershipListener


viewAccepted

public void viewAccepted(View new_view)
Called by JGroups to notify the target object of a change of membership. No long running actions should be done in this callback in the case of Ensemble, as this would block Ensemble. If some long running action needs to be performed, it should be done in a separate thread (cf. ../Tests/QuoteServer.java).
Specified by:
viewAccepted in interface MembershipListener


Copyright B) 2001,2002 www.jgroups.com . All Rights Reserved.