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