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     */
017    package org.apache.commons.collections;
018    
019    import 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>
035     * MapIterator it = map.mapIterator();
036     * while (it.hasNext()) {
037     *   Object key = it.next();
038     *   Object value = it.getValue();
039     *   it.setValue(newValue);
040     * }
041     * </pre>
042     *  
043     * @since Commons Collections 3.0
044     * @version $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
045     *
046     * @author Stephen Colebourne
047     */
048    public interface MapIterator extends Iterator {
049        
050        /**
051         * Checks to see if there are more entries still to be iterated.
052         *
053         * @return <code>true</code> if the iterator has more elements
054         */
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        Object next();
064    
065        //-----------------------------------------------------------------------
066        /**
067         * Gets the current key, which is the key returned by the last call
068         * to <code>next()</code>.
069         *
070         * @return the current key
071         * @throws IllegalStateException if <code>next()</code> has not yet been called
072         */
073        Object getKey();
074    
075        /**
076         * Gets the current value, which is the value associated with the last key
077         * returned by <code>next()</code>.
078         *
079         * @return the current value
080         * @throws IllegalStateException if <code>next()</code> has not yet been called
081         */
082        Object getValue();
083    
084        //-----------------------------------------------------------------------
085        /**
086         * Removes the last returned key from the underlying <code>Map</code> (optional operation).
087         * <p>
088         * This method can be called once per call to <code>next()</code>.
089         *
090         * @throws UnsupportedOperationException if remove is not supported by the map
091         * @throws IllegalStateException if <code>next()</code> has not yet been called
092         * @throws IllegalStateException if <code>remove()</code> has already been called
093         *  since the last call to <code>next()</code>
094         */
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()</code> has not yet been called
104         * @throws IllegalStateException if <code>remove()</code> has been called since the
105         *  last call to <code>next()</code>
106         */
107        Object setValue(Object value);
108    
109    }