History.java

/*
 *    Copyright (c) 2012 Hai Bison
 *
 *    See the file LICENSE at the root directory of this project for copying
 *    permission.
 */

package group.pals.android.lib.ui.filechooser.utils.history;

import java.util.ArrayList;

import android.os.Parcelable;

/**
 * A history store of any object.
 * 
 * @author Hai Bison
 * 
 * @param <A>
 *            any type
 * @since v2.0 alpha
 */
public interface History<A> extends Parcelable {

    /**
     * Pushes {@code newItem} to the history. If the top item is same as this
     * one, then does nothing.
     * 
     * @param newItem
     *            the new item
     */
    void push(A newItem);

    /**
     * Finds {@code item} and if it exists, removes all items after it.
     * 
     * @param item
     *            {@link A}
     * @since v4.3 beta
     */
    void truncateAfter(A item);

    /**
     * Removes an item.
     * 
     * @param item
     *            {@link A}
     * @since v4.0 beta
     */
    void remove(A item);

    /**
     * Removes all items by a filter.
     * 
     * @param filter
     *            {@link HistoryFilter}
     * @since v4.0 beta
     */
    void removeAll(HistoryFilter<A> filter);

    /**
     * Gets size of the history
     * 
     * @return the size of the history
     */
    int size();

    /**
     * Gets index of item {@code a}
     * 
     * @param a
     *            an item
     * @return index of the {@code a}, or -1 if there is no one
     */
    int indexOf(A a);

    /**
     * Gets previous item of {@code a}
     * 
     * @param a
     *            current item
     * @return the previous item, can be {@code null}
     */
    A prevOf(A a);

    /**
     * Gets next item of {@code a}
     * 
     * @param a
     *            current item
     * @return the next item, can be {@code null}
     */
    A nextOf(A a);

    /**
     * Retrieves all items in this history, in an <i>independent</i> list.
     * 
     * @return list of {@link A}.
     * @since v4.3 beta
     */
    ArrayList<A> items();

    /**
     * Checks if the history is empty or not.
     * 
     * @return {@code true} if this history is empty, {@code false} otherwise.
     * @since v4.3 beta
     */
    boolean isEmpty();

    /**
     * Clears this history.
     * 
     * @since v4.3 beta.
     */
    void clear();

    /**
     * Adds a {@link HistoryListener}
     * 
     * @param listener
     *            {@link HistoryListener}
     * @since v4.0 beta
     */
    void addListener(HistoryListener<A> listener);

    /**
     * Removes a {@link HistoryListener}
     * 
     * @param listener
     *            {@link HistoryListener}
     * @return the removed listener
     * @since v4.0 beta
     */
    void removeListener(HistoryListener<A> listener);

    /**
     * Notifies to all {@link HistoryListener}'s that the history changed.
     */
    void notifyHistoryChanged();
}