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  ;
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   {
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   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   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   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   setValue(Object   value);
107 
108 }
109
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags