1   /*
2    * %W% %E%
3    *
4    * Copyright (c) 2006, Oracle and/or its affiliates. All rights reserved.
5    * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.util;
9   
10  /**
11   * An iterator over a collection.  Iterator takes the place of Enumeration in
12   * the Java collections framework.  Iterators differ from enumerations in two
13   * ways: <ul>
14   *  <li> Iterators allow the caller to remove elements from the
15   *       underlying collection during the iteration with well-defined
16   *       semantics.
17   *  <li> Method names have been improved.
18   * </ul><p>
19   *
20   * This interface is a member of the 
21   * <a href="{@docRoot}/../technotes/guides/collections/index.html">
22   * Java Collections Framework</a>.
23   *
24   * @author  Josh Bloch
25   * @version %I%, %G%
26   * @see Collection
27   * @see ListIterator
28   * @see Enumeration
29   * @since 1.2
30   */
31  public interface Iterator<E> {
32      /**
33       * Returns <tt>true</tt> if the iteration has more elements. (In other
34       * words, returns <tt>true</tt> if <tt>next</tt> would return an element
35       * rather than throwing an exception.)
36       *
37       * @return <tt>true</tt> if the iterator has more elements.
38       */
39      boolean hasNext();
40  
41      /**
42       * Returns the next element in the iteration.
43       *
44       * @return the next element in the iteration.
45       * @exception NoSuchElementException iteration has no more elements.
46       */
47      E next();
48  
49      /**
50       * 
51       * Removes from the underlying collection the last element returned by the
52       * iterator (optional operation).  This method can be called only once per
53       * call to <tt>next</tt>.  The behavior of an iterator is unspecified if
54       * the underlying collection is modified while the iteration is in
55       * progress in any way other than by calling this method.
56       *
57       * @exception UnsupportedOperationException if the <tt>remove</tt>
58       *        operation is not supported by this Iterator.
59       
60       * @exception IllegalStateException if the <tt>next</tt> method has not
61       *        yet been called, or the <tt>remove</tt> method has already
62       *        been called after the last call to the <tt>next</tt>
63       *        method.
64       */
65      void remove();
66  }
67