/**
 * The PriorityQueue interface specifies a collection of prioritized elements 
 * that supports arbitrary additions and removals in order of priority.
 * A prioritized element, or item, is an element together with a key.
 *
 * @version     1.1    October 25, 1999
 * @author      Franck van Breugel
 */
public interface PriorityQueue 
{
    /** 
     * Returns the size of this priority queue. 
     * @return The size of this priority queue.
     */
    int size();

    /** 
     * Tests if this priority queue is empty. 
     * @return true if this priority queue is empty, false otherwise.
     */
    boolean isEmpty();

    /**
     * Adds the specified element with the specified key to the priority queue.
     * @param key Key of element to be added.
     * @param element Element to be added.
     */
    void insertItem(Object key, Object element);

    /**
     * Returns an element with the smallest key in this priority queue.
     * Throws an EmptyContainerException if this priority queue is empty.
     * @return Element with the smallest key.
     * @exception EmptyContainerException if this priority queue is empty.
     */
    Object minElement() throws EmptyContainerException;

    /**
     * Returns the smallest key in this priority queue.
     * Throws an EmptyContainerException if this priority queue is empty.
     * @return The smallest key.
     * @exception EmptyContainerException if this priority queue is empty.
     */
    Object minKey() throws EmptyContainerException;

    /**
     * Removes an item with the smallest key from this priority queue
     * and returns the element of the item.
     * Throws an EmptyContainerException if this priority queue is empty.
     * @return Element of an item with the smallest key.
     * @exception EmptyContainerException if this priority queue is empty.
     */
    Object removeMinElement() throws EmptyContainerException;
}