commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scolebou...@apache.org
Subject cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections/iterators ResetableMapIterator.java MapIterator.java
Date Sun, 02 Nov 2003 15:27:54 GMT
scolebourne    2003/11/02 07:27:54

  Modified:    collections/src/java/org/apache/commons/collections
                        IteratorUtils.java AbstractDualBidiMap.java
                        BidiMap.java
               collections/src/test/org/apache/commons/collections
                        AbstractTestBidiMap.java TestIteratorUtils.java
  Added:       collections/src/java/org/apache/commons/collections/iterators
                        ResetableMapIterator.java MapIterator.java
  Removed:     collections/src/java/org/apache/commons/collections
                        MapIterator.java
  Log:
  More work around the MapIterator
  
  Revision  Changes    Path
  1.14      +68 -41    jakarta-commons/collections/src/java/org/apache/commons/collections/IteratorUtils.java
  
  Index: IteratorUtils.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/IteratorUtils.java,v
  retrieving revision 1.13
  retrieving revision 1.14
  diff -u -r1.13 -r1.14
  --- IteratorUtils.java	29 Sep 2003 22:44:14 -0000	1.13
  +++ IteratorUtils.java	2 Nov 2003 15:27:53 -0000	1.14
  @@ -70,6 +70,7 @@
   import java.util.ListIterator;
   import java.util.Map;
   import java.util.NoSuchElementException;
  +import java.util.Map.Entry;
   
   import org.apache.commons.collections.iterators.ArrayIterator;
   import org.apache.commons.collections.iterators.ArrayListIterator;
  @@ -85,6 +86,7 @@
   import org.apache.commons.collections.iterators.ObjectArrayListIterator;
   import org.apache.commons.collections.iterators.ResetableIterator;
   import org.apache.commons.collections.iterators.ResetableListIterator;
  +import org.apache.commons.collections.iterators.ResetableMapIterator;
   import org.apache.commons.collections.iterators.SingletonIterator;
   import org.apache.commons.collections.iterators.SingletonListIterator;
   import org.apache.commons.collections.iterators.TransformIterator;
  @@ -107,11 +109,15 @@
       /**
        * An iterator over no elements
        */    
  -    public static final Iterator EMPTY_ITERATOR = new EmptyIterator();
  +    public static final ResetableIterator EMPTY_ITERATOR = new EmptyIterator();
       /**
        * A list iterator over no elements
        */    
  -    public static final ListIterator EMPTY_LIST_ITERATOR = new EmptyListIterator();
  +    public static final ResetableListIterator EMPTY_LIST_ITERATOR = new EmptyListIterator();
  +    /**
  +     * A map iterator over no elements
  +     */    
  +    public static final ResetableMapIterator EMPTY_MAP_ITERATOR = new EmptyMapIterator();
   
       /**
        * Prevents instantiation.
  @@ -131,7 +137,7 @@
        * @return  an iterator over nothing
        */
       public static ResetableIterator emptyIterator() {
  -        return (ResetableIterator) EMPTY_ITERATOR;
  +        return EMPTY_ITERATOR;
       }
   
       /**
  @@ -143,7 +149,19 @@
        * @return  a list iterator over nothing
        */
       public static ResetableListIterator emptyListIterator() {
  -        return (ResetableListIterator) EMPTY_LIST_ITERATOR;
  +        return EMPTY_LIST_ITERATOR;
  +    }
  +
  +    /**
  +     * Gets an empty map iterator.
  +     * <p>
  +     * This iterator is a valid map iterator object that will iterate 
  +     * over nothing.
  +     *
  +     * @return  a list iterator over nothing
  +     */
  +    public static ResetableMapIterator emptyMapIterator() {
  +        return EMPTY_MAP_ITERATOR;
       }
   
       /**
  @@ -761,90 +779,96 @@
           }
       }
       
  +    //-----------------------------------------------------------------------
       /**
        * EmptyIterator class
        */
       static class EmptyIterator implements ResetableIterator {
           
  -        /**
  -         * @see java.util.Iterator#hasNext()
  -         */
  +        EmptyIterator() {
  +            super();
  +        }
  +
           public boolean hasNext() {
               return false;
           }
   
  -        /**
  -         * @see java.util.Iterator#next()
  -         */
           public Object next() {
  -            throw new NoSuchElementException();
  +            throw new NoSuchElementException("Iterator contains no elements");
           }
   
  -        /**
  -         * @see java.util.Iterator#remove()
  -         */
           public void remove() {
  -            throw new UnsupportedOperationException("remove() not supported for empty Iterator");
  +            throw new IllegalStateException("Iterator contains no elements");
           }
           
  -        /**
  -         * Reset the iterator
  -         */
           public void reset() {
               // do nothing
           }
  -
       }
       
  +    //-----------------------------------------------------------------------    
       /**
        * EmptyListIterator class
        */
       static class EmptyListIterator extends EmptyIterator implements ResetableListIterator
{
           
  -        /**
  -         * @see java.util.ListIterator#hasPrevious()
  -         */
  +        EmptyListIterator() {
  +            super();
  +        }
  +
           public boolean hasPrevious() {
               return false;
           }
   
  -        /**
  -         * @see java.util.ListIterator#previous()
  -         */
           public Object previous() {
  -            throw new NoSuchElementException();
  +            throw new NoSuchElementException("Iterator contains no elements");
           }
   
  -        /**
  -         * @see java.util.ListIterator#nextIndex()
  -         */
           public int nextIndex() {
               return 0;
           }
   
  -        /**
  -         * @see java.util.ListIterator#previousIndex()
  -         */
           public int previousIndex() {
               return -1;
           }
   
  -        /**
  -         * @see java.util.ListIterator#add(Object)
  -         */
           public void add(Object o) {
               throw new UnsupportedOperationException("add() not supported for empty Iterator");
           }
   
  -        /**
  -         * @see java.util.ListIterator#set(Object)
  -         */
           public void set(Object o) {
  -            throw new UnsupportedOperationException("set() not supported for empty Iterator");
  +            throw new IllegalStateException("Iterator contains no elements");
  +        }
  +    }
  +
  +    //-----------------------------------------------------------------------    
  +    /**
  +     * EmptyMapIterator class
  +     */
  +    static class EmptyMapIterator extends EmptyIterator implements ResetableMapIterator
{
  +        
  +        EmptyMapIterator() {
  +            super();
  +        }
  +
  +        public Object getKey() {
  +            throw new IllegalStateException("Iterator contains no elements");
  +        }
  +
  +        public Object getValue() {
  +            throw new IllegalStateException("Iterator contains no elements");
           }
   
  +        public Object setValue(Object value) {
  +            throw new IllegalStateException("Iterator contains no elements");
  +        }
  +        
  +        public Entry asMapEntry() {
  +            throw new IllegalStateException("Iterator contains no elements");
  +        }
       }
   
  +    //-----------------------------------------------------------------------    
       /**
        * A wrapper for an {@link java.util.Iterator} which makes it immutable. All
        * calls are passed through to the delegate. The {@link #remove()} method
  @@ -883,6 +907,7 @@
   
       }
   
  +    //-----------------------------------------------------------------------
       /**
        * An unmodifiable resetable iterator.
        *
  @@ -908,6 +933,7 @@
   
       }
       
  +    //-----------------------------------------------------------------------
       /**
        * A wrapper for an {@link java.util.ListIterator} which makes it immutable.
        * All calls are passed through to the delegate. The {@link #remove()},
  @@ -970,6 +996,7 @@
           }
       }
       
  +    //-----------------------------------------------------------------------
       /**
        * An unmodifiable resetable list iterator.
        *
  
  
  
  1.7       +45 -6     jakarta-commons/collections/src/java/org/apache/commons/collections/AbstractDualBidiMap.java
  
  Index: AbstractDualBidiMap.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/AbstractDualBidiMap.java,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- AbstractDualBidiMap.java	1 Nov 2003 18:47:18 -0000	1.6
  +++ AbstractDualBidiMap.java	2 Nov 2003 15:27:53 -0000	1.7
  @@ -65,6 +65,9 @@
   import org.apache.commons.collections.decorators.AbstractCollectionDecorator;
   import org.apache.commons.collections.decorators.AbstractIteratorDecorator;
   import org.apache.commons.collections.decorators.AbstractMapEntryDecorator;
  +import org.apache.commons.collections.iterators.MapIterator;
  +import org.apache.commons.collections.iterators.ResetableMapIterator;
  +import org.apache.commons.collections.pairs.AbstractMapEntry;
   
   /**
    * Abstract <code>BidiMap</code> implemented using two maps.
  @@ -218,6 +221,13 @@
   
       // BidiMap
       //-----------------------------------------------------------------------
  +    /**
  +     * Obtains a <code>MapIterator</code> over the map.
  +     * The iterator implements <code>ResetableMapIterator</code>.
  +     * This implementation relies on the entrySet iterator.
  +     * 
  +     * @return a map iterator
  +     */
       public MapIterator mapIterator() {
           return new BidiMapIterator(this);
       }
  @@ -524,19 +534,25 @@
       /**
        * Inner class MapIterator.
        */
  -    protected static class BidiMapIterator extends AbstractIteratorDecorator implements
MapIterator {
  +    protected static class BidiMapIterator implements ResetableMapIterator {
           
           protected final AbstractDualBidiMap map;
  +        protected Iterator iterator;
           private Map.Entry last = null;
           private boolean canRemove = false;
           
           protected BidiMapIterator(AbstractDualBidiMap map) {
  -            super(map.maps[0].entrySet().iterator());
  +            super();
               this.map = map;
  +            this.iterator = map.maps[0].entrySet().iterator();
  +        }
  +        
  +        public boolean hasNext() {
  +            return iterator.hasNext();
           }
           
           public Object next() {
  -            last = new MapEntry((Map.Entry) super.next(), map);
  +            last = new MapEntry((Map.Entry) iterator.next(), map);
               canRemove = true;
               return last.getKey();
           }
  @@ -547,7 +563,7 @@
               }
               // store value as remove may change the entry in the decorator (eg.TreeMap)
               Object value = last.getValue();
  -            super.remove();
  +            iterator.remove();
               map.maps[1].remove(value);
               last = null;
               canRemove = false;
  @@ -576,6 +592,29 @@
                   throw new IllegalArgumentException("Cannot use setValue() when the object
being set is already in the map");
               }
               return map.put(last.getKey(), value);
  +        }
  +        
  +        public void reset() {
  +            iterator = map.maps[0].entrySet().iterator();
  +            last = null;
  +            canRemove = false;
  +        }
  +        
  +        public Map.Entry asMapEntry() {
  +            return new AbstractMapEntry(getKey(), getValue()) {
  +                public Object setValue(Object value) {
  +                    BidiMapIterator.this.setValue(value);
  +                    return super.setValue(value);
  +                }
  +            };
  +        }
  +        
  +        public String toString() {
  +            if (last == null) {
  +                return "MapIterator[" + getKey() + "=" + getValue() + "]";
  +            } else {
  +                return "MapIterator[]";
  +            }
           }
       }
       
  
  
  
  1.5       +9 -5      jakarta-commons/collections/src/java/org/apache/commons/collections/BidiMap.java
  
  Index: BidiMap.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/BidiMap.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- BidiMap.java	29 Oct 2003 00:06:25 -0000	1.4
  +++ BidiMap.java	2 Nov 2003 15:27:53 -0000	1.5
  @@ -59,6 +59,8 @@
   
   import java.util.Map;
   
  +import org.apache.commons.collections.iterators.MapIterator;
  +
   /**
    * Defines a map that allows bidirectional lookup between key and values.
    * <p>
  @@ -88,9 +90,11 @@
        * <pre>
        * BidiMap map = new DualHashBidiMap();
        * MapIterator it = map.mapIterator();
  -     * Object key = it.next();
  -     * Object value = it.getValue();
  -     * it.setValue("newValue");
  +     * while (it.hasNext()) {
  +     *   Object key = it.next();
  +     *   Object value = it.getValue();
  +     *   it.setValue("newValue");
  +     * }
        * </pre>
        * 
        * @return a map iterator
  
  
  
  1.5       +24 -4     jakarta-commons/collections/src/test/org/apache/commons/collections/AbstractTestBidiMap.java
  
  Index: AbstractTestBidiMap.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/collections/src/test/org/apache/commons/collections/AbstractTestBidiMap.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- AbstractTestBidiMap.java	1 Nov 2003 18:47:18 -0000	1.4
  +++ AbstractTestBidiMap.java	2 Nov 2003 15:27:54 -0000	1.5
  @@ -64,6 +64,8 @@
   import java.util.NoSuchElementException;
   import java.util.Set;
   
  +import org.apache.commons.collections.iterators.MapIterator;
  +
   /**
    * Abstract test class for {@link BidiMap} methods and contracts.
    * 
  @@ -491,12 +493,14 @@
           }
           try {
               it.remove();
  -        } catch (UnsupportedOperationException ex) {
           } catch (IllegalStateException ex) {
           }
           try {
               it.setValue(null);
  -        } catch (UnsupportedOperationException ex) {
  +        } catch (IllegalStateException ex) {
  +        }
  +        try {
  +            it.asMapEntry();
           } catch (IllegalStateException ex) {
           }
           verify();
  @@ -509,12 +513,28 @@
           MapIterator it = bidi.mapIterator();
           
           assertEquals(true, it.hasNext());
  +        Map.Entry lastEntry = null;
  +        Object lastKey = null;
  +        Object lastValue = null;
           while (it.hasNext()) {
               Object key = it.next();
               assertSame(key, it.getKey());
           
               Object value = it.getValue();
               assertSame(bidi.get(key), value);
  +            
  +            Map.Entry entry = it.asMapEntry();
  +            assertTrue(entry != lastEntry);
  +            if (lastKey != null && lastValue != null) {
  +                assertSame(lastKey, lastEntry.getKey());
  +                assertSame(lastValue, lastEntry.getValue());
  +            }
  +            assertSame(key, entry.getKey());
  +            assertSame(value, entry.getValue());
  +            
  +            lastEntry = entry;
  +            lastKey = key;
  +            lastValue = value;
           }
           verify();
       }
  
  
  
  1.8       +90 -2     jakarta-commons/collections/src/test/org/apache/commons/collections/TestIteratorUtils.java
  
  Index: TestIteratorUtils.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/collections/src/test/org/apache/commons/collections/TestIteratorUtils.java,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- TestIteratorUtils.java	5 Oct 2003 21:17:40 -0000	1.7
  +++ TestIteratorUtils.java	2 Nov 2003 15:27:54 -0000	1.8
  @@ -424,6 +424,94 @@
           return IteratorUtils.unmodifiableListIterator(list.listIterator());
       }
   
  +    //-----------------------------------------------------------------------
  +    /**
  +     * Test empty iterator
  +     */
  +    public void testEmptyIterator() {
  +        assertEquals(false, IteratorUtils.EMPTY_ITERATOR.hasNext());
  +        IteratorUtils.EMPTY_ITERATOR.reset();
  +        assertSame(IteratorUtils.EMPTY_ITERATOR, IteratorUtils.EMPTY_ITERATOR);
  +        assertSame(IteratorUtils.EMPTY_ITERATOR, IteratorUtils.emptyIterator());
  +        try {
  +            IteratorUtils.EMPTY_ITERATOR.next();
  +            fail();
  +        } catch (NoSuchElementException ex) {}
  +        try {
  +            IteratorUtils.EMPTY_ITERATOR.remove();
  +            fail();
  +        } catch (IllegalStateException ex) {}
  +    }
  +    
  +    //-----------------------------------------------------------------------
  +    /**
  +     * Test empty list iterator
  +     */
  +    public void testEmptyListIterator() {
  +        assertEquals(false, IteratorUtils.EMPTY_LIST_ITERATOR.hasNext());
  +        assertEquals(0, IteratorUtils.EMPTY_LIST_ITERATOR.nextIndex());
  +        assertEquals(-1, IteratorUtils.EMPTY_LIST_ITERATOR.previousIndex());
  +        IteratorUtils.EMPTY_LIST_ITERATOR.reset();
  +        assertSame(IteratorUtils.EMPTY_LIST_ITERATOR, IteratorUtils.EMPTY_LIST_ITERATOR);
  +        assertSame(IteratorUtils.EMPTY_LIST_ITERATOR, IteratorUtils.emptyListIterator());
  +        try {
  +            IteratorUtils.EMPTY_LIST_ITERATOR.next();
  +            fail();
  +        } catch (NoSuchElementException ex) {}
  +        try {
  +            IteratorUtils.EMPTY_LIST_ITERATOR.previous();
  +            fail();
  +        } catch (NoSuchElementException ex) {}
  +        try {
  +            IteratorUtils.EMPTY_LIST_ITERATOR.remove();
  +            fail();
  +        } catch (IllegalStateException ex) {}
  +        try {
  +            IteratorUtils.EMPTY_LIST_ITERATOR.set(null);
  +            fail();
  +        } catch (IllegalStateException ex) {}
  +        try {
  +            IteratorUtils.EMPTY_LIST_ITERATOR.add(null);
  +            fail();
  +        } catch (UnsupportedOperationException ex) {}
  +    }
  +    
  +    //-----------------------------------------------------------------------
  +    /**
  +     * Test empty map iterator
  +     */
  +    public void testEmptyMapIterator() {
  +        assertEquals(false, IteratorUtils.EMPTY_MAP_ITERATOR.hasNext());
  +        IteratorUtils.EMPTY_MAP_ITERATOR.reset();
  +        assertSame(IteratorUtils.EMPTY_MAP_ITERATOR, IteratorUtils.EMPTY_MAP_ITERATOR);
  +        assertSame(IteratorUtils.EMPTY_MAP_ITERATOR, IteratorUtils.emptyMapIterator());
  +        try {
  +            IteratorUtils.EMPTY_MAP_ITERATOR.next();
  +            fail();
  +        } catch (NoSuchElementException ex) {}
  +        try {
  +            IteratorUtils.EMPTY_MAP_ITERATOR.remove();
  +            fail();
  +        } catch (IllegalStateException ex) {}
  +        try {
  +            IteratorUtils.EMPTY_MAP_ITERATOR.getKey();
  +            fail();
  +        } catch (IllegalStateException ex) {}
  +        try {
  +            IteratorUtils.EMPTY_MAP_ITERATOR.getValue();
  +            fail();
  +        } catch (IllegalStateException ex) {}
  +        try {
  +            IteratorUtils.EMPTY_MAP_ITERATOR.setValue(null);
  +            fail();
  +        } catch (IllegalStateException ex) {}
  +        try {
  +            IteratorUtils.EMPTY_MAP_ITERATOR.asMapEntry();
  +            fail();
  +        } catch (IllegalStateException ex) {}
  +    }
  +    
  +    //-----------------------------------------------------------------------
   	/**
   	 * Test next() and hasNext() for an immutable Iterator.
   	 */
  
  
  
  1.1                  jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/ResetableMapIterator.java
  
  Index: ResetableMapIterator.java
  ===================================================================
  /*
   * $Header: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/ResetableMapIterator.java,v
1.1 2003/11/02 15:27:54 scolebourne Exp $
   * ====================================================================
   *
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 1999-2003 The Apache Software Foundation.  All rights
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer.
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution, if
   *    any, must include the following acknowledgement:
   *       "This product includes software developed by the
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowledgement may appear in the software itself,
   *    if and wherever such third-party acknowledgements normally appear.
   *
   * 4. The names "The Jakarta Project", "Commons", and "Apache Software
   *    Foundation" must not be used to endorse or promote products derived
   *    from this software without prior written permission. For written
   *    permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache"
   *    nor may "Apache" appear in their names without prior written
   *    permission of the Apache Software Foundation.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   *
   */
  package org.apache.commons.collections.iterators;
  
  /** 
   * Interface implemented by those map iterators that can be reset back 
   * to an initial state.
   *
   * @since Commons Collections 3.0
   * @version $Revision: 1.1 $ $Date: 2003/11/02 15:27:54 $
   * 
   * @author Stephen Colebourne
   */
  public interface ResetableMapIterator extends MapIterator, ResetableIterator {
  
      /**
       * Resets the iterator back to the position at which the iterator
       * was created.
       */
      public void reset();
  
  }
  
  
  
  1.1                  jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/MapIterator.java
  
  Index: MapIterator.java
  ===================================================================
  /*
   * $Header: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/iterators/MapIterator.java,v
1.1 2003/11/02 15:27:54 scolebourne Exp $
   * ====================================================================
   *
   * The Apache Software License, Version 1.1
   *
   * Copyright (c) 2001-2003 The Apache Software Foundation.  All rights
   * reserved.
   *
   * Redistribution and use in source and binary forms, with or without
   * modification, are permitted provided that the following conditions
   * are met:
   *
   * 1. Redistributions of source code must retain the above copyright
   *    notice, this list of conditions and the following disclaimer.
   *
   * 2. Redistributions in binary form must reproduce the above copyright
   *    notice, this list of conditions and the following disclaimer in
   *    the documentation and/or other materials provided with the
   *    distribution.
   *
   * 3. The end-user documentation included with the redistribution, if
   *    any, must include the following acknowledgement:
   *       "This product includes software developed by the
   *        Apache Software Foundation (http://www.apache.org/)."
   *    Alternately, this acknowledgement may appear in the software itself,
   *    if and wherever such third-party acknowledgements normally appear.
   *
   * 4. The names "The Jakarta Project", "Commons", and "Apache Software
   *    Foundation" must not be used to endorse or promote products derived
   *    from this software without prior written permission. For written
   *    permission, please contact apache@apache.org.
   *
   * 5. Products derived from this software may not be called "Apache"
   *    nor may "Apache" appear in their names without prior written
   *    permission of the Apache Software Foundation.
   *
   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   * SUCH DAMAGE.
   * ====================================================================
   *
   * This software consists of voluntary contributions made by many
   * individuals on behalf of the Apache Software Foundation.  For more
   * information on the Apache Software Foundation, please see
   * <http://www.apache.org/>.
   *
   */
  package org.apache.commons.collections.iterators;
  
  import java.util.Iterator;
  import java.util.Map;
  
  /**
   * Defines an iterator that operates over a <code>Map</code>.
   * <p>
   * This iterator is a special version designed for maps. It is much more
   * efficient to use this rather than an entry set iterator where the option
   * is available.
   * <p>
   * 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.
   * <p>
   * In use, this iterator iterates through the keys in the map. After each call
   * to <code>next()</code>, the <code>getValue()</code> method provides
direct
   * access to the value. The value can also be set using <code>setValue()</code>.
   * <pre>
   * MapIterator it = map.mapIterator();
   * while (it.hasNext()) {
   *   Object key = it.next();
   *   Object value = it.getValue();
   *   it.setValue(newValue);
   * }
   * </pre>
   *  
   * @since Commons Collections 3.0
   * @version $Revision: 1.1 $ $Date: 2003/11/02 15:27:54 $
   *
   * @author Stephen Colebourne
   */
  public interface MapIterator extends Iterator {
      
      /**
       * Checks to see if there are more entries still to be iterated.
       *
       * @return <code>true</code> if the iterator has more elements
       */
      boolean hasNext();
  
      /**
       * Gets the next <em>key</em> from the <code>Map</code>.
       *
       * @return the next key in the iteration
       * @throws NoSuchElementException if the iteration is finished
       */
      Object next();
  
      //-----------------------------------------------------------------------
      /**
       * Gets the current key, which is the key returned by the last call
       * to <code>next()</code>.
       *
       * @return the current key
       * @throws IllegalStateException if <code>next()</code> has not yet been
called
       */
      Object getKey();
  
      /**
       * Gets the current value, which is the value associated with the last key
       * returned by <code>next()</code>.
       *
       * @return the current value
       * @throws IllegalStateException if <code>next()</code> has not yet been
called
       */
      Object getValue();
  
      //-----------------------------------------------------------------------
      /**
       * Gets the last returned key-value pair from the underlying <code>Map</code>
       * as a Map Entry instance.
       * <p>
       * The returned entry must not change when <code>next</code> is called.
       * Changes made to the entry via <code>setValue</code> must change the map.
       * 
       * @return the last return key-value pair as an independent Map Entry
       * @throws IllegalStateException if <code>next()</code> has not yet been
called
       * @throws IllegalStateException if <code>remove()</code> has been called
since the
       *  last call to <code>next()</code>
       */
      Map.Entry asMapEntry();
      
      //-----------------------------------------------------------------------
      /**
       * Removes the last returned key from the underlying <code>Map</code> (optional
operation).
       * <p>
       * This method can be called once per call to <code>next()</code>.
       *
       * @throws UnsupportedOperationException if remove is not supported by the map
       * @throws IllegalStateException if <code>next()</code> has not yet been
called
       * @throws IllegalStateException if <code>remove()</code> has already been
called
       *  since the last call to <code>next()</code>
       */
      void remove();
      
      /**
       * Sets the value associated with the current key (optional operation).
       *
       * @param value  the new value
       * @return the previous value
       * @throws UnsupportedOperationException if setValue is not supported by the map
       * @throws IllegalStateException if <code>next()</code> has not yet been
called
       * @throws IllegalStateException if <code>remove()</code> has been called
since the
       *  last call to <code>next()</code>
       */
      Object setValue(Object value);
  
  }
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message