1 /*
2  *  Licensed to the Apache Software Foundation (ASF) under one or more
3  *  contributor license agreements.  See the NOTICE file distributed with
4  *  this work for additional information regarding copyright ownership.
5  *  The ASF licenses this file to You under the Apache License, Version 2.0
6  *  (the "License"); you may not use this file except in compliance with
7  *  the License.  You may obtain a copy of the License at
8  *
9  *     http://www.apache.org/licenses/LICENSE-2.0
10  *
11  *  Unless required by applicable law or agreed to in writing, software
12  *  distributed under the License is distributed on an "AS IS" BASIS,
13  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  *  See the License for the specific language governing permissions and
15  *  limitations under the License.
16  */
17 
18 package java.util;
19 
20 
21 /**
22  * An ListIterator is used to sequence over a List of objects. ListIterator can
23  * move backwards or forwards through the list.
24  */
25 public interface ListIterator<E> extends Iterator<E> {
26 
27     /**
28      * Inserts the specified object into the list between {@code next} and
29      * {@code previous}. The object inserted will be the previous object.
30      *
31      * @param object
32      *            the object to insert.
33      * @throws UnsupportedOperationException
34      *             if adding is not supported by the list being iterated.
35      * @throws ClassCastException
36      *             if the class of the object is inappropriate for the list.
37      * @throws IllegalArgumentException
38      *             if the object cannot be added to the list.
39      */
add(E object)40     void add(E object);
41 
42     /**
43      * Returns whether there are more elements to iterate.
44      *
45      * @return {@code true} if there are more elements, {@code false} otherwise.
46      * @see #next
47      */
hasNext()48     public boolean hasNext();
49 
50     /**
51      * Returns whether there are previous elements to iterate.
52      *
53      * @return {@code true} if there are previous elements, {@code false}
54      *         otherwise.
55      * @see #previous
56      */
hasPrevious()57     public boolean hasPrevious();
58 
59     /**
60      * Returns the next object in the iteration.
61      *
62      * @return the next object.
63      * @throws NoSuchElementException
64      *             if there are no more elements.
65      * @see #hasNext
66      */
next()67     public E next();
68 
69     /**
70      * Returns the index of the next object in the iteration.
71      *
72      * @return the index of the next object, or the size of the list if the
73      *         iterator is at the end.
74      * @throws NoSuchElementException
75      *             if there are no more elements.
76      * @see #next
77      */
nextIndex()78     public int nextIndex();
79 
80     /**
81      * Returns the previous object in the iteration.
82      *
83      * @return the previous object.
84      * @throws NoSuchElementException
85      *             if there are no previous elements.
86      * @see #hasPrevious
87      */
previous()88     public E previous();
89 
90     /**
91      * Returns the index of the previous object in the iteration.
92      *
93      * @return the index of the previous object, or -1 if the iterator is at the
94      *         beginning.
95      * @throws NoSuchElementException
96      *             if there are no previous elements.
97      * @see #previous
98      */
previousIndex()99     public int previousIndex();
100 
101     /**
102      * Removes the last object returned by {@code next} or {@code previous} from
103      * the list.
104      *
105      * @throws UnsupportedOperationException
106      *             if removing is not supported by the list being iterated.
107      * @throws IllegalStateException
108      *             if {@code next} or {@code previous} have not been called, or
109      *             {@code remove} or {@code add} have already been called after
110      *             the last call to {@code next} or {@code previous}.
111      */
remove()112     public void remove();
113 
114     /**
115      * Replaces the last object returned by {@code next} or {@code previous}
116      * with the specified object.
117      *
118      * @param object
119      *            the object to set.
120      * @throws UnsupportedOperationException
121      *             if setting is not supported by the list being iterated
122      * @throws ClassCastException
123      *             if the class of the object is inappropriate for the list.
124      * @throws IllegalArgumentException
125      *             if the object cannot be added to the list.
126      * @throws IllegalStateException
127      *             if {@code next} or {@code previous} have not been called, or
128      *             {@code remove} or {@code add} have already been called after
129      *             the last call to {@code next} or {@code previous}.
130      */
set(E object)131     void set(E object);
132 }
133