KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > collections > iterators > ReverseListIterator


1 /*
2  * Copyright 2006 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.collections.iterators;
17
18 import java.util.List JavaDoc;
19 import java.util.ListIterator JavaDoc;
20
21 import org.apache.commons.collections.ResettableListIterator;
22
23 /**
24  * Iterates backwards through a List, starting with the last element
25  * and continuing to the first. This is useful for looping around
26  * a list in reverse order without needing to actually reverse the list.
27  * <p>
28  * The first call to <code>next()</code> will return the last element
29  * from the list, and so on. The <code>hasNext()</code> method works
30  * in concert with the <code>next()</code> method as expected.
31  * However, the <code>nextIndex()</code> method returns the correct
32  * index in the list, thus it starts high and reduces as the iteration
33  * continues. The previous methods work similarly.
34  *
35  * @author Serge Knystautas
36  * @author Stephen Colebourne
37  * @since Commons Collections 3.2
38  * @version $Revision: $ $Date: 2006-05-12 23:52:43 +0100 (Fri, 12 May 2006) $
39  */
40 public class ReverseListIterator implements ResettableListIterator {
41
42     /** The list being wrapped. */
43     private final List JavaDoc list;
44     /** The list iterator being wrapped. */
45     private ListIterator JavaDoc iterator;
46     /** Flag to indicate if updating is possible at the moment. */
47     private boolean validForUpdate = true;
48
49     /**
50      * Constructor that wraps a list.
51      *
52      * @param list the list to create a reversed iterator for
53      * @throws NullPointerException if the list is null
54      */
55     public ReverseListIterator(List JavaDoc list) {
56         super();
57         this.list = list;
58         iterator = list.listIterator(list.size());
59     }
60
61     //-----------------------------------------------------------------------
62 /**
63      * Checks whether there is another element.
64      *
65      * @return true if there is another element
66      */
67     public boolean hasNext() {
68         return iterator.hasPrevious();
69     }
70
71     /**
72      * Gets the next element.
73      * The next element is the previous in the list.
74      *
75      * @return the next element in the iterator
76      */
77     public Object JavaDoc next() {
78         Object JavaDoc obj = iterator.previous();
79         validForUpdate = true;
80         return obj;
81     }
82
83     /**
84      * Gets the index of the next element.
85      *
86      * @return the index of the next element in the iterator
87      */
88     public int nextIndex() {
89         return iterator.previousIndex();
90     }
91
92     /**
93      * Checks whether there is a previous element.
94      *
95      * @return true if there is a previous element
96      */
97     public boolean hasPrevious() {
98         return iterator.hasNext();
99     }
100
101     /**
102      * Gets the previous element.
103      * The next element is the previous in the list.
104      *
105      * @return the previous element in the iterator
106      */
107     public Object JavaDoc previous() {
108         Object JavaDoc obj = iterator.next();
109         validForUpdate = true;
110         return obj;
111     }
112
113     /**
114      * Gets the index of the previous element.
115      *
116      * @return the index of the previous element in the iterator
117      */
118     public int previousIndex() {
119         return iterator.nextIndex();
120     }
121
122     /**
123      * Removes the last returned element.
124      *
125      * @throws UnsupportedOperationException if the list is unmodifiable
126      * @throws IllegalStateException if there is no element to remove
127      */
128     public void remove() {
129         if (validForUpdate == false) {
130             throw new IllegalStateException JavaDoc("Cannot remove from list until next() or previous() called");
131         }
132         iterator.remove();
133     }
134
135     /**
136      * Replaces the last returned element.
137      *
138      * @param obj the object to set
139      * @throws UnsupportedOperationException if the list is unmodifiable
140      * @throws IllegalStateException if the iterator is not in a valid state for set
141      */
142     public void set(Object JavaDoc obj) {
143         if (validForUpdate == false) {
144             throw new IllegalStateException JavaDoc("Cannot set to list until next() or previous() called");
145         }
146         iterator.set(obj);
147     }
148
149     /**
150      * Adds a new element to the list between the next and previous elements.
151      *
152      * @param obj the object to add
153      * @throws UnsupportedOperationException if the list is unmodifiable
154      * @throws IllegalStateException if the iterator is not in a valid state for set
155      */
156     public void add(Object JavaDoc obj) {
157         // the validForUpdate flag is needed as the necessary previous()
158 // method call re-enables remove and add
159 if (validForUpdate == false) {
160             throw new IllegalStateException JavaDoc("Cannot add to list until next() or previous() called");
161         }
162         validForUpdate = false;
163         iterator.add(obj);
164         iterator.previous();
165     }
166
167     /**
168      * Resets the iterator back to the start (which is the
169      * end of the list as this is a reversed iterator)
170      */
171     public void reset() {
172         iterator = list.listIterator(list.size());
173     }
174
175 }
176
Popular Tags