public class

ComparatorChain

extends Object
implements Serializable Comparator<T>
java.lang.Object
   ↳ org.apache.commons.collections.comparators.ComparatorChain

Class Overview

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. However, take care to not alter the underlying List of Comparators or the BitSet that defines the sort order.

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.

Summary

Fields
protected List comparatorChain The list of comparators in the chain.
protected boolean isLocked Whether the chain has been "locked".
protected BitSet orderingBits Order - false (clear) = ascend; true (set) = descend.
Public Constructors
ComparatorChain()
Construct a ComparatorChain with no Comparators.
ComparatorChain(Comparator comparator)
Construct a ComparatorChain with a single Comparator, sorting in the forward order
ComparatorChain(Comparator comparator, boolean reverse)
Construct a Comparator chain with a single Comparator, sorting in the given order
ComparatorChain(List list)
Construct a ComparatorChain from the Comparators in the List.
ComparatorChain(List list, BitSet bits)
Construct a ComparatorChain from the Comparators in the given List.
Public Methods
void addComparator(Comparator comparator)
Add a Comparator to the end of the chain using the forward sort order
void addComparator(Comparator comparator, boolean reverse)
Add a Comparator to the end of the chain using the given sort order
int compare(Object o1, Object o2)
Perform comparisons on the Objects as per Comparator.compare(o1,o2).
boolean equals(Object object)
Returns true iff that Object is is a Comparator whose ordering is known to be equivalent to mine.
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, Comparator comparator, boolean reverse)
Replace the Comparator at the given index in the ComparatorChain, using the given sort order
void setComparator(int index, Comparator comparator)
Replace the Comparator at the given index, maintaining the existing sort order.
void setForwardSort(int index)
Change the sort order at the given index in the ComparatorChain to a forward sort.
void setReverseSort(int index)
Change the sort order at the given index in the ComparatorChain to a reverse sort.
int size()
Number of Comparators in the current ComparatorChain.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.util.Comparator

Fields

protected List comparatorChain

The list of comparators in the chain.

protected boolean isLocked

Whether the chain has been "locked".

protected BitSet orderingBits

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

Public Constructors

public ComparatorChain ()

Construct a ComparatorChain with no Comparators. You must add at least one Comparator before calling the compare(Object,Object) method, or an UnsupportedOperationException is thrown

public ComparatorChain (Comparator comparator)

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

Parameters
comparator First comparator in the Comparator chain

public ComparatorChain (Comparator comparator, boolean reverse)

Construct a Comparator chain with a single Comparator, sorting in the given order

Parameters
comparator First Comparator in the ComparatorChain
reverse false = forward sort; true = reverse sort

public ComparatorChain (List list)

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

Parameters
list List of Comparators
See Also

public ComparatorChain (List list, BitSet bits)

Construct a ComparatorChain from the Comparators in the given List. The sort order of each column will be drawn from the given BitSet. When determining the sort order for Comparator at index i in the List, the ComparatorChain will call BitSet.get(i). If that method returns false, the forward sort order is used; a return value of true indicates reverse sort order.

Parameters
list List of Comparators. NOTE: This constructor does not perform a defensive copy of the list
bits Sort order for each Comparator. Extra bits are ignored, unless extra Comparators are added by another method.

Public Methods

public void addComparator (Comparator comparator)

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

Parameters
comparator Comparator with the forward sort order

public void addComparator (Comparator comparator, boolean reverse)

Add a Comparator to the end of the chain using the given sort order

Parameters
comparator Comparator to add to the end of the chain
reverse false = forward sort order; true = reverse sort order

public int compare (Object o1, Object o2)

Perform comparisons on the Objects as per Comparator.compare(o1,o2).

Parameters
o1 the first object to compare
o2 the second object to compare
Returns
  • -1, 0, or 1
Throws
UnsupportedOperationException if the ComparatorChain does not contain at least one Comparator

public boolean equals (Object object)

Returns true iff that Object is is a Comparator whose ordering is known to be equivalent to mine.

This implementation returns true iff 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 equals(Object) contract.

Parameters
object the object to compare with
Returns
  • true if equal

public int hashCode ()

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

Returns
  • a suitable hash code

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 = ComparatorChain cannot be modified; false = ComparatorChain can still be modified.

public void setComparator (int index, Comparator comparator, boolean reverse)

Replace the Comparator at the given index in the ComparatorChain, using the given sort order

Parameters
index index of the Comparator to replace
comparator Comparator to set
reverse false = forward sort order; true = reverse sort order

public void setComparator (int index, Comparator comparator)

Replace the Comparator at the given index, maintaining the existing sort order.

Parameters
index index of the Comparator to replace
comparator Comparator to place at the given index
Throws
IndexOutOfBoundsException if index < 0 or index >= size()

public void setForwardSort (int index)

Change the sort order at the given index in the ComparatorChain to a forward sort.

Parameters
index Index of the ComparatorChain

public void setReverseSort (int index)

Change the sort order at the given index in the ComparatorChain to a reverse sort.

Parameters
index Index of the ComparatorChain

public int size ()

Number of Comparators in the current ComparatorChain.

Returns
  • Comparator count