org.decisiondeck.xmcda_oo.utils
Class ExternalOrderingComparator<E>

java.lang.Object
  org.decisiondeck.xmcda_oo.utils.ExternalOrderingComparator<E>

Type Parameters:

E - the type of elements that may be compared by this comparator.

All Implemented Interfaces:

Comparator<E>

public class ExternalOrderingComparator<E>
extends Object
implements Comparator<E>

A comparator based on an externally defined set of objects. The set order is used to assign a position to each object. The order is then provided according to the external set order. This implies that this comparator may not be asked to compare objects that are outside its defined universe, that is, objects that do not exist in the order set. If asked to, it will throw an IllegalArgumentException.

This comparator imposes orderings that are consistent with equals.

Constructor Summary

ExternalOrderingComparator()

ExternalOrderingComparator(Collection<E> order)
Creates a new object initialized with the given collection, in order of iteration.

Method Summary

void	add(E elem) Adds the given element as the greatest of all elements already known to this object.
void	addAsWorst(E elem)
void	addInBetween(E previous, E elem, E next) Adds an element in-between two other elements.
void	clear()
int	compare(E o1, E o2) Compares its two arguments for order.
boolean	contains(Object o)
boolean	remove(Object o) Removes an element from this ordering if it is present.
void	replace(E oldElement, E newElement)
void	resetOrder(Collection<E> newOrder) Equivalent to a clear then add of all the objects contained in the given collection in iteration order.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Comparator

equals

Constructor Detail

ExternalOrderingComparator

public ExternalOrderingComparator(Collection<E> order)

Creates a new object initialized with the given collection, in order of iteration. The content of the collection is used to define the universe of objects this comparator accepts, and the order of iteration on the given collection is used to define the order on the universe of objects.

Parameters:

order - not null. May be empty (in which case this comparator will not be able to compare any objects until elements are added). One of the collection element may be null element (which counts as a normal element for this comparator). The collection may not contain duplicate elements. It is recommended to use a SortedSet when possible to ensure a correct iteration order and no duplicate.

ExternalOrderingComparator

public ExternalOrderingComparator()

Method Detail

add

public void add(E elem)

Adds the given element as the greatest of all elements already known to this object. The given element must not be already known to this object.

Parameters:

elem - may be null, if the null element is not already in the set of known objects. The null element counts as a normal element for this comparator.

remove

public boolean remove(Object o)

Removes an element from this ordering if it is present.

Parameters:

o - null is allowed.

Returns:

true iff the element was present.

replace

public void replace(E oldElement,
                    E newElement)

resetOrder

public void resetOrder(Collection<E> newOrder)

Equivalent to a clear then add of all the objects contained in the given collection in iteration order. When this method returns this object's content is equivalent to a new object created using ExternalOrderingComparator(Collection).

Parameters:

newOrder - not null, no duplicate allowed.

addInBetween

public void addInBetween(E previous,
                         E elem,
                         E next)

Adds an element in-between two other elements. The previous element must be right before the next one, i.e., there must not already be an element in between the given previous and next. This is required for the ordering to be totally defined over the elements known to this object.

Parameters:

previous - must be an element in this object.

elem - the element to add (null allowed as it counts as a normal element), must not already be in this object.

next - must be an element in this object.

addAsWorst

public void addAsWorst(E elem)

compare

public int compare(E o1,
                   E o2)

Compares its two arguments for order. Returns a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second, according to the order of the objects predefined at construction.

Comparing the null element is allowed, if it is one of the objects known to this comparator.

Specified by:

compare in interface Comparator<E>

Throws:

IllegalStateException - iff at least one of the given arguments is not in the universe of objects this comparator accepts.

contains

public boolean contains(Object o)

clear

public void clear()