org.ocap.shared.dvr.navigation.RecordingList Maven / Gradle / Ivy

package org.ocap.shared.dvr.navigation;

import org.ocap.shared.dvr.RecordingRequest;
import javax.tv.locator.Locator;
import javax.tv.locator.InvalidLocatorException;

/**
 * RecordingList represents a list of recordings.
 */
public interface RecordingList
{

    /**
     * Creates a new RecordingList object that is a subset of
     * this list, based on the conditions specified by a
     * RecordingListFilter object. This method may be used
     * to generate increasingly specialized lists of
     * RecordingRequest objects based on multiple filtering
     * criteria. If the filter is null, the resulting
     * RecordingList will be a duplicate of this list.
     * Note that the accept method of the given
     * RecordingListFilter will be invoked for each
     * RecordingRequest to be filtered using the same
     * application thread that invokes this method.
     *
     * @param filter A filter constraining the requested
     * recording list, or null.
     * @return A RecordingList object created based on the
     * specified filtering rules.
     */
    public RecordingList filterRecordingList(RecordingListFilter filter);

    /**
     * Generates an iterator on the RecordingRequest elements
     * in this list.
     *
     * @return A RecordingListIterator on the
     * RecordingRequests in this list.
     */
    public RecordingListIterator createRecordingListIterator();

    /**
     * Tests if the indicated RecordingRequest object is
     * contained in the list.
     *
     * @param entry The RecordingRequest object for which
     * to search.
     * @return true if the specified
     * RecordingRequest is a member of the list;
     * false otherwise.
     */
    public boolean contains(RecordingRequest entry);

    /**
     * Reports the position of the first occurrence of the indicated
     * RecordingRequest object in the list.
     *
     * @param entry The RecordingRequest object for which
     * to search.
     * @return The index of the first occurrence of the entry,
     * or -1 if entry is not contained in the list.
     */
    public int indexOf(RecordingRequest entry);

    /**
     * Reports the number of RecordingRequest objects in the list.
     *
     * @return The number of RecordingRequest objects in the list.
     */
    public int size();

    /**
     * Reports the RecordingRequest at the specified index
     * position.
     *
     * @param index A position in the RecordingList.
     * @return The RecordingRequest at the specified index.
     * @throws java.lang.IndexOutOfBoundsException If
     * index < 0 or index > size()-1.
     */
    public RecordingRequest getRecordingRequest(int index);

    /**
    * Creates a new RecordingList that contains all the
    * elements of this list sorted according to the criteria specified
    * by a RecordingListComparator. 
    * 
    * @param sortCriteria the sort criteria to be applied to sort the
    * entries in the recording list.
    *
    * @return A sorted copy of the recording list.
    */
    public RecordingList sortRecordingList(
            RecordingListComparator sortCriteria);

}