org.jgroups.blocks
Class DistributedQueue

java.lang.Object
  org.jgroups.blocks.DistributedQueue

All Implemented Interfaces:

java.lang.Cloneable, MembershipListener, MessageListener

public class DistributedQueue
extends java.lang.Object
implements MessageListener, MembershipListener, java.lang.Cloneable

Provides the abstraction of a java.util.LinkedList that is replicated at several locations. Any change to the list (reset, add, 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 list must be serializable, the reason being that they will be sent across the network to all replicas of the group. An instance of this class will contact an existing member of the group to fetch its initial state. Beware to use a total protocol on initialization or elements would not be in same order on all replicas.

Author:

Romuald du Song

Nested Class Summary

static interface

DistributedQueue.Notification

Field Summary

protected Channel	channel
protected RpcDispatcher	disp
protected java.lang.String	groupname
protected java.util.LinkedList	internalQueue
protected Log	logger
protected java.util.Vector	members
protected java.lang.Object	mutex
protected java.util.Vector	notifs
protected boolean	stopped

Constructor Summary

DistributedQueue(JChannel channel)

DistributedQueue(PullPushAdapter adapter, java.io.Serializable id)
Uses a user-provided PullPushAdapter to create the dispatcher rather than a Channel.

DistributedQueue(java.lang.String groupname, ChannelFactory factory, java.lang.String properties, long state_timeout)
Creates a DistributedQueue

Method Summary

void	_add(java.lang.Object value)
void	_addAll(java.util.Collection c)
void	_addAtHead(java.lang.Object value)
protected void	_private_reset()
java.lang.Object	_remove()
void	_reset()
void	add(java.lang.Object value) Add the speficied element at the bottom of the queue
void	addAll(java.util.Collection values) Add the speficied collection to the top of the queue.
void	addAtHead(java.lang.Object value) Add the speficied element at the top of the queue
void	addNotifier(DistributedQueue.Notification n)
void	block() Block sending and receiving of messages until ViewAccepted is called
protected void	checkResult(RspList rsp, java.lang.Object retval)
Channel	getChannel()
java.util.Vector	getContents()
Address	getLocalAddress()
byte[]	getState() Answers the group state; e.g., when joining.
protected void	init()
static void	main(java.lang.String[] args)
java.lang.Object	peek() returns the first object on the queue, without removing it.
void	receive(Message msg) Called when a message is received.
java.lang.Object	remove() Try to return the first objet in the queue.It does not wait for an object.
java.lang.Object	remove(long timeout)
void	removeNotifier(DistributedQueue.Notification n)
void	reset()
void	setState(byte[] new_state) Sets the group state; e.g., when joining.
int	size()
void	start(long state_timeout)
void	stop()
void	suspect(Address suspected_mbr) Called when a member is suspected
java.lang.String	toString()
void	viewAccepted(View new_view) Called when a change in membership has occurred.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

logger

protected Log logger

mutex

protected final java.lang.Object mutex

stopped

protected boolean stopped

internalQueue

protected java.util.LinkedList internalQueue

channel

protected Channel channel

disp

protected RpcDispatcher disp

groupname

protected java.lang.String groupname

notifs

protected java.util.Vector notifs

members

protected java.util.Vector members

Constructor Detail

DistributedQueue

public DistributedQueue(java.lang.String groupname,
                        ChannelFactory factory,
                        java.lang.String properties,
                        long state_timeout)
                 throws ChannelException

Creates a DistributedQueue

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.

Throws:

ChannelException

DistributedQueue

public DistributedQueue(JChannel channel)

DistributedQueue

public DistributedQueue(PullPushAdapter adapter,
                        java.io.Serializable id)

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. The caller needs to call start(), before using the this block. It gives the opportunity for the caller to register as a lessoner for Notifications events.

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.

Method Detail

init

protected final void init()

start

public final void start(long state_timeout)
                 throws ChannelClosedException,
                        ChannelNotConnectedException

Throws:

ChannelClosedException

ChannelNotConnectedException

getLocalAddress

public Address getLocalAddress()

getChannel

public Channel getChannel()

addNotifier

public void addNotifier(DistributedQueue.Notification n)

removeNotifier

public void removeNotifier(DistributedQueue.Notification n)

stop

public void stop()

add

public void add(java.lang.Object value)

Add the speficied element at the bottom of the queue

Parameters:

value -

addAtHead

public void addAtHead(java.lang.Object value)

Add the speficied element at the top of the queue

Parameters:

value -

addAll

public void addAll(java.util.Collection values)

Add the speficied collection to the top of the queue. Elements are added in the order that they are returned by the specified collection's iterator.

Parameters:

values -

getContents

public java.util.Vector getContents()

size

public int size()

peek

public java.lang.Object peek()

returns the first object on the queue, without removing it. If the queue is empty this object blocks until the first queue object has been added

Returns:

the first object on the queue

reset

public void reset()

checkResult

protected void checkResult(RspList rsp,
                           java.lang.Object retval)

remove

public java.lang.Object remove()

Try to return the first objet in the queue.It does not wait for an object.

Returns:

the first object in the queue or null if none were found.

remove

public java.lang.Object remove(long timeout)

Parameters:

timeout - The time to wait until an entry is retrieved in milliseconds. A value of 0 means wait forever.

Returns:

the first object in the queue or null if none were found

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

_add

public void _add(java.lang.Object value)

_addAtHead

public void _addAtHead(java.lang.Object value)

_reset

public void _reset()

_private_reset

protected void _private_reset()

_remove

public java.lang.Object _remove()

_addAll

public void _addAll(java.util.Collection c)

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

main

public static void main(java.lang.String[] args)