edu.unm.cs.cs351.tdrl.f07.p2
Interface FindableQueue<S,T extends Comparable<T> & Findable<S>>

public interface FindableQueue<S,T extends Comparable<T> & Findable<S>>

A FindableQueue is a priority queue that additionally supports fast lookup/removal of elements by element key (via the Findable interface). Separating the key value from the object identity allows us to look up copies of an object of unknown priority, to re-insert an object under a new priority, or, in general, to use only partial information about the object (e.g., an order ID code) to look it up. Note that a standard queue-like behavior, in which the entire object ID is used as a lookup value, can be obtained by defining Findable.getKey() simply to return this.

A FindableQueue is a generic type, parameterized by two type parameters, T and S. T represents the type of the objects being stored in the queue, while S represents the type of object used as the key used for looking up arbitrary entries in the queue.

FindableQueue objects sort their contents into increasing priority order. That is, the first element of the queue is the one with the smallest priority: the first element of the queue is the element x such that for every y in the queue, x.compareTo(y)<=0. (That is,x is less than or equal to every y.)

Objects of this type MUST NOT consume more than amortized O(n) space for a queue containing n objects.

Version:

1.0

Author:

terran

See Also:

Comparable, Findable

Method Summary

boolean	contains(T item) true iff this queue contains the object item, as located via its key (Findable.getKey()).
T	first() Return the first item, by priority, from the queue.
T	get(T element) This looks up an arbitrary object in the queue, according to its Findable.getKey() method, and returns a reference to the object stored in the queue.
void	insert(T element) Insert an object into the queue, ordered according to its priority via the natural order.
boolean	isEmpty() Test whether the queue contains any elements.
int	length() Get the number of elements currently in this queue.
T	pop() Remove and return the first item, by priority, from the queue.
T	remove(T element) Remove an element by reference.

Method Detail

contains

boolean contains(T item)

true iff this queue contains the object item, as located via its key (Findable.getKey()).

The semantics of this method are equivalent to the following. Assume that the queue is implemented in terms of a List named _heap, then a naive implementation of contains(Comparable) would be:

 private List _heap;
 public boolean contains(T item) {
   for (T qElem : _heap) {
     if (qElem.getKey().equals(item.getKey())) {
       return true;
     }
   }
   return false;
 }
 

Note that this is only semantically equivalent to the required contains method -- it produces the same output, but does not run in the required asymptotic time bound (see below). In practice, objects of type FindableQueue will probably not use a simple list for their heap representation and definitely will not use a linear scan to locate an item by key.

This method MUST run in amortized O(1) time.

Parameters:

item - Object to look up in the queue.

Returns:

true iff this queue contains item

Throws:

IllegalArgumentException - iff item==null.

length

int length()

Get the number of elements currently in this queue.

This method MUST run in O(1) time.

Returns:

Number of elements in the queue.

get

T get(T element)

This looks up an arbitrary object in the queue, according to its Findable.getKey() method, and returns a reference to the object stored in the queue.

Semantically, this method is similar to contains(Comparable), in that it is equivalent to scanning through the priority queue, looking for any queue entry that is equivalent to element, according to the Findable.getKey() method. As with contains(Comparable), however, a linear scan will not meet the asymptotic time requirements of this object.

This method MUST run in amortized O(1) time.

Parameters:

element - Item to search for in the queue.

Returns:

Reference to the object stored in the queue, if present, or null if no such object is present in the queue.

Throws:

IllegalArgumentException - iff element==null.

isEmpty

boolean isEmpty()

Test whether the queue contains any elements.

This method MUST run in O(1) time.

Returns:

true iff the queue contains no elements.

insert

void insert(T element)

Insert an object into the queue, ordered according to its priority via the natural order. If the object is already present in the queue, according to the Findable.getKey() method, then the previous copy is removed from the queue before this copy is inserted.

null objects are not allowed in these queues, so this prevents their insertion by generating an IllegalArgumentException.

This method MUST run in O(log(n)) time for a queue containing n elements.

Parameters:

element - Item to insert into the queue in priority order

Throws:

IllegalArgumentException - iff element==null

first

T first()

Return the first item, by priority, from the queue. This does not alter the state of the queue (i.e., does not delete anything from the queue), merely returns a reference to the first item. Returns null if the queue is currently empty.

This method MUST run in O(1) time.

Returns:

First element of the queue

pop

T pop()

Remove and return the first item, by priority, from the queue. Unlike first(), this does change the state of the queue, by removing the first element from the queue and decreasing the queue length by one. Returns null if the queue is currently empty.

This method MUST run in O(log(n)) time for a queue containing n elements.

Returns:

First element of the queue, or null if the queue is currently empty.

remove

T remove(T element)

Remove an element by reference. This uses the Findable.getKey() method to locate the element in the queue and then removes it from the queue, maintaining priority order among all other elements of the queue. It returns a reference to the removed item (i.e., the item that was actually found in the queue, not the argument to this method). If the requested element is not currently in the queue, this returns null without modifying the queue.

This method MUST run in O(log(n)) time for a queue containing n elements.

Parameters:

element - Element to remove from the queue.

Returns:

Original record stored in the queue

Throws:

IllegalArgumentException - iff element==null.