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
18package 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 */
25public 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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
131    void set(E object);
132}
133