ComparatorChain (Apache Commons Collections 4.4 API)

java.lang.Object
- org.apache.commons.collections4.comparators.ComparatorChain<E>

Type Parameters:

E - the type of objects compared by this comparator

All Implemented Interfaces:

Serializable, Comparator<E>
```
public class ComparatorChain<E>
extends Object
implements Comparator<E>, 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:

2.0

See Also:

Serialized Form

Constructor Summary

Constructors
Constructor and Description
`ComparatorChain()` Construct a ComparatorChain with no Comparators.
`ComparatorChain(Comparator<E> comparator)` Construct a ComparatorChain with a single Comparator, sorting in the forward order
`ComparatorChain(Comparator<E> comparator, boolean reverse)` Construct a Comparator chain with a single Comparator, sorting in the given order
`ComparatorChain(List<Comparator<E>> list)` Construct a ComparatorChain from the Comparators in the List.
`ComparatorChain(List<Comparator<E>> list, BitSet bits)` Construct a ComparatorChain from the Comparators in the given List.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addComparator(Comparator<E> comparator)` Add a Comparator to the end of the chain using the forward sort order
`void`	`addComparator(Comparator<E> comparator, boolean reverse)` Add a Comparator to the end of the chain using the given sort order
`int`	`compare(E o1, E 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<E> comparator)` Replace the Comparator at the given index, maintaining the existing sort order.
`void`	`setComparator(int index, Comparator<E> 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

Methods inherited from interface java.util.Comparator
comparing, comparing, comparingDouble, comparingInt, comparingLong, naturalOrder, nullsFirst, nullsLast, reversed, reverseOrder, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

- 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<E> 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<E> 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<Comparator<E>> 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<Comparator<E>> 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<E> 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<E> 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<E> 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<E> 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(E o1,
                   E o2)
            throws UnsupportedOperationException
```
    Perform comparisons on the Objects as per Comparator.compare(o1,o2).
    
    Specified by:
    
    compare in interface Comparator<E>
    
    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.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    a suitable hash code
    
    Since:
    
    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<E>
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    object - the object to compare with
    
    Returns:
    
    true if equal
    
    Since:
    
    3.0

Class ComparatorChain<E>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Comparator

Constructor Detail

ComparatorChain

ComparatorChain

ComparatorChain

ComparatorChain

ComparatorChain

Method Detail

addComparator

addComparator

setComparator

setComparator

setForwardSort

setReverseSort

size

isLocked

compare

hashCode

equals