001: /*
002: * @(#)ListIterator.java 1.23 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.util;
029:
030: /**
031: *
032: * An iterator for lists that allows the programmer
033: * to traverse the list in either direction, modify
034: * the list during iteration, and obtain the iterator's
035: * current position in the list. A <TT>ListIterator</TT>
036: * has no current element; its <I>cursor position</I> always
037: * lies between the element that would be returned by a call
038: * to <TT>previous()</TT> and the element that would be
039: * returned by a call to <TT>next()</TT>. In a list of
040: * length <TT>n</TT>, there are <TT>n+1</TT> valid
041: * index values, from <TT>0</TT> to <TT>n</TT>, inclusive.
042: * <PRE>
043: *
044: * Element(0) Element(1) Element(2) ... Element(n)
045: * ^ ^ ^ ^ ^
046: * Index: 0 1 2 3 n+1
047: *
048: * </PRE>
049: * <P>
050: * Note that the {@link #remove} and {@link #set(Object)} methods are
051: * <i>not</i> defined in terms of the cursor position; they are defined to
052: * operate on the last element returned by a call to {@link #next} or {@link
053: * #previous()}.
054: * <P>
055: * This interface is a member of the
056: * <a href="{@docRoot}/../guide/collections/index.html">
057: * Java Collections Framework</a>.
058: *
059: * @author Josh Bloch
060: * @version 1.16, 02/02/00
061: * @see Collection
062: * @see List
063: * @see Iterator
064: * @see Enumeration
065: * @since 1.2
066: */
067: public interface ListIterator extends Iterator {
068: // Query Operations
069:
070: /**
071: * Returns <tt>true</tt> if this list iterator has more elements when
072: * traversing the list in the forward direction. (In other words, returns
073: * <tt>true</tt> if <tt>next</tt> would return an element rather than
074: * throwing an exception.)
075: *
076: * @return <tt>true</tt> if the list iterator has more elements when
077: * traversing the list in the forward direction.
078: */
079: boolean hasNext();
080:
081: /**
082: * Returns the next element in the list. This method may be called
083: * repeatedly to iterate through the list, or intermixed with calls to
084: * <tt>previous</tt> to go back and forth. (Note that alternating calls
085: * to <tt>next</tt> and <tt>previous</tt> will return the same element
086: * repeatedly.)
087: *
088: * @return the next element in the list.
089: * @exception NoSuchElementException if the iteration has no next element.
090: */
091: Object next();
092:
093: /**
094: * Returns <tt>true</tt> if this list iterator has more elements when
095: * traversing the list in the reverse direction. (In other words, returns
096: * <tt>true</tt> if <tt>previous</tt> would return an element rather than
097: * throwing an exception.)
098: *
099: * @return <tt>true</tt> if the list iterator has more elements when
100: * traversing the list in the reverse direction.
101: */
102: boolean hasPrevious();
103:
104: /**
105: * Returns the previous element in the list. This method may be called
106: * repeatedly to iterate through the list backwards, or intermixed with
107: * calls to <tt>next</tt> to go back and forth. (Note that alternating
108: * calls to <tt>next</tt> and <tt>previous</tt> will return the same
109: * element repeatedly.)
110: *
111: * @return the previous element in the list.
112: *
113: * @exception NoSuchElementException if the iteration has no previous
114: * element.
115: */
116: Object previous();
117:
118: /**
119: * Returns the index of the element that would be returned by a subsequent
120: * call to <tt>next</tt>. (Returns list size if the list iterator is at the
121: * end of the list.)
122: *
123: * @return the index of the element that would be returned by a subsequent
124: * call to <tt>next</tt>, or list size if list iterator is at end
125: * of list.
126: */
127: int nextIndex();
128:
129: /**
130: * Returns the index of the element that would be returned by a subsequent
131: * call to <tt>previous</tt>. (Returns -1 if the list iterator is at the
132: * beginning of the list.)
133: *
134: * @return the index of the element that would be returned by a subsequent
135: * call to <tt>previous</tt>, or -1 if list iterator is at
136: * beginning of list.
137: */
138: int previousIndex();
139:
140: // Modification Operations
141:
142: /**
143: * Removes from the list the last element that was returned by
144: * <tt>next</tt> or <tt>previous</tt> (optional operation). This call can
145: * only be made once per call to <tt>next</tt> or <tt>previous</tt>. It
146: * can be made only if <tt>ListIterator.add</tt> has not been called after
147: * the last call to <tt>next</tt> or <tt>previous</tt>.
148: *
149: * @exception UnsupportedOperationException if the <tt>remove</tt>
150: * operation is not supported by this list iterator.
151: * @exception IllegalStateException neither <tt>next</tt> nor
152: * <tt>previous</tt> have been called, or <tt>remove</tt> or
153: * <tt>add</tt> have been called after the last call to *
154: * <tt>next</tt> or <tt>previous</tt>.
155: */
156: void remove();
157:
158: /**
159: * Replaces the last element returned by <tt>next</tt> or
160: * <tt>previous</tt> with the specified element (optional operation).
161: * This call can be made only if neither <tt>ListIterator.remove</tt> nor
162: * <tt>ListIterator.add</tt> have been called after the last call to
163: * <tt>next</tt> or <tt>previous</tt>.
164: *
165: * @param o the element with which to replace the last element returned by
166: * <tt>next</tt> or <tt>previous</tt>.
167: * @exception UnsupportedOperationException if the <tt>set</tt> operation
168: * is not supported by this list iterator.
169: * @exception ClassCastException if the class of the specified element
170: * prevents it from being added to this list.
171: * @exception IllegalArgumentException if some aspect of the specified
172: * element prevents it from being added to this list.
173: * @exception IllegalStateException if neither <tt>next</tt> nor
174: * <tt>previous</tt> have been called, or <tt>remove</tt> or
175: * <tt>add</tt> have been called after the last call to
176: * <tt>next</tt> or <tt>previous</tt>.
177: */
178: void set(Object o);
179:
180: /**
181: * Inserts the specified element into the list (optional operation). The
182: * element is inserted immediately before the next element that would be
183: * returned by <tt>next</tt>, if any, and after the next element that
184: * would be returned by <tt>previous</tt>, if any. (If the list contains
185: * no elements, the new element becomes the sole element on the list.)
186: * The new element is inserted before the implicit cursor: a subsequent
187: * call to <tt>next</tt> would be unaffected, and a subsequent call to
188: * <tt>previous</tt> would return the new element. (This call increases
189: * by one the value that would be returned by a call to <tt>nextIndex</tt>
190: * or <tt>previousIndex</tt>.)
191: *
192: * @param o the element to insert.
193: * @exception UnsupportedOperationException if the <tt>add</tt> method is
194: * not supported by this list iterator.
195: *
196: * @exception ClassCastException if the class of the specified element
197: * prevents it from being added to this list.
198: *
199: * @exception IllegalArgumentException if some aspect of this element
200: * prevents it from being added to this list.
201: */
202: void add(Object o);
203: }
|