FixedOrderComparator (Apache Commons Collections 3.2.2 API)

java.lang.Object
- org.apache.commons.collections.comparators.FixedOrderComparator

All Implemented Interfaces:

Comparator
```
public class FixedOrderComparator
extends Object
implements Comparator
```
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.
Since:

Commons Collections 3.0

Version:

$Revision: 972404 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $

Author:

David Leppik, Stephen Colebourne, Janek Bogucki

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`UNKNOWN_AFTER` Behavior when comparing unknown Objects: unknown objects compare as after known Objects.
`static int`	`UNKNOWN_BEFORE` Behavior when comparing unknown Objects: unknown objects compare as before known Objects.
`static int`	`UNKNOWN_THROW_EXCEPTION` Behavior when comparing unknown Objects: unknown objects cause a IllegalArgumentException to be thrown.

Constructor Summary

Constructors
Constructor and Description
`FixedOrderComparator()` Constructs an empty FixedOrderComparator.
`FixedOrderComparator(List items)` Constructs a FixedOrderComparator which uses the order of the given list to compare the objects.
`FixedOrderComparator(Object[] 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(Object obj)` Adds an item, which compares as after all items known to the Comparator.
`boolean`	`addAsEqual(Object existingObj, Object 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(Object obj1, Object obj2)` Compares two objects according to the order of this Comparator.
`int`	`getUnknownObjectBehavior()` Gets the behavior for comparing unknown objects.
`boolean`	`isLocked()` Returns true if modifications cannot be made to the FixedOrderComparator.
`void`	`setUnknownObjectBehavior(int unknownObjectBehavior)` Sets the behavior for comparing unknown objects.

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

Methods inherited from interface java.util.Comparator
equals

- Field Detail
  - UNKNOWN_BEFORE
```
public static final int UNKNOWN_BEFORE
```
    Behavior when comparing unknown Objects: unknown objects compare as before known Objects.
    
    See Also:
    Constant Field Values
  - UNKNOWN_AFTER
```
public static final int UNKNOWN_AFTER
```
    Behavior when comparing unknown Objects: unknown objects compare as after known Objects.
    
    See Also:
    Constant Field Values
  - UNKNOWN_THROW_EXCEPTION
```
public static final int UNKNOWN_THROW_EXCEPTION
```
    Behavior when comparing unknown Objects: unknown objects cause a IllegalArgumentException to be thrown. This is the default behavior.
    
    See Also:
    Constant Field Values
- Constructor Detail
  - FixedOrderComparator
```
public FixedOrderComparator()
```
    Constructs an empty FixedOrderComparator.
  - FixedOrderComparator
```
public FixedOrderComparator(Object[] 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 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 int getUnknownObjectBehavior()
```
    Gets the behavior for comparing unknown objects.
    
    Returns:
    the flag for unknown behaviour - UNKNOWN_AFTER, UNKNOWN_BEFORE or UNKNOWN_THROW_EXCEPTION
  - setUnknownObjectBehavior
```
public void setUnknownObjectBehavior(int 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(Object 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(Object existingObj,
                 Object 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(Object obj1,
          Object 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
    
    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(int).

Class FixedOrderComparator

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Comparator

Field Detail

UNKNOWN_BEFORE

UNKNOWN_AFTER

UNKNOWN_THROW_EXCEPTION

Constructor Detail

FixedOrderComparator

FixedOrderComparator

FixedOrderComparator

Method Detail

isLocked

checkLocked

getUnknownObjectBehavior

setUnknownObjectBehavior

add

addAsEqual

compare