1. /*

  2.  * @(#)ListIterator.java	1.16 00/02/02

  3.  *

  4.  * Copyright 1997-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.util;

  12. 

  13. /**

  14.  * An iterator for lists that allows the programmer to traverse the

  15.  * list in either direction and modify the list during iteration.

  16.  *

  17.  * @author  Josh Bloch

  18.  * @version 1.16, 02/02/00

  19.  * @see Collection

  20.  * @see List

  21.  * @see Iterator

  22.  * @see Enumeration

  23.  * @since   1.2

  24.  */

  25. public interface ListIterator extends Iterator {

  26.     // Query Operations

  27. 

  28.     /**

  29.      * Returns <tt>true</tt> if this list iterator has more elements when

  30.      * traversing the list in the forward direction. (In other words, returns

  31.      * <tt>true</tt> if <tt>next</tt> would return an element rather than

  32.      * throwing an exception.)

  33.      *

  34.      * @return <tt>true</tt> if the list iterator has more elements when

  35.      *		traversing the list in the forward direction.

  36.      */

  37.     boolean hasNext();

  38. 

  39.     /**

  40.      * Returns the next element in the list.  This method may be called

  41.      * repeatedly to iterate through the list, or intermixed with calls to

  42.      * <tt>previous</tt> to go back and forth.  (Note that alternating calls

  43.      * to <tt>next</tt> and <tt>previous</tt> will return the same element

  44.      * repeatedly.)

  45.      *

  46.      * @return the next element in the list.

  47.      * @exception NoSuchElementException if the iteration has no next element.

  48.      */

  49.     Object next();

  50. 

  51.     /**

  52.      * Returns <tt>true</tt> if this list iterator has more elements when

  53.      * traversing the list in the reverse direction.  (In other words, returns

  54.      * <tt>true</tt> if <tt>previous</tt> would return an element rather than

  55.      * throwing an exception.)

  56.      *

  57.      * @return <tt>true</tt> if the list iterator has more elements when

  58.      *	       traversing the list in the reverse direction.

  59.      */

  60.     boolean hasPrevious();

  61. 

  62.     /**

  63.      * Returns the previous element in the list.  This method may be called

  64.      * repeatedly to iterate through the list backwards, or intermixed with

  65.      * calls to <tt>next</tt> to go back and forth.  (Note that alternating

  66.      * calls to <tt>next</tt> and <tt>previous</tt> will return the same

  67.      * element repeatedly.)

  68.      *

  69.      * @return the previous element in the list.

  70.      * 

  71.      * @exception NoSuchElementException if the iteration has no previous

  72.      *            element.

  73.      */

  74.     Object previous();

  75. 

  76.     /**

  77.      * Returns the index of the element that would be returned by a subsequent

  78.      * call to <tt>next</tt>. (Returns list size if the list iterator is at the

  79.      * end of the list.)

  80.      *

  81.      * @return the index of the element that would be returned by a subsequent

  82.      * 	       call to <tt>next</tt>, or list size if list iterator is at end

  83.      *	       of list. 

  84.      */

  85.     int nextIndex();

  86. 

  87.     /**

  88.      * Returns the index of the element that would be returned by a subsequent

  89.      * call to <tt>previous</tt>. (Returns -1 if the list iterator is at the

  90.      * beginning of the list.)

  91.      *

  92.      * @return the index of the element that would be returned by a subsequent

  93.      * 	       call to <tt>previous</tt>, or -1 if list iterator is at

  94.      *	       beginning of list.

  95.      */ 

  96.     int previousIndex();

  97. 

  98. 

  99.     // Modification Operations

  100.     

  101.     /**

  102.      * Removes from the list the last element that was returned by

  103.      * <tt>next</tt> or <tt>previous</tt> (optional operation).  This call can

  104.      * only be made once per call to <tt>next</tt> or <tt>previous</tt>.  It

  105.      * can be made only if <tt>ListIterator.add</tt> has not been called after

  106.      * the last call to <tt>next</tt> or <tt>previous</tt>.

  107.      *

  108.      * @exception UnsupportedOperationException if the <tt>remove</tt>

  109.      * 		  operation is not supported by this list iterator.

  110.      * @exception IllegalStateException neither <tt>next</tt> nor

  111.      *		  <tt>previous</tt> have been called, or <tt>remove</tt> or

  112.      *		  <tt>add</tt> have been called after the last call to *

  113.      *		  <tt>next</tt> or <tt>previous</tt>.

  114.      */

  115.     void remove();

  116. 

  117.     /**

  118.      * Replaces the last element returned by <tt>next</tt> or

  119.      * <tt>previous</tt> with the specified element (optional operation).

  120.      * This call can be made only if neither <tt>ListIterator.remove</tt> nor

  121.      * <tt>ListIterator.add</tt> have been called after the last call to

  122.      * <tt>next</tt> or <tt>previous</tt>.

  123.      *

  124.      * @param o the element with which to replace the last element returned by

  125.      *          <tt>next</tt> or <tt>previous</tt>.

  126.      * @exception UnsupportedOperationException if the <tt>set</tt> operation

  127.      * 		  is not supported by this list iterator.

  128.      * @exception ClassCastException if the class of the specified element

  129.      * 		  prevents it from being added to this list.

  130.      * @exception IllegalArgumentException if some aspect of the specified

  131.      *		  element prevents it from being added to this list.

  132.      * @exception IllegalStateException if neither <tt>next</tt> nor

  133.      *	          <tt>previous</tt> have been called, or <tt>remove</tt> or

  134.      *		  <tt>add</tt> have been called after the last call to

  135.      * 		  <tt>next</tt> or <tt>previous</tt>.

  136.      */

  137.     void set(Object o);

  138. 

  139.     /**

  140.      * Inserts the specified element into the list (optional operation).  The

  141.      * element is inserted immediately before the next element that would be

  142.      * returned by <tt>next</tt>, if any, and after the next element that

  143.      * would be returned by <tt>previous</tt>, if any.  (If the list contains

  144.      * no elements, the new element becomes the sole element on the list.)

  145.      * The new element is inserted before the implicit cursor: a subsequent

  146.      * call to <tt>next</tt> would be unaffected, and a subsequent call to

  147.      * <tt>previous</tt> would return the new element.  (This call increases

  148.      * by one the value that would be returned by a call to <tt>nextIndex</tt>

  149.      * or <tt>previousIndex</tt>.)

  150.      *

  151.      * @param o the element to insert.

  152.      * @exception UnsupportedOperationException if the <tt>add</tt> method is

  153.      * 		  not supported by this list iterator.

  154.      * 

  155.      * @exception ClassCastException if the class of the specified element

  156.      * 		  prevents it from being added to this Set.

  157.      * 

  158.      * @exception IllegalArgumentException if some aspect of this element

  159.      *            prevents it from being added to this Collection.

  160.      */

  161.     void add(Object o);

  162. }