org.ocap.shared.dvr.navigation
Interface RecordingListIterator


public interface RecordingListIterator

This iterator could be used to traverse entries in a RecordingList. An iterator for lists that allows the programmer to traverse the list in either direction and to obtain the iterator's current position in the list. A RecordingListIterator has no current element; its cursor position always lies between the element that would be returned by a call to previousEntry(), previousEntries(n), nextEntry(),and nextEntries(n), where each traverse backward by 1, n, and forward by 1, n respectively. In a list of length n, there are N+1 valid index values, from 0 to n, inclusive.

        Element(0)   Element(1)   Element(2)   ... Element(n)   
        ^            ^            ^            ^               ^
 Index: 0            1            2            3               N+1
Total failure to traverse the list shall not change the position. When a request to traverses by n entries would result in going beyond the list, it shall traverse as much possible and change the position accordingly. The orders of the entries in the array returned by both nextEntries(n) or previousEntries(n) shall be the same the order maintained within the implementation.


Method Summary
 RecordingRequest getEntry(int index)
          Gets the RecordingRequest object at the specified position.
 int getPosition()
          Gets the current position of the RecordingListIterator.
 int getPosition(RecordingRequest entry)
          Gets the position of a specified recording request in the list.
 RecordingList getRecordingList()
          Gets the recording list corresponding to this RecordingListIterator.
 boolean hasNext()
          Tests if there is a RecordingRequest in the next position in the list.
 boolean hasPrevious()
          Tests if there is a RecordingRequest in the previous position in the list.
 RecordingRequest[] nextEntries(int n)
          Gets the next 'n' RecordingRequest objects in the list.
 RecordingRequest nextEntry()
          Gets the next RecordingRequest object in the list.
 RecordingRequest[] previousEntries(int n)
          Gets the previous 'n' RecordingRequest objects in the list.
 RecordingRequest previousEntry()
          Gets the previous RecordingRequest object in the list.
 void setPosition(int index)
          Sets the current position of the RecordingListIterator.
 void toBeginning()
          Resets the iterator to the beginning of the list, such that hasPrevious() returns false and nextEntry() returns the first RecordingRequest in the list (if the list is not empty).
 void toEnd()
          Sets the iterator to the end of the list, such that hasNext() returns false and previousEntry() returns the last RecordingRequest in the list (if the list is not empty).
 

Method Detail

toBeginning

void toBeginning()
Resets the iterator to the beginning of the list, such that hasPrevious() returns false and nextEntry() returns the first RecordingRequest in the list (if the list is not empty).


toEnd

void toEnd()
Sets the iterator to the end of the list, such that hasNext() returns false and previousEntry() returns the last RecordingRequest in the list (if the list is not empty).


nextEntry

RecordingRequest nextEntry()
Gets the next RecordingRequest object in the list. This method may be called repeatedly to iterate through the list.

Returns:
The RecordingRequest object at the next position in the list.
Throws:
java.util.NoSuchElementException - If the iteration has no next RecordingRequest.

previousEntry

RecordingRequest previousEntry()
Gets the previous RecordingRequest object in the list. This method may be called repeatedly to iterate through the list in reverse order.

Returns:
The RecordingRequest object at the previous position in the list.
Throws:
java.util.NoSuchElementException - If the iteration has no previous RecordingRequest.

hasNext

boolean hasNext()
Tests if there is a RecordingRequest in the next position in the list.

Returns:
true if there is a RecordingRequest in the next position in the list; false otherwise.

hasPrevious

boolean hasPrevious()
Tests if there is a RecordingRequest in the previous position in the list.

Returns:
true if there is a RecordingRequest in the previous position in the list; false otherwise.

nextEntries

RecordingRequest[] nextEntries(int n)
Gets the next 'n' RecordingRequest objects in the list. This method also advances the current position within the list. If the requested number of entries are not available, the remaining elements are returned. If the current position is at the end of the iterator, this method returns an array with length zero.

Parameters:
n - the number of next entries requested.
Returns:
an array containing the next 'n' RecordingRequest object from the current position in the list. If 'n' is zero or negative, a zero-length array shall be returned.

previousEntries

RecordingRequest[] previousEntries(int n)
Gets the previous 'n' RecordingRequest objects in the list. This method also changes the current position within the list. If the requested number of entries are not available, the remaining elements are returned. If the current position is at the beginning of the iterator, this method returns an array with length zero.

Parameters:
n - the number of previous entries requested.
Returns:
an array containing the previous 'n' RecordingRequest object from the current position in the list. If 'n' is zero or negative, a zero-length array shall be returned.

getEntry

RecordingRequest getEntry(int index)
Gets the RecordingRequest object at the specified position. This method does not advance the current position within the list.

Parameters:
index - the position of the RecordingRequest to be retrieved.
Returns:
the RecordingRequest at the specified position.
Throws:
java.lang.IndexOutOfBoundsException - if the index is greater than the size of the list.

getPosition

int getPosition(RecordingRequest entry)
Gets the position of a specified recording request in the list.

Parameters:
entry - The recording request for which the position is sought.
Returns:
The position of the specified recording; -1 if the entry is not found.

getPosition

int getPosition()
Gets the current position of the RecordingListIterator. This would be the position from where the next RecordingRequest will be retrieved when an application calls the nextEntry.

Returns:
the current position of the RecordingListIterator.

setPosition

void setPosition(int index)
                 throws java.lang.IndexOutOfBoundsException
Sets the current position of the RecordingListIterator. This would be the position from where the next RecordingRequest will be retrieved when an application calls the nextEntry.

Parameters:
index - the current position of the RecordingListIterator would be set to this value.
Throws:
java.lang.IndexOutOfBoundsException - if the index is greater than the size of the list.

getRecordingList

RecordingList getRecordingList()
Gets the recording list corresponding to this RecordingListIterator.

Returns:
the RecordingList corresponding to this iterator.