Update MapIterator to remove asMapEntry

Add OrderedMapIterator
Rename DefaultMapIterator


git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@131336 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/collections/IteratorUtils.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/IteratorUtils.java,v 1.14 2003/11/02 15:27:53 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/IteratorUtils.java,v 1.15 2003/11/08 18:43:12 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -70,7 +70,6 @@ import java.util.List;
 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;
@@ -87,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.ResetableOrderedMapIterator;
 import org.apache.commons.collections.iterators.SingletonIterator;
 import org.apache.commons.collections.iterators.SingletonListIterator;
 import org.apache.commons.collections.iterators.TransformIterator;
@@ -97,7 +97,7 @@ import org.apache.commons.collections.iterators.TransformIterator;
  * {@link org.apache.commons.collections.iterators} subpackage.
  *
  * @since Commons Collections 2.1
- * @version $Revision: 1.14 $ $Date: 2003/11/02 15:27:53 $
+ * @version $Revision: 1.15 $ $Date: 2003/11/08 18:43:12 $
  * 
  * @author Stephen Colebourne
  * @author Phil Steitz
@@ -118,6 +118,10 @@ public class IteratorUtils {
      * A map iterator over no elements
      */    
     public static final ResetableMapIterator EMPTY_MAP_ITERATOR = new EmptyMapIterator();
+    /**
+     * A map iterator over no elements
+     */    
+    public static final ResetableOrderedMapIterator EMPTY_ORDERED_MAP_ITERATOR = new EmptyOrderedMapIterator();
 
     /**
      * Prevents instantiation.
@@ -164,6 +168,18 @@ public class IteratorUtils {
         return EMPTY_MAP_ITERATOR;
     }
 
+    /**
+     * Gets an empty ordered map iterator.
+     * <p>
+     * This iterator is a valid map iterator object that will iterate 
+     * over nothing.
+     *
+     * @return  a list iterator over nothing
+     */
+    public static ResetableOrderedMapIterator emptyOrderedMapIterator() {
+        return EMPTY_ORDERED_MAP_ITERATOR;
+    }
+
     /**
      * Gets a singleton iterator.
      * <p>
@@ -850,7 +866,7 @@ public class IteratorUtils {
         EmptyMapIterator() {
             super();
         }
-
+        
         public Object getKey() {
             throw new IllegalStateException("Iterator contains no elements");
         }
@@ -862,9 +878,24 @@ public class IteratorUtils {
         public Object setValue(Object value) {
             throw new IllegalStateException("Iterator contains no elements");
         }
+    }
+
+    //-----------------------------------------------------------------------    
+    /**
+     * EmptyOrderedMapIterator class
+     */
+    static class EmptyOrderedMapIterator extends EmptyMapIterator implements ResetableOrderedMapIterator {
         
-        public Entry asMapEntry() {
+        EmptyOrderedMapIterator() {
-            throw new IllegalStateException("Iterator contains no elements");
+            super();
+        }
+        
+        public boolean hasPrevious() {
+            return false;
+        }
+        
+        public Object previous() {
+            throw new NoSuchElementException("Iterator contains no elements");
         }
     }
 

src/java/org/apache/commons/collections/decorators/OrderedMap.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/decorators/Attic/OrderedMap.java,v 1.5 2003/11/04 23:36:23 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/decorators/Attic/OrderedMap.java,v 1.6 2003/11/08 18:43:12 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -66,7 +66,7 @@ import java.util.List;
 import java.util.Map;
 import java.util.Set;
 
-import org.apache.commons.collections.iterators.DefaultMapIterator;
+import org.apache.commons.collections.iterators.EntrySetMapIterator;
 import org.apache.commons.collections.iterators.MapIterator;
 import org.apache.commons.collections.pairs.AbstractMapEntry;
 
@@ -80,7 +80,7 @@ import org.apache.commons.collections.pairs.AbstractMapEntry;
  * original position in the iteration.
  *
  * @since Commons Collections 3.0
- * @version $Revision: 1.5 $ $Date: 2003/11/04 23:36:23 $
+ * @version $Revision: 1.6 $ $Date: 2003/11/08 18:43:12 $
  * 
  * @author Henri Yandell
  * @author Stephen Colebourne
@@ -146,7 +146,7 @@ public class OrderedMap extends AbstractMapDecorator implements Map {
 
     //-----------------------------------------------------------------------
     public MapIterator mapIterator() {
-        return new DefaultMapIterator(this);
+        return new EntrySetMapIterator(this);
     }
     
     public Set keySet() {

src/java/org/apache/commons/collections/iterators/AbstractMapIteratorDecorator.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/AbstractMapIteratorDecorator.java,v 1.1 2003/11/02 16:29:12 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/AbstractMapIteratorDecorator.java,v 1.2 2003/11/08 18:43:12 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -57,15 +57,13 @@
  */
 package org.apache.commons.collections.iterators;
 
-import java.util.Map;
-
 /**
  * Provides basic behaviour for decorating a map iterator with extra functionality.
  * <p>
  * All methods are forwarded to the decorated map iterator.
  *
  * @since Commons Collections 3.0
- * @version $Revision: 1.1 $ $Date: 2003/11/02 16:29:12 $
+ * @version $Revision: 1.2 $ $Date: 2003/11/08 18:43:12 $
  * 
  * @author Stephen Colebourne
  */
@@ -123,8 +121,4 @@ public class AbstractMapIteratorDecorator implements MapIterator {
         return iterator.setValue(obj);
     }
 
-    public Map.Entry asMapEntry() {
-        return iterator.asMapEntry();
-    }
-
 }

src/java/org/apache/commons/collections/iterators/EntrySetMapIterator.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/Attic/DefaultMapIterator.java,v 1.1 2003/11/02 23:40:53 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/EntrySetMapIterator.java,v 1.1 2003/11/08 18:43:13 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -60,10 +60,9 @@ package org.apache.commons.collections.iterators;
 import java.util.Iterator;
 import java.util.Map;
 
-import org.apache.commons.collections.pairs.TiedMapEntry;
-
 /**
  * Implements a <code>MapIterator</code> using a Map entrySet.
+ * Reverse iteration is not supported.
  * <pre>
  * MapIterator it = map.mapIterator();
  * while (it.hasNext()) {
@@ -74,11 +73,11 @@ import org.apache.commons.collections.pairs.TiedMapEntry;
  * </pre>
  *  
  * @since Commons Collections 3.0
- * @version $Revision: 1.1 $ $Date: 2003/11/02 23:40:53 $
+ * @version $Revision: 1.1 $ $Date: 2003/11/08 18:43:13 $
  *
  * @author Stephen Colebourne
  */
-public class DefaultMapIterator implements ResetableMapIterator {
+public class EntrySetMapIterator implements MapIterator, ResetableMapIterator {
     
     private final Map map;
     private Iterator iterator;
@@ -90,7 +89,7 @@ public class DefaultMapIterator implements ResetableMapIterator {
      * 
      * @param map  the map to iterate over
      */
-    public DefaultMapIterator(Map map) {
+    public EntrySetMapIterator(Map map) {
         super();
         this.map = map;
         this.iterator = map.entrySet().iterator();
@@ -118,6 +117,7 @@ public class DefaultMapIterator implements ResetableMapIterator {
         return last.getKey();
     }
 
+    //-----------------------------------------------------------------------
     /**
      * Removes the last returned key from the underlying <code>Map</code>.
      * <p>
@@ -184,24 +184,6 @@ public class DefaultMapIterator implements ResetableMapIterator {
     }
 
     //-----------------------------------------------------------------------
-    /**
-     * Gets the last returned key-value pair from the underlying <code>Map</code>
-     * as a Map Entry instance.
-     * <p>
-     * The returned entry will not change when <code>next</code> is called.
-     * Changes made to the entry via <code>setValue</code> will change the map.
-     * If you call setValue after next on the iterator, a ConcurrentModificationException
-     * may occur.
-     * 
-     * @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>
-     */
-    public Map.Entry asMapEntry() {
-        return new TiedMapEntry(map, getKey());
-    }        
-    
     /**
      * Resets the state of the iterator.
      */

src/java/org/apache/commons/collections/iterators/MapIterator.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/Attic/MapIterator.java,v 1.1 2003/11/02 15:27:54 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/Attic/MapIterator.java,v 1.2 2003/11/08 18:43:13 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -58,7 +58,6 @@
 package org.apache.commons.collections.iterators;
 
 import java.util.Iterator;
-import java.util.Map;
 
 /**
  * Defines an iterator that operates over a <code>Map</code>.
@@ -83,7 +82,7 @@ import java.util.Map;
  * </pre>
  *  
  * @since Commons Collections 3.0
- * @version $Revision: 1.1 $ $Date: 2003/11/02 15:27:54 $
+ * @version $Revision: 1.2 $ $Date: 2003/11/08 18:43:13 $
  *
  * @author Stephen Colebourne
  */
@@ -123,21 +122,6 @@ public interface MapIterator extends Iterator {
      */
     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).

src/java/org/apache/commons/collections/iterators/OrderedMapIterator.java

@@ -0,0 +1,87 @@
+/*
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/Attic/OrderedMapIterator.java,v 1.1 2003/11/08 18:43:12 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;
+
+/**
+ * Defines an iterator that operates over an ordered <code>Map</code>.
+ * <p>
+ * This iterator allows both forward and reverse iteration through the map.
+ *  
+ * @since Commons Collections 3.0
+ * @version $Revision: 1.1 $ $Date: 2003/11/08 18:43:12 $
+ *
+ * @author Stephen Colebourne
+ */
+public interface OrderedMapIterator extends MapIterator {
+    
+    /**
+     * Checks to see if there is a previous entry that can be iterated to.
+     *
+     * @return <code>true</code> if the iterator has a previous element
+     */
+    boolean hasPrevious();
+
+    /**
+     * Gets the previous <em>key</em> from the <code>Map</code>.
+     *
+     * @return the previous key in the iteration
+     * @throws NoSuchElementException if the iteration is finished
+     */
+    Object previous();
+
+}

src/java/org/apache/commons/collections/iterators/ResetableOrderedMapIterator.java

@@ -0,0 +1,77 @@
+/*
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/Attic/ResetableOrderedMapIterator.java,v 1.1 2003/11/08 18:43:13 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/08 18:43:13 $
+ * 
+ * @author Stephen Colebourne
+ */
+public interface ResetableOrderedMapIterator extends OrderedMapIterator, ResetableMapIterator {
+
+    /**
+     * Resets the iterator back to the position at which the iterator
+     * was created.
+     */
+    public void reset();
+
+}

src/java/org/apache/commons/collections/iterators/UnmodifiableMapIterator.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/UnmodifiableMapIterator.java,v 1.1 2003/11/02 18:29:59 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/iterators/UnmodifiableMapIterator.java,v 1.2 2003/11/08 18:43:13 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -57,16 +57,13 @@
  */
 package org.apache.commons.collections.iterators;
 
-import java.util.Map.Entry;
-
 import org.apache.commons.collections.Unmodifiable;
-import org.apache.commons.collections.pairs.UnmodifiableMapEntry;
 
 /** 
  * Decorates a map iterator such that it cannot be modified.
  *
  * @since Commons Collections 3.0
- * @version $Revision: 1.1 $ $Date: 2003/11/02 18:29:59 $
+ * @version $Revision: 1.2 $ $Date: 2003/11/08 18:43:13 $
  * 
  * @author Stephen Colebourne
  */
@@ -120,10 +117,6 @@ public final class UnmodifiableMapIterator implements MapIterator, Unmodifiable
         return iterator.getValue();
     }
 
-    public Entry asMapEntry() {
-        return new UnmodifiableMapEntry(getKey(), getValue());
-    }
-
     public Object setValue(Object value) {
         throw new UnsupportedOperationException("setValue() is not supported");
     }