net.sf.collections15.comparators
Class ComparatorChain<E>

java.lang.Object
  net.sf.collections15.comparators.ComparatorChain<E>

All Implemented Interfaces:

java.io.Serializable, java.util.Comparator<E>

public class ComparatorChain<E>
extends java.lang.Object
implements java.util.Comparator<E>, java.io.Serializable

A ComparatorChain is a Comparator that wraps one or more Comparators in sequence. The ComparatorChain calls each Comparator in sequence until either

1. any single Comparator returns a non-zero result (and that result is then returned), or
2. the ComparatorChain is exhausted (and zero is returned).

This type of sorting is very similar to multi-column sorting in SQL, and this class allows Java classes to emulate that kind of behaviour when sorting a List.

To further facilitate SQL-like sorting, the order of any single Comparator in the list can be reversed.

Calling a method that adds new Comparators or changes the ascend/descend sort after compare(Object, Object) has been called will result in an UnsupportedOperationException.

Instances of ComparatorChain are not synchronized. The class is not thread-safe at construction time, but it is thread-safe to perform multiple comparisons after all the setup operations are complete.

Since:

Collections15 1.0

Author:

Morgan Delagrange, Chris Lambrou (port to Java 5.0)

See Also:

Serialized Form

Field Summary

protected java.util.List<java.util.Comparator<E>>	comparatorChain The list of comparators in the chain.
protected boolean	isLocked Whether the chain has been "locked".
protected java.util.BitSet	orderingBits Order - false (clear) = ascend; true (set) = descend.

Constructor Summary

protected

ComparatorChain(int initialCapacity) Construct a ComparatorChain with no Comparators and the specified initial capacity.

Method Summary

void	addComparator(java.util.Comparator<E> comparator) Add a Comparator to the end of the chain using the forward sort order.
void	addComparator(java.util.Comparator<E> comparator, boolean reverse) Add a Comparator to the end of the chain using the specified sort order.
int	compare(E o1, E o2) Compares its two arguments for order.
boolean	equals(java.lang.Object object) Indicates whether or not the specified object is equal to this ComparatorChain instance.
static <T> ComparatorChain<T>	getInstance() Construct an empty ComparatorChain with the default initial capacity.
static <T> ComparatorChain<T>	getInstance(java.util.Collection<java.util.Comparator<T>> comparators) Returns a ComparatorChain from the Comparators in the List.
static <T> ComparatorChain<T>	getInstance(java.util.Comparator<T> comparator) Construct a ComparatorChain with a single Comparator, sorting in the forward order.
static <T> ComparatorChain<T>	getInstance(java.util.Comparator<T> comparator, boolean reverse) Construct a ComparatorChain with a single Comparator, sorting in the specified order.
static <T> ComparatorChain<T>	getInstance(java.util.List<java.util.Comparator<T>> comparators, java.util.BitSet orderingBits) Returns a ComparatorChain from the Comparators in the List.
int	hashCode() Implement a hash code for this comparator that is consistent with equals.
boolean	isLocked() Determine if modifications can still be made to the ComparatorChain.
void	setComparator(int index, java.util.Comparator<E> comparator) Replace the Comparator at the given index, using the forward sort order for the new Comparator.
void	setComparator(int index, java.util.Comparator<E> comparator, boolean reverse) Replace the Comparator at the given index, using the specified sort order for the new Comparator.
void	setForwardSort(int index) Set the sort order at the given index in the ComparatorChain to the forward sort order of the Comparator at that position.
void	setReverseSort(int index) Set the sort order at the given index in the ComparatorChain to the reverse sort order of the Comparator at that position.
int	size() Returns the number of Comparators in the ComparatorChain.

Methods inherited from class java.lang.Object

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

Field Detail

comparatorChain

protected java.util.List<java.util.Comparator<E>> comparatorChain

The list of comparators in the chain.

orderingBits

protected java.util.BitSet orderingBits

Order - false (clear) = ascend; true (set) = descend.

isLocked

protected boolean isLocked

Whether the chain has been "locked".

Constructor Detail

ComparatorChain

protected ComparatorChain(int initialCapacity)

Construct a ComparatorChain with no Comparators and the specified initial capacity.

Parameters:

initialCapacity - The initial capacity of the internal list of Comparators and ordering bits BitSet. A negative value indicates that the default initial capacity of the underlying storage elements should be used.

Method Detail

getInstance

public static <T> ComparatorChain<T> getInstance()

Construct an empty ComparatorChain with the default initial capacity.

getInstance

public static <T> ComparatorChain<T> getInstance(java.util.Comparator<T> comparator)

Construct a ComparatorChain with a single Comparator, sorting in the forward order.

Parameters:

comparator - The first comparator in the ComparatorChain.

Throws:

java.lang.IllegalArgumentException - Thrown if comparator is null.

getInstance

public static <T> ComparatorChain<T> getInstance(java.util.Comparator<T> comparator,
                                                 boolean reverse)

Construct a ComparatorChain with a single Comparator, sorting in the specified order.

Parameters:

comparator - The first comparator in the ComparatorChain.

reverse - If false, the natural order of comparator is used. If true, the reverse order of comparator is used.

Throws:

java.lang.IllegalArgumentException - Thrown if comparator is null.

getInstance

public static <T> ComparatorChain<T> getInstance(java.util.Collection<java.util.Comparator<T>> comparators)

Returns a ComparatorChain from the Comparators in the List. All Comparators will default to the forward sort order.

Parameters:

comparators - The Collection of Comparators to chain. The Comparator are added to the chain in the order that they are returned by the iterator method of the Collection.

Throws:

java.lang.IllegalArgumentException - Thrown if comparators is null, or contains any null elements. It may be empty, however.

getInstance

public static <T> ComparatorChain<T> getInstance(java.util.List<java.util.Comparator<T>> comparators,
                                                 java.util.BitSet orderingBits)

Returns a ComparatorChain from the Comparators in the List. All Comparators will default to the forward sort order.

Parameters:

comparators - The List of Comparators to chain.

orderingBits - Indicates the sort order for each of the Comparators in comparators.

Throws:

java.lang.IllegalArgumentException - Thrown if comparators is null, or contains any null elements. It may be empty, however.

java.lang.IllegalArgumentException - Thrown if orderingBits is null, or if comparators and orderingBits are of unequal lengths.

addComparator

public void addComparator(java.util.Comparator<E> comparator)

Add a Comparator to the end of the chain using the forward sort order.

Parameters:

comparator - The Comparator to add to the end of the chain, with the forward sort order.

Throws:

java.lang.IllegalArgumentException - Thrown if comparator is null.

addComparator

public void addComparator(java.util.Comparator<E> comparator,
                          boolean reverse)

Add a Comparator to the end of the chain using the specified sort order.

Parameters:

comparator - The Comparator to add to the end of the chain, with the forward sort order.

reverse - If false, the natural order of comparator is used. If true, the reverse order of comparator is used.

Throws:

java.lang.IllegalArgumentException - Thrown if comparator is null.

setComparator

public void setComparator(int index,
                          java.util.Comparator<E> comparator)
                   throws java.lang.IndexOutOfBoundsException

Replace the Comparator at the given index, using the forward sort order for the new Comparator.

Parameters:

index - The index of the Comparator to replace.

comparator - The Comparator to place at the given index.

Throws:

java.lang.IndexOutOfBoundsException - Thrown if index < 0 or index >= size().

java.lang.IllegalArgumentException - Thrown if comparator is null.

setComparator

public void setComparator(int index,
                          java.util.Comparator<E> comparator,
                          boolean reverse)

Replace the Comparator at the given index, using the specified sort order for the new Comparator.

Parameters:

index - The index of the Comparator to replace.

comparator - The Comparator to place at the given index.

reverse - If false, the natural order of comparator is used. If true, the reverse order of comparator is used.

Throws:

java.lang.IndexOutOfBoundsException - Thrown if index < 0 or index >= size().

java.lang.IllegalArgumentException - Thrown if comparator is null.

setForwardSort

public void setForwardSort(int index)

Set the sort order at the given index in the ComparatorChain to the forward sort order of the Comparator at that position.

Parameters:

index - Index of the Comparator in the ComparatorChain.

Throws:

java.lang.IndexOutOfBoundsException - Thrown if index < 0 or index >= size().

setReverseSort

public void setReverseSort(int index)

Set the sort order at the given index in the ComparatorChain to the reverse sort order of the Comparator at that position.

Parameters:

index - Index of the Comparator in the ComparatorChain.

Throws:

java.lang.IndexOutOfBoundsException - Thrown if index < 0 or index >= size().

size

public int size()

Returns the number of Comparators in the ComparatorChain.

Returns:

The length of the chain.

isLocked

public boolean isLocked()

Determine if modifications can still be made to the ComparatorChain. ComparatorChains cannot be modified once they have performed a comparison.

Returns:

true if the ComparatorChain cannot be modified; false if the ComparatorChain can still be modified.

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.

Specified by:

compare in interface java.util.Comparator<E>

Parameters:

o1 - The first object to compare.

o2 - The second object to compare.

Returns:

-1, 0, or 1

hashCode

public int hashCode()

Implement a hash code for this comparator that is consistent with equals.

Overrides:

hashCode in class java.lang.Object

Returns:

A suitable hash code

Since:

Collections15 1.0

equals

public boolean equals(java.lang.Object object)

Indicates whether or not the specified object is equal to this ComparatorChain instance.

This implementation returns true only if object.getClass() equals this.getClass(), and the underlying comparators and order bits are equal. Subclasses may want to override this behavior to remain consistent with the Comparator.equals(Object) contract.

Specified by:

equals in interface java.util.Comparator<E>

Overrides:

equals in class java.lang.Object

Parameters:

object - The object to compare to.

Returns:

true if object is equal to this instance.

Since:

Collections15 1.0