KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > collections > MapIterator


1 /*
2  * Copyright 2003-2004 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;
17
18 import java.util.Iterator JavaDoc;
19
20 /**
21  * Defines an iterator that operates over a <code>Map</code>.
22  * <p>
23  * This iterator is a special version designed for maps. It can be more
24  * efficient to use this rather than an entry set iterator where the option
25  * is available, and it is certainly more convenient.
26  * <p>
27  * A map that provides this interface may not hold the data internally using
28  * Map Entry objects, thus this interface can avoid lots of object creation.
29  * <p>
30  * In use, this iterator iterates through the keys in the map. After each call
31  * to <code>next()</code>, the <code>getValue()</code> method provides direct
32  * access to the value. The value can also be set using <code>setValue()</code>.
33  * <pre>
34  * MapIterator it = map.mapIterator();
35  * while (it.hasNext()) {
36  * Object key = it.next();
37  * Object value = it.getValue();
38  * it.setValue(newValue);
39  * }
40  * </pre>
41  *
42  * @since Commons Collections 3.0
43  * @version $Revision: 1.7 $ $Date: 2004/02/18 01:15:42 $
44  *
45  * @author Stephen Colebourne
46  */

47 public interface MapIterator extends Iterator JavaDoc {
48     
49     /**
50      * Checks to see if there are more entries still to be iterated.
51      *
52      * @return <code>true</code> if the iterator has more elements
53      */

54     boolean hasNext();
55
56     /**
57      * Gets the next <em>key</em> from the <code>Map</code>.
58      *
59      * @return the next key in the iteration
60      * @throws java.util.NoSuchElementException if the iteration is finished
61      */

62     Object JavaDoc next();
63
64     //-----------------------------------------------------------------------
65
/**
66      * Gets the current key, which is the key returned by the last call
67      * to <code>next()</code>.
68      *
69      * @return the current key
70      * @throws IllegalStateException if <code>next()</code> has not yet been called
71      */

72     Object JavaDoc getKey();
73
74     /**
75      * Gets the current value, which is the value associated with the last key
76      * returned by <code>next()</code>.
77      *
78      * @return the current value
79      * @throws IllegalStateException if <code>next()</code> has not yet been called
80      */

81     Object JavaDoc getValue();
82
83     //-----------------------------------------------------------------------
84
/**
85      * Removes the last returned key from the underlying <code>Map</code> (optional operation).
86      * <p>
87      * This method can be called once per call to <code>next()</code>.
88      *
89      * @throws UnsupportedOperationException if remove is not supported by the map
90      * @throws IllegalStateException if <code>next()</code> has not yet been called
91      * @throws IllegalStateException if <code>remove()</code> has already been called
92      * since the last call to <code>next()</code>
93      */

94     void remove();
95     
96     /**
97      * Sets the value associated with the current key (optional operation).
98      *
99      * @param value the new value
100      * @return the previous value
101      * @throws UnsupportedOperationException if setValue is not supported by the map
102      * @throws IllegalStateException if <code>next()</code> has not yet been called
103      * @throws IllegalStateException if <code>remove()</code> has been called since the
104      * last call to <code>next()</code>
105      */

106     Object JavaDoc setValue(Object JavaDoc value);
107
108 }
109
Popular Tags