You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sc...@apache.org on 2003/11/02 16:27:54 UTC
cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections/iterators ResetableMapIterator.java MapIterator.java
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