Application: gvSIG desktop » gvSIG projections

package org.gvsig.proj.swing;

import java.util.Iterator;

import java.util.List;

/**

 * Stores a collection of objects, removing the oldest objects when the size

 * of the collection grows beyond the allowed {@link #getMaxSize() maxSize}.

 * 

 * @author Cesar Martinez Izquierdo

 *

 * @param <E> The type of object to be stored

 */

public interface RecentHistory<E> extends Iterable<E> {

        /**

         * Gets the maximum size allowed by this history collection.

         * 

         * @return

         */

        int getMaxSize();

    /**

     * Returns the number of elements in this collection.

     *

     * @return the number of elements in this collection

     */

    int size();

    /**

     * Returns <tt>true</tt> if this collection contains no elements.

     *

     * @return <tt>true</tt> if this collection contains no elements

     */

    boolean isEmpty();

    /**

     * Returns <tt>true</tt> if this collection contains the specified element.

     * More formally, returns <tt>true</tt> if and only if this collection

     * contains at least one element <tt>e</tt> such that

     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.

     *

     * @param o element whose presence in this collection is to be tested

     * @return <tt>true</tt> if this collection contains the specified

     *         element

     * @throws ClassCastException if the type of the specified element

     *         is incompatible with this collection

     *         (<a href="#optional-restrictions">optional</a>)

     * @throws NullPointerException if the specified element is null and this

     *         collection does not permit null elements

     *         (<a href="#optional-restrictions">optional</a>)

     */

    boolean contains(Object o);

        /**

         * Adds an element to the history. If the history grows beyond

         * the allowed {@link #getMaxSize() maxSize}, then the oldest

         * object of the collection is removed from the history. If the

         * added element was already present in the history, its age is

         * updated to be considered the most recent object in the collection.

         */

        boolean add(E element);

        /**

         * Returns an iterator over the elements in this collection, ordered according

         * the age of the element in the collection (newer objects come first).

         * 

         * Concurrent changes in the RecentHistory instance do not affect nor modify

         * the returned iterator.  

         * @return

         */

        Iterator<E> iterator();

        /**

         * Returns the elements in this collection as an unmodifiable List,

         * ordered according the age of the element in the collection

         * (newer objects come first).

         * 

         * Concurrent changes in the RecentHistory instance do not affect nor modify

         * the returned list. 

         *   

         * @return

         */

        List<E> toList();

}