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. package java.util;
  11. /**
  12. * An iterator for lists that allows the programmer to traverse the
  13. * list in either direction and modify the list during iteration.
  14. *
  15. * @author Josh Bloch
  16. * @version 1.16, 02/02/00
  17. * @see Collection
  18. * @see List
  19. * @see Iterator
  20. * @see Enumeration
  21. * @since 1.2
  22. */
  23. public interface ListIterator extends Iterator {
  24. // Query Operations
  25. /**
  26. * Returns <tt>true</tt> if this list iterator has more elements when
  27. * traversing the list in the forward direction. (In other words, returns
  28. * <tt>true</tt> if <tt>next</tt> would return an element rather than
  29. * throwing an exception.)
  30. *
  31. * @return <tt>true</tt> if the list iterator has more elements when
  32. * traversing the list in the forward direction.
  33. */
  34. boolean hasNext();
  35. /**
  36. * Returns the next element in the list. This method may be called
  37. * repeatedly to iterate through the list, or intermixed with calls to
  38. * <tt>previous</tt> to go back and forth. (Note that alternating calls
  39. * to <tt>next</tt> and <tt>previous</tt> will return the same element
  40. * repeatedly.)
  41. *
  42. * @return the next element in the list.
  43. * @exception NoSuchElementException if the iteration has no next element.
  44. */
  45. Object next();
  46. /**
  47. * Returns <tt>true</tt> if this list iterator has more elements when
  48. * traversing the list in the reverse direction. (In other words, returns
  49. * <tt>true</tt> if <tt>previous</tt> would return an element rather than
  50. * throwing an exception.)
  51. *
  52. * @return <tt>true</tt> if the list iterator has more elements when
  53. * traversing the list in the reverse direction.
  54. */
  55. boolean hasPrevious();
  56. /**
  57. * Returns the previous element in the list. This method may be called
  58. * repeatedly to iterate through the list backwards, or intermixed with
  59. * calls to <tt>next</tt> to go back and forth. (Note that alternating
  60. * calls to <tt>next</tt> and <tt>previous</tt> will return the same
  61. * element repeatedly.)
  62. *
  63. * @return the previous element in the list.
  64. *
  65. * @exception NoSuchElementException if the iteration has no previous
  66. * element.
  67. */
  68. Object previous();
  69. /**
  70. * Returns the index of the element that would be returned by a subsequent
  71. * call to <tt>next</tt>. (Returns list size if the list iterator is at the
  72. * end of the list.)
  73. *
  74. * @return the index of the element that would be returned by a subsequent
  75. * call to <tt>next</tt>, or list size if list iterator is at end
  76. * of list.
  77. */
  78. int nextIndex();
  79. /**
  80. * Returns the index of the element that would be returned by a subsequent
  81. * call to <tt>previous</tt>. (Returns -1 if the list iterator is at the
  82. * beginning of the list.)
  83. *
  84. * @return the index of the element that would be returned by a subsequent
  85. * call to <tt>previous</tt>, or -1 if list iterator is at
  86. * beginning of list.
  87. */
  88. int previousIndex();
  89. // Modification Operations
  90. /**
  91. * Removes from the list the last element that was returned by
  92. * <tt>next</tt> or <tt>previous</tt> (optional operation). This call can
  93. * only be made once per call to <tt>next</tt> or <tt>previous</tt>. It
  94. * can be made only if <tt>ListIterator.add</tt> has not been called after
  95. * the last call to <tt>next</tt> or <tt>previous</tt>.
  96. *
  97. * @exception UnsupportedOperationException if the <tt>remove</tt>
  98. * operation is not supported by this list iterator.
  99. * @exception IllegalStateException neither <tt>next</tt> nor
  100. * <tt>previous</tt> have been called, or <tt>remove</tt> or
  101. * <tt>add</tt> have been called after the last call to *
  102. * <tt>next</tt> or <tt>previous</tt>.
  103. */
  104. void remove();
  105. /**
  106. * Replaces the last element returned by <tt>next</tt> or
  107. * <tt>previous</tt> with the specified element (optional operation).
  108. * This call can be made only if neither <tt>ListIterator.remove</tt> nor
  109. * <tt>ListIterator.add</tt> have been called after the last call to
  110. * <tt>next</tt> or <tt>previous</tt>.
  111. *
  112. * @param o the element with which to replace the last element returned by
  113. * <tt>next</tt> or <tt>previous</tt>.
  114. * @exception UnsupportedOperationException if the <tt>set</tt> operation
  115. * is not supported by this list iterator.
  116. * @exception ClassCastException if the class of the specified element
  117. * prevents it from being added to this list.
  118. * @exception IllegalArgumentException if some aspect of the specified
  119. * element prevents it from being added to this list.
  120. * @exception IllegalStateException if neither <tt>next</tt> nor
  121. * <tt>previous</tt> have been called, or <tt>remove</tt> or
  122. * <tt>add</tt> have been called after the last call to
  123. * <tt>next</tt> or <tt>previous</tt>.
  124. */
  125. void set(Object o);
  126. /**
  127. * Inserts the specified element into the list (optional operation). The
  128. * element is inserted immediately before the next element that would be
  129. * returned by <tt>next</tt>, if any, and after the next element that
  130. * would be returned by <tt>previous</tt>, if any. (If the list contains
  131. * no elements, the new element becomes the sole element on the list.)
  132. * The new element is inserted before the implicit cursor: a subsequent
  133. * call to <tt>next</tt> would be unaffected, and a subsequent call to
  134. * <tt>previous</tt> would return the new element. (This call increases
  135. * by one the value that would be returned by a call to <tt>nextIndex</tt>
  136. * or <tt>previousIndex</tt>.)
  137. *
  138. * @param o the element to insert.
  139. * @exception UnsupportedOperationException if the <tt>add</tt> method is
  140. * not supported by this list iterator.
  141. *
  142. * @exception ClassCastException if the class of the specified element
  143. * prevents it from being added to this Set.
  144. *
  145. * @exception IllegalArgumentException if some aspect of this element
  146. * prevents it from being added to this Collection.
  147. */
  148. void add(Object o);
  149. }