goldman.collection
Interface Locator<E>

All Superinterfaces:
Cloneable, Iterator<E>
All Known Subinterfaces:
PositionalCollectionLocator<E>, PriorityQueueLocator<E>
All Known Implementing Classes:
AbstractCollection.AbstractLocator, AbstractCollection.VisitingIterator, Array.BasicMarker, Array.Marker, BinaryHeap.BinaryHeapLocator, BinarySearchTree.Tracker, BTree.Marker, DirectAddressing.Marker, LeftistHeap.Tracker, PairingHeap.Tracker, SeparateChaining.Marker, SinglyLinkedList.Tracker, SkipList.Tracker, TrackedArray.Tracker, Trie.Tracker

public interface Locator<E>
extends Iterator<E>, Cloneable

A locator provides the user with a mechanism for remembering a location within a collection without exposing the internal representation. A locator can be used to advance or retreat through a collection, or to directly an element in the collection (in order to remove it, for example) without incurring the cost of searching the collection for that element.


Method Summary
 boolean advance()
          Advances to the next element in the collection (if there is one) and returns true.
 E get()
          Returns the element associated with this locator.
 void ignoreConcurrentModifications(boolean ignore)
          If ignore is true then concurrent modification exceptions are disabled.
 void ignorePriorConcurrentModifications()
          Any prior concurrent modifications are ignored, but if another critical mutator is executed then any later access will result in a concurrent modification exception.
 boolean inCollection()
          Returns true if and only if the locator is at an element of the collection.
 boolean retreat()
          Retreats to the previous element in the collection (if there is one) and returns true.
 
Methods inherited from interface java.util.Iterator
hasNext, next, remove
 

Method Detail

advance

boolean advance()
Advances to the next element in the collection (if there is one) and returns true. If the locator is already at the last element of the collection then false is returned and the locator is moved to AFT. If a call to advance is made when the locator is at AFT, an AtBoundaryException is thrown. Starting with the locator at FORE and calling advance repeatedly until false is returned will reach each element in the collection exactly once.


get

E get()
Returns the element associated with this locator. When a tracker is used, the element associated with the locator might no longer be in the collection. If desired, the inCollection method can be used to determine if a tracked element is currently in the collection. If the locator is at FORE or AFT then a NoSuchElementException is thrown.


ignoreConcurrentModifications

void ignoreConcurrentModifications(boolean ignore)
If ignore is true then concurrent modification exceptions are disabled. If ignore is false, it sets the state of the iterator so that (future) concurrent modifications will be noticed and result in concurrent modification exceptions.


ignorePriorConcurrentModifications

void ignorePriorConcurrentModifications()
Any prior concurrent modifications are ignored, but if another critical mutator is executed then any later access will result in a concurrent modification exception.


inCollection

boolean inCollection()
Returns true if and only if the locator is at an element of the collection.


retreat

boolean retreat()
Retreats to the previous element in the collection (if there is one) and returns true. If the locator is already at the first element of the collection then false is returned and the locator is moved to FORE. If a call to retreat is made when the Locator is at FORE, an AtBoundaryException is thrown. Starting with the locator at AFT and calling retreat repeatedly until false is returned will reach each element in the underlying collection exactly once, in the reverse order.