## org.apache.commons.collections.comparators
Class ComparatorChain

    java.lang.Object
      org.apache.commons.collections.comparators.ComparatorChain

All Implemented Interfaces:
  Comparator, Serializable

public class ComparatorChain
extends Object
implements Comparator, 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. 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.

Since:
  Commons Collections 2.0
Version:
  $Revision: 1.18 $ $Date: 2004/05/16 11:48:49 $
Author:
  Morgan Delagrange
See Also:
  Serialized Form

Field Summary
`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.

Constructor Summary
`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.

Method Summary
`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)` Replace the Comparator at the given index, maintaining the existing sort order.
`void` `setComparator(int index, Comparator comparator, boolean reverse)` Replace the Comparator at the given index in the ComparatorChain, using the given 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.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### comparatorChain

    protected List comparatorChain

  The list of comparators in the chain.

### orderingBits

    protected BitSet orderingBits

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

### isLocked

    protected boolean isLocked

  Whether the chain has been "locked".

Constructor Detail

### ComparatorChain

    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

### ComparatorChain

    public ComparatorChain(Comparator comparator)

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

Parameters:
  `comparator` - First comparator in the Comparator chain

### ComparatorChain

    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

### ComparatorChain

    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:
  `ComparatorChain(List,BitSet)`

### ComparatorChain

    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.

Method Detail

### addComparator

    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

### addComparator

    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

### setComparator

    public void setComparator(int index,
                              Comparator comparator)
                       throws IndexOutOfBoundsException

  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()

### setComparator

    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

### setForwardSort

    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

### setReverseSort

    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

### size

    public int size()

  Number of Comparators in the current ComparatorChain.

  Returns:
    Comparator count

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

### compare

    public int compare(Object o1,
                       Object o2)
                throws UnsupportedOperationException

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

  Specified by:
    `compare` in interface `Comparator`
  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

### hashCode

    public int hashCode()

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

  Returns:
    a suitable hash code
  Since:
    Commons Collections 3.0

### equals

    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 `Comparator.equals(Object)` contract.

  Specified by:
    `equals` in interface `Comparator`
  Parameters:
    `object` - the object to compare with
  Returns:
    true if equal
  Since:
    Commons Collections 3.0

Copyright © 2001-2005 Apache Software Foundation. All Rights Reserved.