- /*
- * Copyright 1999-2004 The Apache Software Foundation
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
- package org.apache.commons.collections.comparators;
-
- import java.io.Serializable;
- import java.util.ArrayList;
- import java.util.BitSet;
- import java.util.Comparator;
- import java.util.Iterator;
- import java.util.List;
-
- /**
- * <p>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.</p>
- *
- * <p>To further facilitate SQL-like sorting, the order of
- * any single Comparator in the list can be reversed.</p>
- *
- * <p>Calling a method that adds new Comparators or
- * changes the ascend/descend sort <i>after compare(Object,
- * Object) has been called</i> will result in an
- * UnsupportedOperationException. However, <i>take care</i>
- * to not alter the underlying List of Comparators
- * or the BitSet that defines the sort order.</p>
- *
- * <p>Instances of ComparatorChain are not synchronized.
- * The class is not thread-safe at construction time, but
- * it <i>is</i> thread-safe to perform multiple comparisons
- * after all the setup operations are complete.</p>
- *
- * @since Commons Collections 2.0
- * @author Morgan Delagrange
- * @version $Revision: 1.18 $ $Date: 2004/05/16 11:48:49 $
- */
- public class ComparatorChain implements Comparator, Serializable {
-
- /** Serialization version from Collections 2.0. */
- private static final long serialVersionUID = -721644942746081630L;
-
- /** The list of comparators in the chain. */
- protected List comparatorChain = null;
- /** Order - false (clear) = ascend; true (set) = descend. */
- protected BitSet orderingBits = null;
- /** Whether the chain has been "locked". */
- protected boolean isLocked = false;
-
- //-----------------------------------------------------------------------
- /**
- * 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() {
- this(new ArrayList(),new BitSet());
- }
-
- /**
- * Construct a ComparatorChain with a single Comparator,
- * sorting in the forward order
- *
- * @param comparator First comparator in the Comparator chain
- */
- public ComparatorChain(Comparator comparator) {
- this(comparator,false);
- }
-
- /**
- * Construct a Comparator chain with a single Comparator,
- * sorting in the given order
- *
- * @param comparator First Comparator in the ComparatorChain
- * @param reverse false = forward sort; true = reverse sort
- */
- public ComparatorChain(Comparator comparator, boolean reverse) {
- comparatorChain = new ArrayList();
- comparatorChain.add(comparator);
- orderingBits = new BitSet(1);
- if (reverse == true) {
- orderingBits.set(0);
- }
- }
-
- /**
- * Construct a ComparatorChain from the Comparators in the
- * List. All Comparators will default to the forward
- * sort order.
- *
- * @param list List of Comparators
- * @see #ComparatorChain(List,BitSet)
- */
- public ComparatorChain(List list) {
- this(list,new BitSet(list.size()));
- }
-
- /**
- * 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>i</i> in the List,
- * the ComparatorChain will call BitSet.get(<i>i</i>).
- * If that method returns <i>false</i>, the forward
- * sort order is used; a return value of <i>true</i>
- * indicates reverse sort order.
- *
- * @param list List of Comparators. NOTE: This constructor does not perform a
- * defensive copy of the list
- * @param bits Sort order for each Comparator. Extra bits are ignored,
- * unless extra Comparators are added by another method.
- */
- public ComparatorChain(List list, BitSet bits) {
- comparatorChain = list;
- orderingBits = bits;
- }
-
- //-----------------------------------------------------------------------
- /**
- * Add a Comparator to the end of the chain using the
- * forward sort order
- *
- * @param comparator Comparator with the forward sort order
- */
- public void addComparator(Comparator comparator) {
- addComparator(comparator,false);
- }
-
- /**
- * Add a Comparator to the end of the chain using the
- * given sort order
- *
- * @param comparator Comparator to add to the end of the chain
- * @param reverse false = forward sort order; true = reverse sort order
- */
- public void addComparator(Comparator comparator, boolean reverse) {
- checkLocked();
-
- comparatorChain.add(comparator);
- if (reverse == true) {
- orderingBits.set(comparatorChain.size() - 1);
- }
- }
-
- /**
- * Replace the Comparator at the given index, maintaining
- * the existing sort order.
- *
- * @param index index of the Comparator to replace
- * @param comparator Comparator to place at the given index
- * @exception IndexOutOfBoundsException
- * if index < 0 or index >= size()
- */
- public void setComparator(int index, Comparator comparator)
- throws IndexOutOfBoundsException {
- setComparator(index,comparator,false);
- }
-
- /**
- * Replace the Comparator at the given index in the
- * ComparatorChain, using the given sort order
- *
- * @param index index of the Comparator to replace
- * @param comparator Comparator to set
- * @param reverse false = forward sort order; true = reverse sort order
- */
- public void setComparator(int index, Comparator comparator, boolean reverse) {
- checkLocked();
-
- comparatorChain.set(index,comparator);
- if (reverse == true) {
- orderingBits.set(index);
- } else {
- orderingBits.clear(index);
- }
- }
-
-
- /**
- * Change the sort order at the given index in the
- * ComparatorChain to a forward sort.
- *
- * @param index Index of the ComparatorChain
- */
- public void setForwardSort(int index) {
- checkLocked();
- orderingBits.clear(index);
- }
-
- /**
- * Change the sort order at the given index in the
- * ComparatorChain to a reverse sort.
- *
- * @param index Index of the ComparatorChain
- */
- public void setReverseSort(int index) {
- checkLocked();
- orderingBits.set(index);
- }
-
- /**
- * Number of Comparators in the current ComparatorChain.
- *
- * @return Comparator count
- */
- public int size() {
- return comparatorChain.size();
- }
-
- /**
- * Determine if modifications can still be made to the
- * ComparatorChain. ComparatorChains cannot be modified
- * once they have performed a comparison.
- *
- * @return true = ComparatorChain cannot be modified; false =
- * ComparatorChain can still be modified.
- */
- public boolean isLocked() {
- return isLocked;
- }
-
- // throw an exception if the ComparatorChain is locked
- private void checkLocked() {
- if (isLocked == true) {
- throw new UnsupportedOperationException("Comparator ordering cannot be changed after the first comparison is performed");
- }
- }
-
- private void checkChainIntegrity() {
- if (comparatorChain.size() == 0) {
- throw new UnsupportedOperationException("ComparatorChains must contain at least one Comparator");
- }
- }
-
- //-----------------------------------------------------------------------
- /**
- * Perform comparisons on the Objects as per
- * Comparator.compare(o1,o2).
- *
- * @param o1 the first object to compare
- * @param o2 the second object to compare
- * @return -1, 0, or 1
- * @exception UnsupportedOperationException
- * if the ComparatorChain does not contain at least one
- * Comparator
- */
- public int compare(Object o1, Object o2) throws UnsupportedOperationException {
- if (isLocked == false) {
- checkChainIntegrity();
- isLocked = true;
- }
-
- // iterate over all comparators in the chain
- Iterator comparators = comparatorChain.iterator();
- for (int comparatorIndex = 0; comparators.hasNext(); ++comparatorIndex) {
-
- Comparator comparator = (Comparator) comparators.next();
- int retval = comparator.compare(o1,o2);
- if (retval != 0) {
- // invert the order if it is a reverse sort
- if (orderingBits.get(comparatorIndex) == true) {
- if(Integer.MIN_VALUE == retval) {
- retval = Integer.MAX_VALUE;
- } else {
- retval *= -1;
- }
- }
-
- return retval;
- }
-
- }
-
- // if comparators are exhausted, return 0
- return 0;
- }
-
- //-----------------------------------------------------------------------
- /**
- * Implement a hash code for this comparator that is consistent with
- * {@link #equals(Object) equals}.
- *
- * @return a suitable hash code
- * @since Commons Collections 3.0
- */
- public int hashCode() {
- int hash = 0;
- if(null != comparatorChain) {
- hash ^= comparatorChain.hashCode();
- }
- if(null != orderingBits) {
- hash ^= orderingBits.hashCode();
- }
- return hash;
- }
-
- /**
- * Returns <code>true</code> iff <i>that</i> Object is
- * is a {@link Comparator} whose ordering is known to be
- * equivalent to mine.
- * <p>
- * This implementation returns <code>true</code>
- * iff <code><i>object</i>.{@link Object#getClass() getClass()}</code>
- * equals <code>this.getClass()</code>, and the underlying
- * comparators and order bits are equal.
- * Subclasses may want to override this behavior to remain consistent
- * with the {@link Comparator#equals(Object)} contract.
- *
- * @param object the object to compare with
- * @return true if equal
- * @since Commons Collections 3.0
- */
- public boolean equals(Object object) {
- if(this == object) {
- return true;
- } else if(null == object) {
- return false;
- } else if(object.getClass().equals(this.getClass())) {
- ComparatorChain chain = (ComparatorChain)object;
- return ( (null == orderingBits ? null == chain.orderingBits : orderingBits.equals(chain.orderingBits))
- && (null == comparatorChain ? null == chain.comparatorChain : comparatorChain.equals(chain.comparatorChain)) );
- } else {
- return false;
- }
- }
-
- }