util
Class SortedQueue<E>

java.lang.Object
  extended by java.util.AbstractCollection<E>
      extended by java.util.AbstractQueue<E>
          extended by util.SortedQueue<E>
Type Parameters:
E - the type of elements held in this collection
All Implemented Interfaces:
java.lang.Iterable<E>, java.util.Collection<E>, java.util.Queue<E>

public class SortedQueue<E>
extends java.util.AbstractQueue<E>

An unbounded sorted queue able to update its elements. This queue grants the correct order also when the elements change their ordering.

The elements of the sorted queue are ordered according to their natural ordering, or by a Comparator provided at queue construction time, depending on which constructor is used. A sorted queue does not permit null elements. A sorted queue relying on natural ordering also does not permit insertion of non-comparable objects (doing so may result in ClassCastException).

The head of this queue is the smallest element with respect to the specified ordering. If there are more smallest elements the first inserted will be the head of the queue. The queue retrieval operations poll, remove and peek search the howl queue to find the current smallest element.

This class and its iterator implement all of the optional methods of the Collection and Iterator interfaces. The Iterator provided in method iterator() is guaranteed to traverse the elements of the sorted queue in the insertion order not the imposed natural ordering. If you need ordered traversal, consider using Arrays.sort(pq.toArray()).

Note that this implementation is not synchronized. Multiple threads should not access a SortedQueue instance concurrently if any of the threads modifies the queue.

Implementation note: this implementation provides constant time for enqueing methods (offer and add) and testing methods (size and isEmpty) and linear time for the retrieval methods (poll, remove, peek, element and contains);
This class is an extension to the Java Collections Framework.

Author:
eden06

Constructor Summary
SortedQueue()
          Creates a SortedQueue that orders its elements according to their natural ordering.
SortedQueue(java.util.Collection<E> c)
          Creates a SortedQueue containing the elements in the specified collection.
SortedQueue(java.util.Comparator<? super E> comparator)
          Creates a SortedQueue with the specified initial capacity that orders its elements according to the specified comparator.
SortedQueue(java.util.PriorityQueue<E> p)
          Creates a SortedQueue containing the elements in the specified priority queue.
SortedQueue(SortedQueue<E> s)
          Creates a SortedQueue containing the elements in the specified sorted queue.
SortedQueue(java.util.SortedSet<E> s)
          Creates a SortedQueue containing the elements in the specified sorted set.
 
Method Summary
 void clear()
           
 java.util.Comparator<? super E> comparator()
          Returns the comparator used to order the elements in this queue, or null if this queue is sorted according to the natural ordering of its elements.
 boolean isEmpty()
           
 java.util.Iterator<E> iterator()
          Returns an iterator over the elements of this queue.
 boolean offer(E value)
          Inserts the specified element into this priority queue.
 E peek()
          Returns but retains the smallest element in the queue.
 E poll()
          Returns and removes the smallest element in the queue.
 int size()
           
 
Methods inherited from class java.util.AbstractQueue
add, addAll, element, remove
 
Methods inherited from class java.util.AbstractCollection
contains, containsAll, remove, removeAll, retainAll, toArray, toArray, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Collection
contains, containsAll, equals, hashCode, remove, removeAll, retainAll, toArray, toArray
 

Constructor Detail

SortedQueue

public SortedQueue()
Creates a SortedQueue that orders its elements according to their natural ordering.


SortedQueue

public SortedQueue(java.util.Comparator<? super E> comparator)
Creates a SortedQueue with the specified initial capacity that orders its elements according to the specified comparator.

Parameters:
comparator - the comparator that will be used to order this sorted queue. If null, the natural ordering of the elements will be used

SortedQueue

public SortedQueue(java.util.Collection<E> c)
Creates a SortedQueue containing the elements in the specified collection. If the specified collection is an instance of a SortedSet,a PriorityQueue or another SortedSet, this sorted queue will be ordered according to the same ordering. Otherwise, this priority queue will be ordered according to the natural ordering of its elements.

Parameters:
c - the collection whose elements are to be placed into this priority queue
Throws:
java.lang.ClassCastException - if elements of the specified collection cannot be compared to one another according to the sorted queue's ordering
java.lang.NullPointerException - if the specified collection or any of its elements are null

SortedQueue

public SortedQueue(java.util.SortedSet<E> s)
Creates a SortedQueue containing the elements in the specified sorted set. This sorted queue will be ordered according to the same ordering as the given sorted set.

Parameters:
s - the sorted set whose elements are to be placed into this sorted queue
Throws:
java.lang.ClassCastException - if elements of c cannot be compared to one another according to sorted set's ordering
java.lang.NullPointerException - if the specified sorted set or any of its elements are null

SortedQueue

public SortedQueue(java.util.PriorityQueue<E> p)
Creates a SortedQueue containing the elements in the specified priority queue. This sorted queue will be ordered according to the same ordering as the given priority queue.

Parameters:
p - the priority queue whose elements are to be placed into this sorted queue
Throws:
java.lang.ClassCastException - if elements of c cannot be compared to one another according to p's ordering
java.lang.NullPointerException - if the specified priority queue or any of its elements are null

SortedQueue

public SortedQueue(SortedQueue<E> s)
Creates a SortedQueue containing the elements in the specified sorted queue. This sorted queue will be ordered according to the same ordering as the given sorted queue.

Parameters:
s - the sorted queue whose elements are to be placed into this sorted queue
Throws:
java.lang.ClassCastException - if elements of c cannot be compared to one another according to sorted queue's ordering
java.lang.NullPointerException - if the specified sorted queue or any of its elements are null
Method Detail

iterator

public java.util.Iterator<E> iterator()
Returns an iterator over the elements of this queue. The iterator will return the elements only in the insertion order.

Specified by:
iterator in interface java.lang.Iterable<E>
Specified by:
iterator in interface java.util.Collection<E>
Specified by:
iterator in class java.util.AbstractCollection<E>
See Also:
AbstractCollection.iterator()

size

public int size()
Specified by:
size in interface java.util.Collection<E>
Specified by:
size in class java.util.AbstractCollection<E>
See Also:
AbstractCollection.size()

offer

public boolean offer(E value)
Inserts the specified element into this priority queue.

Throws:
java.lang.ClassCastException - if the given element is not comparable
See Also:
Queue.offer(java.lang.Object)

peek

public E peek()
Returns but retains the smallest element in the queue. This method iterates over all elements to find the smallest one. If there are two smallest elements the first one (according to the insertion order) will be selected.
Note: This operation needs O(n) time.

See Also:
Queue.peek()

poll

public E poll()
Returns and removes the smallest element in the queue. This method iterates over all elements to find the smallest one. If there are two smallest elements the first one (according to the insertion order) will be selected.
Note: This operation needs O(n) time.

See Also:
Queue.poll()

clear

public void clear()
Specified by:
clear in interface java.util.Collection<E>
Overrides:
clear in class java.util.AbstractQueue<E>
See Also:
AbstractQueue.clear()

isEmpty

public boolean isEmpty()
Specified by:
isEmpty in interface java.util.Collection<E>
Overrides:
isEmpty in class java.util.AbstractCollection<E>
See Also:
AbstractCollection.isEmpty()

comparator

public java.util.Comparator<? super E> comparator()
Returns the comparator used to order the elements in this queue, or null if this queue is sorted according to the natural ordering of its elements.

Returns:
the comparator used to order this queue, or null if this queue is sorted according to the natural ordering of its elements