/*
 * Created on Apr 24, 2005
 */
package stockportfolio;

/** Interface for a queue of objects.  
 * It is an error for the queue to contain null.
 * Concrete classes should include at least a zero-argument constructor which
 * creates an empty queue.
 */
public interface IQueue {
    
    /** Push a new object on the queue.
     * 
     * @param newValue a non-null object
     * @return true iff the operation succeeded.  In this case, the newValue
     * is now the top of the queue and the previous top is just below it;
     * the size of the queue has increased by 1.
     * @throws IllegalArgumentException if the new value is null.
     */
    boolean enqueue(Object newValue);
    
    /** Remove an object from the queue.
     * 
     * @return a reference to the front of the queue, 
     * or null if the queue is empty.  The size
     * of the queue has decreased by 1.  Note that the reference is to the
     * actual enqueued object, not to a clone.
     */
    Object dequeue();
    
    /** Look at the front of the queue. The 
     * queue itself is unchanged.
     * 
     * @return the front of the queue, or null if the queue is empty.  Note that the reference is to the
     * actual enqueued object, not to a clone.
     */
    Object front();
    
    /** Tell whether the queue is empty.
     * 
     * @return true iff the queue is empty (has size 0).
     */
    boolean isEmpty();
    
    /** Tell whether the queue is full.
     * 
     * @return true iff the queue is full, i.e., whether it is possible
     * to another another object to it.
     */
    boolean isFull();
    
    /** Tells how many objects are currently in the queue.
     * @return the number of objects in the queue, always >= 0
     */
    int size();

}