public class

FixedOrderComparator

extends Object
implements Comparator<T>
java.lang.Object
   ↳ org.apache.commons.collections.comparators.FixedOrderComparator

Class Overview

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.

Summary

Constants
int UNKNOWN_AFTER Behavior when comparing unknown Objects: unknown objects compare as after known Objects.
int UNKNOWN_BEFORE Behavior when comparing unknown Objects: unknown objects compare as before known Objects.
int UNKNOWN_THROW_EXCEPTION Behavior when comparing unknown Objects: unknown objects cause a IllegalArgumentException to be thrown.
Public Constructors
FixedOrderComparator()
Constructs an empty FixedOrderComparator.
FixedOrderComparator(Object[] items)
Constructs a FixedOrderComparator which uses the order of the given array to compare the objects.
FixedOrderComparator(List items)
Constructs a FixedOrderComparator which uses the order of the given list to compare the objects.
Public Methods
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.
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.
Protected Methods
void checkLocked()
Checks to see whether the comparator is now locked against further changes.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.util.Comparator

Constants

public static final int UNKNOWN_AFTER

Behavior when comparing unknown Objects: unknown objects compare as after known Objects.

Constant Value: 1 (0x00000001)

public static final int UNKNOWN_BEFORE

Behavior when comparing unknown Objects: unknown objects compare as before known Objects.

Constant Value: 0 (0x00000000)

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.

Constant Value: 2 (0x00000002)

Public Constructors

public FixedOrderComparator ()

Constructs an empty 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

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

Public Methods

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

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

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.

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

public int getUnknownObjectBehavior ()

Gets the behavior for comparing unknown objects.

Returns
  • the flag for unknown behaviour - UNKNOWN_AFTER, UNKNOWN_BEFORE or UNKNOWN_THROW_EXCEPTION

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.

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

Protected Methods

protected void checkLocked ()

Checks to see whether the comparator is now locked against further changes.

Throws
UnsupportedOperationException if the comparator is locked