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

Nested Classes
`static interface` `DistributedQueue.Notification`

### Field Summary

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

Constructors
Constructor and Description
`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

Methods
`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)