org.apache.commons.collections.comparators
public class FixedOrderComparator extends Object implements Comparator
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: 155406 $ $Date: 2005-02-26 12:55:26 +0000 (Sat, 26 Feb 2005) $
Field Summary | |
---|---|
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 | |
---|---|
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.
|
Method Summary | |
---|---|
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.
|
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
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
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
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
Throws: UnsupportedOperationException if the comparator is locked
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 FixedOrderComparator.
Returns: the flag for unknown behaviour - UNKNOWN_AFTER, UNKNOWN_BEFORE or UNKNOWN_THROW_EXCEPTION
Returns: true if attempts to change the FixedOrderComparator yield an UnsupportedOperationException, false if it can be changed.
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