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 *      https://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 */
017
018package org.apache.commons.collections4;
019
020import java.util.Iterator;
021
022/**
023 * Defines an iterator that operates over a {@code Map}.
024 * <p>
025 * This iterator is a special version designed for maps. It can be more efficient to use this rather than an entry set iterator where the option is available,
026 * and it is certainly more convenient.
027 * </p>
028 * <p>
029 * A map that provides this interface may not hold the data internally using Map Entry objects, thus this interface can avoid lots of object creation.
030 * </p>
031 * <p>
032 * In use, this iterator iterates through the keys in the map. After each call to {@code next()}, the {@code getValue()} method provides direct access to the
033 * value. The value can also be set using {@code setValue()}.
034 * </p>
035 *
036 * <pre>{@code
037 * MapIterator<String, Integer> it = map.mapIterator();
038 * while (it.hasNext()) {
039 *     String key = it.next();
040 *     Integer value = it.getValue();
041 *     it.setValue(value + 1);
042 * }
043 * }</pre>
044 *
045 * @param <K> The type of the keys in the map.
046 * @param <V> The type of the values in the map.
047 * @since 3.0
048 */
049public interface MapIterator<K, V> extends Iterator<K> {
050
051    /**
052     * Gets the current key, which is the key returned by the last call to {@code next()}.
053     *
054     * @return The current key.
055     * @throws IllegalStateException if {@code next()} has not yet been called.
056     */
057    K getKey();
058
059    /**
060     * Gets the current value, which is the value associated with the last key returned by {@code next()}.
061     *
062     * @return The current value.
063     * @throws IllegalStateException if {@code next()} has not yet been called.
064     */
065    V getValue();
066
067    /**
068     * Checks to see if there are more entries still to be iterated.
069     *
070     * @return {@code true} if the iterator has more elements
071     */
072    @Override
073    boolean hasNext();
074
075    /**
076     * Gets the next <em>key</em> from the {@code Map}.
077     *
078     * @return The next key in the iteration.
079     * @throws java.util.NoSuchElementException if the iteration is finished.
080     */
081    @Override
082    K next();
083
084    /**
085     * Removes the last returned key from the underlying {@code Map} (optional operation).
086     * <p>
087     * This method can be called once per call to {@code next()}.
088     * </p>
089     *
090     * @throws UnsupportedOperationException if remove is not supported by the map.
091     * @throws IllegalStateException         if {@code next()} has not yet been called.
092     * @throws IllegalStateException         if {@code remove()} has already been called since the last call to {@code next()}.
093     */
094    @Override
095    void remove();
096
097    /**
098     * Sets the value associated with the current key (optional operation).
099     *
100     * @param value The new value.
101     * @return The previous value.
102     * @throws UnsupportedOperationException if setValue is not supported by the map.
103     * @throws IllegalStateException         if {@code next()} has not yet been called.
104     * @throws IllegalStateException         if {@code remove()} has been called since the last call to {@code next()}.
105     */
106    V setValue(V value);
107}