goodslib
Class MapQueryIterator

java.lang.Object
  extended bygoodslib.MapQueryIterator
All Implemented Interfaces:
QueryIterator

public class MapQueryIterator
extends java.lang.Object
implements QueryIterator

Creates a goodslib.QueryIterator to iterate over the supplied Map. A shallow copy of the map is created. This means that this iterator captures the state of the map as it was at the iterator's creation time and the map is not kept up-to-date with the original.

This class is guaranteed to work correctly even if you have multiple callers using the iterator at the same time. Note however that if subsequent calls to getNext during runtime are not marching sequentially through the iterator, a large performance hit may be observed.

No guarantees are made if the iterator is associated with a WeakHashMap or any other Map that uses weak references.

This class is believed to be threadsafe.

Copyright: Copyright (c) 2004

Company: Alphatech, Inc.


Constructor Summary
MapQueryIterator(java.util.Map map, java.lang.String keyName)
          An exception will be thrown if the supplied map object does not implement a public clone() method.
 
Method Summary
 java.lang.Object getByKey(java.lang.String keyName, java.lang.Object keyValue)
          To be consistent with the documentation for QueryInterface, getByKey does not modify the state of the iterator.
 java.lang.Object getFirst()
          Returns the first object indexed by this iterator.
 java.lang.String getKeyName()
           
 java.lang.Object getNext(java.lang.Object prevObject, int prevIndex)
          Returns the next object in the iteration list.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MapQueryIterator

public MapQueryIterator(java.util.Map map,
                        java.lang.String keyName)
                 throws java.lang.SecurityException,
                        java.lang.NoSuchMethodException,
                        java.lang.reflect.InvocationTargetException,
                        java.lang.IllegalArgumentException,
                        java.lang.IllegalAccessException
An exception will be thrown if the supplied map object does not implement a public clone() method.

Parameters:
map - Map The map over which this iterator will operate. The Map must supply a public clone method.
keyName - String Name of the key field. All calls to getByKey must use this key name.
Throws:
java.lang.SecurityException
java.lang.NoSuchMethodException
java.lang.reflect.InvocationTargetException
java.lang.IllegalArgumentException
java.lang.IllegalAccessException
Method Detail

getKeyName

public java.lang.String getKeyName()

getFirst

public java.lang.Object getFirst()
Returns the first object indexed by this iterator. This moves the internal iterator cached location to the second item.

Specified by:
getFirst in interface QueryIterator
Returns:
Object First value in the map (according to the original map's ordering scheme).

getNext

public java.lang.Object getNext(java.lang.Object prevObject,
                                int prevIndex)
Returns the next object in the iteration list. This method verifies first that a reference to prevObject exists at iteration position prevIndex. If prevObject and prevIndex do not agree or are otherwise invalid, an exception is thrown. Assuming no problems were encountered, the next object in the iteration list is extracted and the internal iterator cache is updated to optimize the next call to getNext.

If getNext is called with valid arguments, but the previous object and index are not actually the most recently returned values, this method will still function properly, but a time-consuming search may be required to find the next item.

Specified by:
getNext in interface QueryIterator
Parameters:
prevObject - Object reference returned by previous call of getNext or getFirst.
prevIndex - int index of previous object (starting from 0 for first object).
Returns:
Object next object or null if there are no more objects
Throws:
java.lang.IllegalArgumentException - Thrown if the object at prevIndex is not the same as prevObject (the actual references must match).

getByKey

public java.lang.Object getByKey(java.lang.String keyName,
                                 java.lang.Object keyValue)
To be consistent with the documentation for QueryInterface, getByKey does not modify the state of the iterator. This means that calls to getByKey are independent of calls to getNext and getFirst and will not impose any performance hits on otherwise normal getFirst + getNext iteration.

Specified by:
getByKey in interface QueryIterator
Parameters:
keyName - String
keyValue - Object
Returns:
Object