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