drcl.util.queue
Interface Queue

All Known Subinterfaces:

FiniteQueue, FiniteVSQueue, VariableSizeQueue

All Known Implementing Classes:

FiniteFIFOQueue, FiniteQueueImpl, FiniteVSFIFOQueue, FiniteVSQueueImpl, FiniteVSSimpleQueue, QueueImpl, VariableSizeQueueImpl

public interface Queue

Interface for implementing a queue. Each element in a queue is associated with a key. In general, the elements in a queue is sorted in the ascending order of their keys. Specific types of queue may have different mechanisms to order the elements. "Enqueue" and "dequeue" are two common operations on a queue. An "enqueue" operation inserts an element to the queue based on its mechanism of ordering. A "dequeue" operation removes the first element in the queue.

Base implementation is provided by QueueImpl.

Method Summary

Element[]	_retrieveAll() Returns all the elements in the queue sorted in the ascending order of the key values and the order of enqueues.
boolean	contains(java.lang.Object element_) Returns true if the queue contains the element.
boolean	containsKey(double key_) Returns true if the queue contains the key.
java.lang.Object	dequeue() Dequeues and returns the element with the smallest key.
java.lang.Object	dequeue(double key_) Dequeues and returns the first element with the key matched the argument.
java.lang.String	diag(boolean listElement_) Prints out for diagnosis.
void	enqueue(double key_, java.lang.Object element_) Enqueues the element with the associated key.
void	enqueue(java.lang.Object element_) Associates the element with the largest key in the queue and then enqueues the element.
boolean	enqueueAfter(java.lang.Object previousElement_, java.lang.Object element_) Enqueues the element right after the previousElement_ element and associates the element with a key equal to the previous element's.
boolean	enqueueAt(int pos_, double key_, java.lang.Object element_) Enqueues the element at the position specified with the associated key.
java.lang.Object	firstElement() Returns the first element in the queue, no dequeue is performed.
double	firstKey() Returns the first key in the queue, no dequeue is performed.
java.util.Enumeration	getElementEnumerator()
java.util.Enumeration	getKeyEnumerator()
int	getLength() Returns the current length of the queue.
java.lang.String	info() Prints the content of the queue.
java.lang.String	info(java.lang.String prefix_) Prints the content of the queue.
java.lang.String	info(java.lang.String prefix_, boolean listElement_) Prints the content of the queue.
boolean	isEmpty() Returns true if the queue is empty.
double[]	keys() Returns all the keys in the queue.
java.lang.Object	lastElement() Returns the last element in the queue, no dequeue is performed.
double	lastKey() Returns the last key in the queue, no dequeue is performed.
void	merge(Queue that_) Enqueues the elements in that_ by the order of that_.dequeue().
java.lang.String	oneline() Prints the content of the queue in one line of string.
java.lang.Object	remove(double key_, java.lang.Object element_) Removes the first element that has the same key and equals() the argument.
java.lang.Object	remove(int n_) Removes and returns the nth element in the queue.
java.lang.Object	remove(java.lang.Object element_) Removes the first element that equals() the argument.
void	removeAll(double key_, java.lang.Object element_) Removes all the elements that match both the argument key and element.
void	removeAll(java.lang.Object element_) Removes all the elements that equals() the argument.
void	reset() Empties the queue.
java.lang.Object[]	retrieveAll() Returns all the elements in the queue sorted in the ascending order of the key values and the order of enqueues.
java.lang.Object[]	retrieveAll(double key_) Returns all the elements with the keys matched to the argument.
java.lang.Object	retrieveAt(int n_) Returns the nth element in the queue, no dequeue is performed.
java.lang.Object	retrieveBy(double key_) Returns the first element with the key matched to the argument.
double	retrieveKey(java.lang.Object o_) Returns the key of the first matched element in this queue, Double.NaN if no match is found.
double	retrieveKeyAt(int n_) Returns the nth key in the queue, Double.NaN if the current length of the queue is smaller than (n+1).

Method Detail

reset

public void reset()

Empties the queue.

isEmpty

public boolean isEmpty()

Returns true if the queue is empty.

enqueue

public void enqueue(double key_,
                    java.lang.Object element_)

Enqueues the element with the associated key. The elements in queue are sorted in the ascending order of their associated keys. If same keys appear in the queue, the element is put right after the last element with the same key.

Parameters:

key_ - the associated key.

element_ - the element to be put in the queue.

enqueueAt

public boolean enqueueAt(int pos_,
                         double key_,
                         java.lang.Object element_)

Enqueues the element at the position specified with the associated key. Note that the elements in queue are sorted in the ascending order of their associated keys. Enqueue fails if position and key create a conflict to the above condition.

Parameters:

pos_ - the position.

key_ - the associated key.

element_ - the element to be put in the queue.

Returns:

false if key and position create a conflict.

enqueueAfter

public boolean enqueueAfter(java.lang.Object previousElement_,
                            java.lang.Object element_)

Enqueues the element right after the previousElement_ element and associates the element with a key equal to the previous element's.

Parameters:

previousElement_ - the previous element.

element_ - the element to be put in the queue.

Returns:

false if previousElement_ does not appear.

merge

public void merge(Queue that_)

Enqueues the elements in that_ by the order of that_.dequeue().

enqueue

public void enqueue(java.lang.Object element_)

Associates the element with the largest key in the queue and then enqueues the element. If the queue is originally empty, then key 0.0 is assigned.

dequeue

public java.lang.Object dequeue()

Dequeues and returns the element with the smallest key. If two keys are identical, then first-in-first-out.

Returns:

the element with the smallest key, null if the queue is empty.

dequeue

public java.lang.Object dequeue(double key_)

Dequeues and returns the first element with the key matched the argument.

Returns:

the element with the key matched the argument, null if no key is matched or the queue is empty.

remove

public java.lang.Object remove(java.lang.Object element_)

Removes the first element that equals() the argument.

Returns:

the element found; null if no element is matched.

remove

public java.lang.Object remove(double key_,
                               java.lang.Object element_)

Removes the first element that has the same key and equals() the argument.

Returns:

the element found; null if no element is matched.

removeAll

public void removeAll(java.lang.Object element_)

Removes all the elements that equals() the argument.

removeAll

public void removeAll(double key_,
                      java.lang.Object element_)

Removes all the elements that match both the argument key and element.

remove

public java.lang.Object remove(int n_)

Removes and returns the nth element in the queue. Returns null if the current size of the queue is smaller than (n+1).

firstElement

public java.lang.Object firstElement()

Returns the first element in the queue, no dequeue is performed. Returns null if the queue is empty.

firstKey

public double firstKey()

Returns the first key in the queue, no dequeue is performed. Returns java.lang.Double.NaN if the queue is empty.

lastElement

public java.lang.Object lastElement()

Returns the last element in the queue, no dequeue is performed. Returns null if the queue is empty.

lastKey

public double lastKey()

Returns the last key in the queue, no dequeue is performed. Returns java.lang.Double.NaN if the queue is empty.

retrieveAt

public java.lang.Object retrieveAt(int n_)

Returns the nth element in the queue, no dequeue is performed.

Returns:

null if the current length of the queue is smaller than (n+1).

retrieveKeyAt

public double retrieveKeyAt(int n_)

Returns the nth key in the queue, Double.NaN if the current length of the queue is smaller than (n+1).

retrieveBy

public java.lang.Object retrieveBy(double key_)

Returns the first element with the key matched to the argument. No dequeue is performed.

Returns:

null if no match is found.

retrieveAll

public java.lang.Object[] retrieveAll(double key_)

Returns all the elements with the keys matched to the argument. No dequeue is performed.

retrieveAll

public java.lang.Object[] retrieveAll()

Returns all the elements in the queue sorted in the ascending order of the key values and the order of enqueues.

_retrieveAll

public Element[] _retrieveAll()

Returns all the elements in the queue sorted in the ascending order of the key values and the order of enqueues.

retrieveKey

public double retrieveKey(java.lang.Object o_)

Returns the key of the first matched element in this queue, Double.NaN if no match is found.

contains

public boolean contains(java.lang.Object element_)

Returns true if the queue contains the element.

containsKey

public boolean containsKey(double key_)

Returns true if the queue contains the key.

keys

public double[] keys()

Returns all the keys in the queue. Duplicate keys may appear.

getKeyEnumerator

public java.util.Enumeration getKeyEnumerator()

getElementEnumerator

public java.util.Enumeration getElementEnumerator()

getLength

public int getLength()

Returns the current length of the queue.

info

public java.lang.String info(java.lang.String prefix_,
                             boolean listElement_)

Prints the content of the queue.

Parameters:

prefix_ - prefix of each line when printing.

info

public java.lang.String info()

Prints the content of the queue.

info

public java.lang.String info(java.lang.String prefix_)

Prints the content of the queue.

oneline

public java.lang.String oneline()

Prints the content of the queue in one line of string.

diag

public java.lang.String diag(boolean listElement_)

Prints out for diagnosis.