1: /** An interface for the ADT list.
2: Entries in a list have positions that begin with 1.
3: @author Frank M. Carrano
4: @author Timothy M. Henry
5: @version 4.0
6: */
7: public interface ListInterface<T>
8: {
9: /** Adds a new entry to the end of this list.
10: Entries currently in the list are unaffected.
11: The list's size is increased by 1.
12: @param newEntry The object to be added as a new entry. */
13: public void add(T newEntry);
14:
15: /** Adds a new entry at a specified position within this list.
16: Entries originally at and above the specified position
17: are at the next higher position within the list.
18: The list's size is increased by 1.
19: @param newPosition An integer that specifies the desired
20: position of the new entry.
21: @param newEntry The object to be added as a new entry.
22: @throws IndexOutOfBoundsException if either
23: newPosition < 1 or newPosition > getLength() + 1. */
24: public void add(int newPosition, T newEntry);
25:
26: /** Removes the entry at a given position from this list.
27: Entries originally at positions higher than the given
28: position are at the next lower position within the list,
29: and the list's size is decreased by 1.
30: @param givenPosition An integer that indicates the position of
31: the entry to be removed.
32: @return A reference to the removed entry.
33: @throws IndexOutOfBoundsException if either
34: givenPosition < 1 or givenPosition > getLength(). */
35: public T remove(int givenPosition);
36:
37: /** Removes all entries from this list. */
38: public void clear();
39:
40: /** Replaces the entry at a given position in this list.
41: @param givenPosition An integer that indicates the position of
42: the entry to be replaced.
43: @param newEntry The object that will replace the entry at the
44: position givenPosition.
45: @return The original entry that was replaced.
46: @throws IndexOutOfBoundsException if either
47: givenPosition < 1 or givenPosition > getLength(). */
48: public T replace(int givenPosition, T newEntry);
49:
50: /** Retrieves the entry at a given position in this list.
51: @param givenPosition An integer that indicates the position of
52: the desired entry.
53: @return A reference to the indicated entry.
54: @throws IndexOutOfBoundsException if either
55: givenPosition < 1 or givenPosition > getLength(). */
56: public T getEntry(int givenPosition);
57:
58: /** Retrieves all entries that are in this list in the order in which
59: they occur in the list.
60: @return A newly allocated array of all the entries in the list.
61: Note: If the list is empty, the returned array is empty. */
62: public T[] toArray();
63:
64: /** Sees whether this list contains a given entry.
65: @param anEntry The object that is the desired entry.
66: @return True if the list contains anEntry, or false if not. */
67: public boolean contains(T anEntry);
68:
69: /** Gets the length of this list.
70: @return The integer number of entries currently in the list. */
71: public int getLength();
72:
73: /** Sees whether this list is empty.
74: @return True if the list is empty, or false if not. */
75: public boolean isEmpty();
76: } // end ListInterface