org.mattbusche.util.partition
Class GroupIterator<M,V>

java.lang.Object
  org.mattbusche.util.partition.GroupIterator<M,V>

public class GroupIterator<M,V>
extends java.lang.Object

A bidirectional iterator for traversing the Entry objects of a Group.

GroupIterator design differs significantly from the design of iterators in the Java Collections Framework (JCF):

1. GroupIterators point to a particular list Entry. In contrast, iterators from the JCF point between two list entries.
2. GroupIterators are only invalidated by those operations that remove the Entry they point to from their Group. In particular, memory reallocation events do not invalidate GroupIterators. In contrast, any update to a JCF container necessarily invalidates all iterators on that container except the one iterator used to perform that update (if any).
3. The behavior of an invalidated GroupIterator is undefined. In contrast, any use of an invalidated iterator from the JCF, results in the well-defined behavior of throwing a ConcurrentModificationException.

Because GroupIterators point to a particular list entry and because they are not regularly invalidated, they can be used as semi-permanent references to Group entries. This is at the cost of user safety: accidental use of an invalidated iterator will not produce an exception, but instead has undefined behavior.

Notes on GroupIterator invalidation:

The behavior of an invalidated GroupIterator is undefined so one must take care to avoid unintentional iterator invalidation. For this Java-based implementation of partition, the only way a GroupIterator can become invalidated is for the Entry pointed to by the GroupIterator to be removed from its Group. This may seem obvious, but remember that any operation that inserts an Entry to a Group also removes that same Entry from its previous Group; so all operations that affect Group membership can invalidate GroupIterators. Also note that the Domain's resize methods can be used to eliminate Entrys from the Domain entirely (and from their Groups).

Constructor Summary

GroupIterator(GroupIterator<M,V> iter)
Copy constructor.

Method Summary

void	addAfter(int id) Removes the Entry with the given id from the Group with which it was previously a member (if any), and adds it into this iterator's Group immediately after the position pointed to by this iterator.
void	addBefore(int id) Removes the Entry with the given id from the Group with which it was previously a member (if any), and adds it into this iterator's Group immediately before the position pointed to by this iterator.
GroupIterator<M,V>	dec() Decrements the iterator to the previous list position and returns a reference to itself.
Group<M,V>	getContainer() Returns the Group associated with this iterator.
Entry<M>	getEntry() Returns the Entry object pointed to by this iterator.
GroupIterator<M,V>	inc() Increments the iterator to the next list position and returns a reference to itself.
boolean	isAfterBack() Returns true if this iterator is pointing one logical position after the last Entry in the list, and false if it is pointing to any list Entry.
boolean	isAtBack() Returns true if this iterator points to the last Entry of a non-empty list, or to the beforeFront position of an empty list; and false otherwise.
boolean	isAtFront() Returns true if this iterator points to the first Entry of a non-empty list, or to the afterBack position of an empty list; and false otherwise.
boolean	isBeforeFront() Returns true if this iterator is pointing one logical position before the first Entry in the list, and false if it is pointing to any list Entry.
Entry<M>	removeAndDec() Removes and returns the Entry pointed to by this iterator from its Group's list, and updates this iterator to point to the previous Entry in the list.
Entry<M>	removeAndInc() Removes and returns the Entry pointed to by this iterator from its Group's list, and updates this iterator to point to the next Entry in the list.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GroupIterator

public GroupIterator(GroupIterator<M,V> iter)

Copy constructor.

Method Detail

inc

public GroupIterator<M,V> inc()

Increments the iterator to the next list position and returns a reference to itself.

dec

public GroupIterator<M,V> dec()

Decrements the iterator to the previous list position and returns a reference to itself.

isBeforeFront

public boolean isBeforeFront()

Returns true if this iterator is pointing one logical position before the first Entry in the list, and false if it is pointing to any list Entry.

isAfterBack

public boolean isAfterBack()

Returns true if this iterator is pointing one logical position after the last Entry in the list, and false if it is pointing to any list Entry.

isAtFront

public boolean isAtFront()

Returns true if this iterator points to the first Entry of a non-empty list, or to the afterBack position of an empty list; and false otherwise.

isAtBack

public boolean isAtBack()

Returns true if this iterator points to the last Entry of a non-empty list, or to the beforeFront position of an empty list; and false otherwise.

getEntry

public Entry<M> getEntry()

Returns the Entry object pointed to by this iterator.

Throws:

PartitionException - if this iterator isBeforeFront() or isAfterBack().

getContainer

public Group<M,V> getContainer()

Returns the Group associated with this iterator.

addBefore

public void addBefore(int id)

Removes the Entry with the given id from the Group with which it was previously a member (if any), and adds it into this iterator's Group immediately before the position pointed to by this iterator.

Computational Complexity: Constant.

Throws:

java.lang.NullPointerException - if this iterator's Group is not associated with a Domain.

ArrayIndexOutOfBoundException - if id is not a member of the associated Domain.

addAfter

public void addAfter(int id)

Removes the Entry with the given id from the Group with which it was previously a member (if any), and adds it into this iterator's Group immediately after the position pointed to by this iterator.

Computational Complexity: Constant.

Throws:

java.lang.NullPointerException - if this iterator's Group is not associated with a Domain.

ArrayIndexOutOfBoundException - if id is not a member of the associated Domain.

removeAndInc

public Entry<M> removeAndInc()

Removes and returns the Entry pointed to by this iterator from its Group's list, and updates this iterator to point to the next Entry in the list.

Computational Complexity: Constant.

Throws:

PartitionException - if this iterator isBeforeFront() or isAfterBack().

removeAndDec

public Entry<M> removeAndDec()

Removes and returns the Entry pointed to by this iterator from its Group's list, and updates this iterator to point to the previous Entry in the list.

Computational Complexity: Constant.

Throws:

PartitionException - if this iterator isBeforeFront() or isAfterBack().