org.apache.commons.collections.comparators

Class FixedOrderComparator

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

All Implemented Interfaces:
Comparator

public class FixedOrderComparator
extends java.lang.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

Authors:

David Leppik
Stephen Colebourne
Janek Bogucki

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

Field Details

UNKNOWN_AFTER

public static final int UNKNOWN_AFTER

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

UNKNOWN_BEFORE

public static final int UNKNOWN_BEFORE

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

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.

Constructor Details

FixedOrderComparator

public FixedOrderComparator()

Constructs an empty FixedOrderComparator.

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:

- if the list is null

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:
 - if the array is null
Method Detailsadd
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:
 - 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:
 - if existingObject is not in the 
Comparator's set of known objects.
 - if a comparison has already been made
checkLocked
protected void checkLocked()
 Checks to see whether the comparator is now locked against further changes.
Throws:
 - if the comparator is locked
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.
Parameters:
obj1 - the first object to compare
obj2 - the second object to compare
Throws:
 - if o1 or o2 are not known 
to this Comparator and an alternative behavior has not been set
via #setUnknownObjectBehavior(int).
getUnknownObjectBehavior
public int getUnknownObjectBehavior()
 Gets the behavior for comparing unknown objects.
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.
setUnknownObjectBehavior
public void setUnknownObjectBehavior(int unknownObjectBehavior)
 Sets the behavior for comparing unknown objects.
Parameters:
unknownObjectBehavior
Throws:
 - if a comparison has been performed
 - if the unknown flag is not valid
Generated on
  February 15, 2004
  by GNU Classpath Tools (Gjdoc XmlDoclet 0.6.1).