org.apache.commons.collections4.comparators

## Class FixedOrderComparator<T>

- java.lang.Object
- - org.apache.commons.collections4.comparators.FixedOrderComparator<T>

- All Implemented Interfaces:
    Serializable, Comparator<T>

      public class FixedOrderComparator<T>
      extends Object
      implements Comparator<T>, Serializable

  A Comparator which imposes a specific order on a specific set of Objects. Objects are presented to the FixedOrderComparator in a specified order and subsequent calls to `compare` yield that order. For example:

       String[] planets = {"Mercury", "Venus", "Earth", "Mars"};
       FixedOrderComparator distanceFromSun = new FixedOrderComparator(planets);
       Arrays.sort(planets);                     // Sort to alphabetical order
       Arrays.sort(planets, distanceFromSun);    // Back to original order

  Once `compare` has been called, the FixedOrderComparator is locked and attempts to modify it yield an UnsupportedOperationException.

  Instances of FixedOrderComparator 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.

  This class is Serializable from Commons Collections 4.0.

  Since:
    3.0
  Version:
    $Id: FixedOrderComparator.java 1479344 2013-05-05 15:48:01Z tn $
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `FixedOrderComparator.UnknownObjectBehavior` Unknown object behavior enum.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FixedOrderComparator()` Constructs an empty FixedOrderComparator.
    `FixedOrderComparator(List<T> items)` Constructs a FixedOrderComparator which uses the order of the given list to compare the objects.
    `FixedOrderComparator(T... items)` Constructs a FixedOrderComparator which uses the order of the given array to compare the objects.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `add(T obj)` Adds an item, which compares as after all items known to the Comparator.
    `boolean` | `addAsEqual(T existingObj, T newObj)` Adds a new item, which compares as equal to the given existing item.
    `protected void` | `checkLocked()` Checks to see whether the comparator is now locked against further changes.
    `int` | `compare(T obj1, T obj2)` Compares two objects according to the order of this Comparator.
    `boolean` | `equals(Object object)` Returns `true` iff that Object is is a `Comparator` whose ordering is known to be equivalent to mine.
    `FixedOrderComparator.UnknownObjectBehavior` | `getUnknownObjectBehavior()` Gets the behavior for comparing unknown objects.
    `int` | `hashCode()` Implement a hash code for this comparator that is consistent with `equals`.
    `boolean` | `isLocked()` Returns true if modifications cannot be made to the FixedOrderComparator.
    `void` | `setUnknownObjectBehavior(FixedOrderComparator.UnknownObjectBehavior unknownObjectBehavior)` Sets the behavior for comparing unknown objects.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### FixedOrderComparator

          public FixedOrderComparator()

      Constructs an empty FixedOrderComparator.

    - #### FixedOrderComparator

          public FixedOrderComparator(T... items)

      Constructs a FixedOrderComparator which uses the order of the given array to compare the objects.

      The array is copied, so later changes will not affect the comparator.

      Parameters:
        `items` - the items that the comparator can compare in order
      Throws:
        `IllegalArgumentException` - if the array is null

    - #### FixedOrderComparator

          public FixedOrderComparator(List<T> items)

      Constructs a FixedOrderComparator which uses the order of the given list to compare the objects.

      The list is copied, so later changes will not affect the comparator.

      Parameters:
        `items` - the items that the comparator can compare in order
      Throws:
        `IllegalArgumentException` - if the list is null

  - ### Method Detail

    - #### isLocked

          public boolean isLocked()

      Returns true if modifications cannot be made to the FixedOrderComparator. FixedOrderComparators cannot be modified once they have performed a comparison.
      Returns:
        true if attempts to change the FixedOrderComparator yield an UnsupportedOperationException, false if it can be changed.

    - #### checkLocked

          protected void checkLocked()

      Checks to see whether the comparator is now locked against further changes.
      Throws:
        `UnsupportedOperationException` - if the comparator is locked

    - #### getUnknownObjectBehavior

          public FixedOrderComparator.UnknownObjectBehavior getUnknownObjectBehavior()

      Gets the behavior for comparing unknown objects.
      Returns:
        `FixedOrderComparator.UnknownObjectBehavior`

    - #### setUnknownObjectBehavior

          public void setUnknownObjectBehavior(FixedOrderComparator.UnknownObjectBehavior unknownObjectBehavior)

      Sets the behavior for comparing unknown objects.
      Parameters:
        `unknownObjectBehavior` - the flag for unknown behaviour - UNKNOWN_AFTER, UNKNOWN_BEFORE or UNKNOWN_THROW_EXCEPTION
      Throws:
        `UnsupportedOperationException` - if a comparison has been performed
        `IllegalArgumentException` - if the unknown flag is not valid

    - #### add

          public boolean add(T obj)

      Adds an item, which compares as after all items known to the Comparator. If the item is already known to the Comparator, its old position is replaced with the new position.
      Parameters:
        `obj` - the item to be added to the Comparator.
      Returns:
        true if obj has been added for the first time, false if it was already known to the Comparator.
      Throws:
        `UnsupportedOperationException` - if a comparison has already been made

    - #### addAsEqual

          public boolean addAsEqual(T existingObj,
                           T newObj)

      Adds a new item, which compares as equal to the given existing item.
      Parameters:
        `existingObj` - an item already in the Comparator's set of known objects
        `newObj` - an item to be added to the Comparator's set of known objects
      Returns:
        true if newObj has been added for the first time, false if it was already known to the Comparator.
      Throws:
        `IllegalArgumentException` - if existingObject is not in the Comparator's set of known objects.
        `UnsupportedOperationException` - if a comparison has already been made

    - #### compare

          public int compare(T obj1,
                    T obj2)

      Compares two objects according to the order of this Comparator.

      It is important to note that this class will throw an IllegalArgumentException in the case of an unrecognised object. This is not specified in the Comparator interface, but is the most appropriate exception.

      Specified by:
        `compare` in interface `Comparator<T>`
      Parameters:
        `obj1` - the first object to compare
        `obj2` - the second object to compare
      Returns:
        negative if obj1 is less, positive if greater, zero if equal
      Throws:
        `IllegalArgumentException` - if obj1 or obj2 are not known to this Comparator and an alternative behavior has not been set via `setUnknownObjectBehavior(UnknownObjectBehavior)`.

    - #### hashCode

          public int hashCode()

      Implement a hash code for this comparator that is consistent with `equals`.
      Overrides:
        `hashCode` in class `Object`
      Returns:
        a hash code for this comparator.

    - #### 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 `that` is a `FixedOrderComparator` whose attributes are equal to mine.

      Specified by:
        `equals` in interface `Comparator<T>`
      Overrides:
        `equals` in class `Object`
      Parameters:
        `object` - the object to compare to
      Returns:
        true if equal

Copyright © 2001–2013 The Apache Software Foundation. All rights reserved.