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 package org.apache.commons.collections4;
18
19 import java.util.Iterator;
20
21 /**
22 * Defines an iterator that operates over a {@code Map}.
23 * <p>
24 * This iterator is a special version designed for maps. It can be more
25 * efficient to use this rather than an entry set iterator where the option
26 * is available, and it is certainly more convenient.
27 * </p>
28 * <p>
29 * A map that provides this interface may not hold the data internally using
30 * Map Entry objects, thus this interface can avoid lots of object creation.
31 * </p>
32 * <p>
33 * In use, this iterator iterates through the keys in the map. After each call
34 * to {@code next()}, the {@code getValue()} method provides direct
35 * access to the value. The value can also be set using {@code setValue()}.
36 * </p>
37 * <pre>{@code
38 * MapIterator<String,Integer> it = map.mapIterator();
39 * while (it.hasNext()) {
40 * String key = it.next();
41 * Integer value = it.getValue();
42 * it.setValue(value + 1);
43 * }
44 * }</pre>
45 *
46 * @param <K> the type of the keys in the map
47 * @param <V> the type of the values in the map
48 * @since 3.0
49 */
50 public interface MapIterator<K, V> extends Iterator<K> {
51
52 /**
53 * Gets the current key, which is the key returned by the last call
54 * to {@code next()}.
55 *
56 * @return the current key
57 * @throws IllegalStateException if {@code next()} has not yet been called
58 */
59 K getKey();
60
61 /**
62 * Gets the current value, which is the value associated with the last key
63 * returned by {@code next()}.
64 *
65 * @return the current value
66 * @throws IllegalStateException if {@code next()} has not yet been called
67 */
68 V getValue();
69
70 /**
71 * Checks to see if there are more entries still to be iterated.
72 *
73 * @return {@code true} if the iterator has more elements
74 */
75 @Override
76 boolean hasNext();
77
78 /**
79 * Gets the next <em>key</em> from the {@code Map}.
80 *
81 * @return the next key in the iteration
82 * @throws java.util.NoSuchElementException if the iteration is finished
83 */
84 @Override
85 K next();
86
87 /**
88 * Removes the last returned key from the underlying {@code Map} (optional operation).
89 * <p>
90 * This method can be called once per call to {@code next()}.
91 * </p>
92 *
93 * @throws UnsupportedOperationException if remove is not supported by the map
94 * @throws IllegalStateException if {@code next()} has not yet been called
95 * @throws IllegalStateException if {@code remove()} has already been called
96 * since the last call to {@code next()}
97 */
98 @Override
99 void remove();
100
101 /**
102 * Sets the value associated with the current key (optional operation).
103 *
104 * @param value the new value
105 * @return the previous value
106 * @throws UnsupportedOperationException if setValue is not supported by the map
107 * @throws IllegalStateException if {@code next()} has not yet been called
108 * @throws IllegalStateException if {@code remove()} has been called since the
109 * last call to {@code next()}
110 */
111 V setValue(V value);
112
113 }