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

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

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

Maintains a doubly linked list of Entry<M> objects from a single associated Domain and may also be assigned a user-defined value of type V.

Read the package summary for introductory information about Group and its related classes.

An Entry may be added to a Group via add operations typical of linked lists, but each such add has the atypical side-affect of simultaneously removing the Entry from its previous Group membership (if any) all with constant computational complexity.

The following four terms are used consistently throughout to refer to key list positions:

• beforeFront - One position before the first entry in the list.
• front - The first entry in the list.
• back - The last entry in the list.
• afterBack - One position after the last entry in the list.

Constructor Summary

Group()
Constructs an empty Group with no Domain association and a null value.

Group(Domain<M,V> d)
Constructs an empty Group associated with Domain d and sets the Group's value to null.

Group(Domain<M,V> d, Group<M,V> g)
Constructs a Group that is a copy of g with the exception that its associated with Domain d.

Group(Domain<M,V> d, V v)
Constructs an empty Group associated with Domain d and sets the Group's value to v.

Method Summary

void	addAll() Adds all Entry objects from this Group's Domain to this Group's list (simultaneously removing them from the Groups with which they were previously a member).
void	addBack(Group<M,V> g) Moves all Entry objects from g to the back of this Group's Entry list.
void	addBack(int id) Adds the Entry with the given id from the Group's associated Domain to the back of this Group's list.
void	addFront(Group<M,V> g) Moves all Entry objects from Group g to the front of this Group's list.
void	addFront(int id) Adds the Entry with the given id from the Group's associated Domain to the front of this Group's list.
GroupIterator<M,V>	afterBack() Returns a GroupIterator pointing to the position after the last Entry in this Group's list.
GroupIterator<M,V>	back() Returns a GroupIterator pointing to the last Entry of this Group's list.
GroupIterator<M,V>	beforeFront() Returns a GroupIterator pointing to the position before the first Entry in this Group's list.
boolean	contains(int id) Returns true if this Group contains the Entry with the given id and false otherwise.
GroupIterator<M,V>	find(int id) Returns a GroupIterator pointing to the Entry from this list with the given id, or pointing to the afterBack() position if this Group does not contain the Entry with the given id.
GroupIterator<M,V>	front() Returns a GroupIterator pointing to the first Entry of this Group's list.
Domain<M,V>	getDomain() Returns the Domain associated with this Group (or null if this Group has no Domain association).
V	getValue() Returns the user provided value object associated with this Group.
Entry<M>	peekBack() Returns the Entry object at the back of the Group list while leaving the list unmodified.
Entry<M>	peekFront() Returns the Entry object at the front of the Group list while leaving the list unmodified.
Entry<M>	remove(int id) Removes the Entry with the given id from this Group's list and returns it.
void	removeAll() Removes all Entry objects from this Group's list.
Entry<M>	removeBack() Removes the Entry at the back of this Group's list and returns it.
Entry<M>	removeFront() Removes the Entry at the front of this Group's list and returns it.
void	setDomain(Domain<M,V> d) Associates this Group with d.
void	setValue(V v) Sets v as this Group's value.
int	size() Returns the number of Entry objects in this Group's list.
java.lang.String	toString() Prints the Group in the following format:

Methods inherited from class java.lang.Object

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

Constructor Detail

Group

public Group()

Constructs an empty Group with no Domain association and a null value. Few operations on a Group constructed in this way are permitted until a Domain object has been associated with the Group via the setDomain(org.mattbusche.util.partition.Domain) method.

Group

public Group(Domain<M,V> d)

Constructs an empty Group associated with Domain d and sets the Group's value to null.

Group

public Group(Domain<M,V> d,
             V v)

Constructs an empty Group associated with Domain d and sets the Group's value to v.

Group

public Group(Domain<M,V> d,
             Group<M,V> g)

Constructs a Group that is a copy of g with the exception that its associated with Domain d. Domain d must not be the same Domain as that associated with g.

Throws:

java.lang.NullPointerException - if d is null.

PartitionException - if g is associated with Domain d.

PartitionException - if an Entry of g has an ID not contained in d.

Method Detail

getDomain

public Domain<M,V> getDomain()

Returns the Domain associated with this Group (or null if this Group has no Domain association).

setDomain

public void setDomain(Domain<M,V> d)

Associates this Group with d. If this Group was not previously associated with d, then the Group's list is first cleared of any Entry objects from its current Domain association (if any). If this Group was already associated with d, then there is no effect.

getValue

public V getValue()

Returns the user provided value object associated with this Group.

setValue

public void setValue(V v)

Sets v as this Group's value.

size

public int size()

Returns the number of Entry objects in this Group's list.

contains

public boolean contains(int id)

Returns true if this Group contains the Entry with the given id and false otherwise.

Computational Complexity: Constant.

Throws:

java.lang.NullPointerException - if this Group has no Domain association.

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

peekFront

public Entry<M> peekFront()

Returns the Entry object at the front of the Group list while leaving the list unmodified.

Throws:

PartitionException - if the Group is empty.

peekBack

public Entry<M> peekBack()

Returns the Entry object at the back of the Group list while leaving the list unmodified.

Throws:

PartitionException - if the Group is empty.

addFront

public void addFront(int id)

Adds the Entry with the given id from the Group's associated Domain to the front of this Group's list. If the Entry was previously a member of a Group, it is first removed from that Group.

Computational Complexity: Constant.

Throws:

java.lang.NullPointerException - if this Group has no Domain association.

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

addBack

public void addBack(int id)

Adds the Entry with the given id from the Group's associated Domain to the back of this Group's list. If the Entry was previously a member of a Group, it is first removed from that Group.

Computational Complexity: Constant.

Throws:

java.lang.NullPointerException - if this Group has no Domain association.

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

addFront

public void addFront(Group<M,V> g)

Moves all Entry objects from Group g to the front of this Group's list.

Computational Complexity: Linear in the size of g.

Throws:

PartitionException - if Group g is not associated with the same Domain as this Group.

addBack

public void addBack(Group<M,V> g)

Moves all Entry objects from g to the back of this Group's Entry list.

Computational Complexity: Linear in the size of g.

Throws:

PartitionException - if Group g is not associated with the same Domain as this Group.

addAll

public void addAll()

Adds all Entry objects from this Group's Domain to this Group's list (simultaneously removing them from the Groups with which they were previously a member). Entry objects are listed in ascending ID order.

Computational Complexity: Linear in the size of this Group's Domain.

Throws:

java.lang.NullPointerException - if this Group has no Domain association.

removeFront

public Entry<M> removeFront()

Removes the Entry at the front of this Group's list and returns it.

Computational Complexity: Constant.

Throws:

PartitionException - if this Group is empty.

removeBack

public Entry<M> removeBack()

Removes the Entry at the back of this Group's list and returns it.

Computational Complexity: Constant.

Throws:

PartitionException - if this Group is empty.

remove

public Entry<M> remove(int id)

Removes the Entry with the given id from this Group's list and returns it.

Computational Complexity: Constant.

Throws:

PartitionException - if this Group does not contain the Entry with the given id.

java.lang.NullPointerException - if this Group has no Domain association.

removeAll

public void removeAll()

Removes all Entry objects from this Group's list.

Computational Complexity: Linear in the size of this Group.

front

public GroupIterator<M,V> front()

Returns a GroupIterator pointing to the first Entry of this Group's list. If this Group is empty, the returned GroupIterator will point to the afterBack() list position.

back

public GroupIterator<M,V> back()

Returns a GroupIterator pointing to the last Entry of this Group's list. If this Group is empty, the returned GroupIterator will point to the beforeFront() list position.

beforeFront

public GroupIterator<M,V> beforeFront()

Returns a GroupIterator pointing to the position before the first Entry in this Group's list.

afterBack

public GroupIterator<M,V> afterBack()

Returns a GroupIterator pointing to the position after the last Entry in this Group's list.

find

public GroupIterator<M,V> find(int id)

Returns a GroupIterator pointing to the Entry from this list with the given id, or pointing to the afterBack() position if this Group does not contain the Entry with the given id.

PLEASE NOTE THE EXCEPTIONAL CONDITION BELOW.

Throws:

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

toString

public java.lang.String toString()

Prints the Group in the following format:

       GroupValue:[Entry_1, Entry_2, ..., Entry_N]
 

where each Entry is printed as (id, member).

Overrides:

toString in class java.lang.Object