001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.collections4.iterators;
018
019import java.util.Iterator;
020import java.util.Map;
021
022import org.apache.commons.collections4.MapIterator;
023import org.apache.commons.collections4.ResettableIterator;
024
025/**
026 * Implements a {@code MapIterator} using a Map entrySet.
027 * Reverse iteration is not supported.
028 * <pre>
029 * MapIterator it = map.mapIterator();
030 * while (it.hasNext()) {
031 *   Object key = it.next();
032 *   Object value = it.getValue();
033 *   it.setValue(newValue);
034 * }
035 * </pre>
036 *
037 * @param <K> the type of keys
038 * @param <V> the type of mapped values
039 * @since 3.0
040 */
041public class EntrySetMapIterator<K, V> implements MapIterator<K, V>, ResettableIterator<K> {
042
043    private final Map<K, V> map;
044    private Iterator<Map.Entry<K, V>> iterator;
045    private Map.Entry<K, V> last;
046    private boolean canRemove;
047
048    /**
049     * Constructs a new instance.
050     *
051     * @param map  the map to iterate over
052     */
053    public EntrySetMapIterator(final Map<K, V> map) {
054        this.map = map;
055        this.iterator = map.entrySet().iterator();
056    }
057
058    /**
059     * Gets the current key, which is the key returned by the last call
060     * to {@code next()}.
061     *
062     * @return the current key
063     * @throws IllegalStateException if {@code next()} has not yet been called
064     */
065    @Override
066    public K getKey() {
067        if (last == null) {
068            throw new IllegalStateException("Iterator getKey() can only be called after next() and before remove()");
069        }
070        return last.getKey();
071    }
072
073    /**
074     * Gets the current value, which is the value associated with the last key
075     * returned by {@code next()}.
076     *
077     * @return the current value
078     * @throws IllegalStateException if {@code next()} has not yet been called
079     */
080    @Override
081    public V getValue() {
082        if (last == null) {
083            throw new IllegalStateException("Iterator getValue() can only be called after next() and before remove()");
084        }
085        return last.getValue();
086    }
087
088    /**
089     * Checks to see if there are more entries still to be iterated.
090     *
091     * @return {@code true} if the iterator has more elements
092     */
093    @Override
094    public boolean hasNext() {
095        return iterator.hasNext();
096    }
097
098    /**
099     * Gets the next <em>key</em> from the {@code Map}.
100     *
101     * @return the next key in the iteration
102     * @throws java.util.NoSuchElementException if the iteration is finished
103     */
104    @Override
105    public K next() {
106        last = iterator.next();
107        canRemove = true;
108        return last.getKey();
109    }
110
111    /**
112     * Removes the last returned key from the underlying {@code Map}.
113     * <p>
114     * This method can be called once per call to {@code next()}.
115     *
116     * @throws UnsupportedOperationException if remove is not supported by the map
117     * @throws IllegalStateException if {@code next()} has not yet been called
118     * @throws IllegalStateException if {@code remove()} has already been called
119     *  since the last call to {@code next()}
120     */
121    @Override
122    public void remove() {
123        if (!canRemove) {
124            throw new IllegalStateException("Iterator remove() can only be called once after next()");
125        }
126        iterator.remove();
127        last = null;
128        canRemove = false;
129    }
130
131    /**
132     * Resets the state of the iterator.
133     */
134    @Override
135    public void reset() {
136        iterator = map.entrySet().iterator();
137        last = null;
138        canRemove = false;
139    }
140
141    /**
142     * Sets the value associated with the current key.
143     *
144     * @param value  the new value
145     * @return the previous value
146     * @throws UnsupportedOperationException if setValue is not supported by the map
147     * @throws IllegalStateException if {@code next()} has not yet been called
148     * @throws IllegalStateException if {@code remove()} has been called since the
149     *  last call to {@code next()}
150     */
151    @Override
152    public V setValue(final V value) {
153        if (last == null) {
154            throw new IllegalStateException("Iterator setValue() can only be called after next() and before remove()");
155        }
156        return last.setValue(value);
157    }
158
159    /**
160     * Gets the iterator as a String.
161     *
162     * @return a string version of the iterator
163     */
164    @Override
165    public String toString() {
166        if (last != null) {
167            return "MapIterator[" + getKey() + "=" + getValue() + "]";
168        }
169        return "MapIterator[]";
170    }
171
172}