| java.lang.Object
 org.apache.commons.collections.comparators.FixedOrderComparator
| FixedOrderComparator | | public class FixedOrderComparator implements Comparator(Code) | | 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
FixedOrderComparator.compare(Object,Object) 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) $
author:
David Leppik
author:
Stephen Colebourne
author:
Janek Bogucki |
| Field Summary | |
| final public static int | UNKNOWN_AFTER
Behavior when comparing unknown Objects:
unknown objects compare as after known Objects. | | final public static int | UNKNOWN_BEFORE
Behavior when comparing unknown Objects:
unknown objects compare as before known Objects. | | final public static int | UNKNOWN_THROW_EXCEPTION
Behavior when comparing unknown Objects:
unknown objects cause a IllegalArgumentException to be thrown. |
| Constructor Summary | |
| 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. | | public | FixedOrderComparator(List items)
Constructs a FixedOrderComparator which uses the order of the given list
to compare the objects. |
| Method Summary | |
| 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. | | public 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. | | 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. | | public int | getUnknownObjectBehavior()
Gets the behavior for comparing unknown objects. | | public boolean | isLocked()
Returns true if modifications cannot be made to the FixedOrderComparator. | | public void | setUnknownObjectBehavior(int unknownObjectBehavior)
Sets the behavior for comparing unknown objects. |
| UNKNOWN_AFTER | | final public static int UNKNOWN_AFTER(Code) | | Behavior when comparing unknown Objects:
unknown objects compare as after known Objects.
|
| UNKNOWN_BEFORE | | final public static int UNKNOWN_BEFORE(Code) | | Behavior when comparing unknown Objects:
unknown objects compare as before known Objects.
|
| UNKNOWN_THROW_EXCEPTION | | final public static int UNKNOWN_THROW_EXCEPTION(Code) | | Behavior when comparing unknown Objects:
unknown objects cause a IllegalArgumentException to be thrown.
This is the default behavior.
|
| FixedOrderComparator | | public FixedOrderComparator()(Code) | | Constructs an empty FixedOrderComparator.
|
| FixedOrderComparator | | public FixedOrderComparator(Object[] items)(Code) | | 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)(Code) | | 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 |
| add | | public boolean add(Object obj)(Code) | | 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. true if obj has been added for the first time, false ifit was already known to the Comparator.
throws:
UnsupportedOperationException - if a comparison has already been made |
| addAsEqual | | public boolean addAsEqual(Object existingObj, Object newObj)(Code) | | 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
Parameters:
newObj - an item to be added to the Comparator's set ofknown objects true if newObj has been added for the first time, false ifit was already known to the Comparator.
throws:
IllegalArgumentException - if existingObject is not in the Comparator's set of known objects.
throws:
UnsupportedOperationException - if a comparison has already been made |
| checkLocked | | protected void checkLocked()(Code) | | Checks to see whether the comparator is now locked against further changes.
throws:
UnsupportedOperationException - if the comparator is locked |
| compare | | public int compare(Object obj1, Object obj2)(Code) | | 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
Parameters:
obj2 - the second object to compare 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 setvia FixedOrderComparator.setUnknownObjectBehavior(int). |
| getUnknownObjectBehavior | | public int getUnknownObjectBehavior()(Code) | | Gets the behavior for comparing unknown objects.
the flag for unknown behaviour - UNKNOWN_AFTER,UNKNOWN_BEFORE or UNKNOWN_THROW_EXCEPTION |
| isLocked | | public boolean isLocked()(Code) | | Returns true if modifications cannot be made to the FixedOrderComparator.
FixedOrderComparators cannot be modified once they have performed a comparison.
true if attempts to change the FixedOrderComparator yield anUnsupportedOperationException, false if it can be changed. |
| setUnknownObjectBehavior | | public void setUnknownObjectBehavior(int unknownObjectBehavior)(Code) | | 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
throws:
IllegalArgumentException - if the unknown flag is not valid |
|
|