org.apache.commons.collections4.comparators

Class FixedOrderComparator<T>

java.lang.Object

org.apache.commons.collections4.comparators.FixedOrderComparator<T>

All Implemented Interfaces:

java.io.Serializable, java.util.Comparator<T>

public class FixedOrderComparator<T>
extends java.lang.Object
implements java.util.Comparator<T>, java.io.Serializable

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.

This class is Serializable from Commons Collections 4.0.

Since:

3.0

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FixedOrderComparator.UnknownObjectBehavior Unknown object behavior enum.

Constructor Summary

Constructors

Constructor and Description
FixedOrderComparator() Constructs an empty FixedOrderComparator.
FixedOrderComparator(java.util.List<T> items) Constructs a FixedOrderComparator which uses the order of the given list to compare the objects.
FixedOrderComparator(T... items) Constructs a FixedOrderComparator which uses the order of the given array to compare the objects.

Method Summary

Modifier and Type	Method and Description
boolean	add(T obj) Adds an item, which compares as after all items known to the Comparator.
boolean	addAsEqual(T existingObj, T newObj) Adds a new item, which compares as equal to the given existing item.
int	compare(T obj1, T obj2) Compares two objects according to the order of this Comparator.
boolean	equals(java.lang.Object object) Returns true iff that Object is is a Comparator whose ordering is known to be equivalent to mine.
FixedOrderComparator.UnknownObjectBehavior	getUnknownObjectBehavior() Gets the behavior for comparing unknown objects.
int	hashCode() Implement a hash code for this comparator that is consistent with equals.
boolean	isLocked() Returns true if modifications cannot be made to the FixedOrderComparator.
void	setUnknownObjectBehavior(FixedOrderComparator.UnknownObjectBehavior unknownObjectBehavior) Sets the behavior for comparing unknown objects.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Comparator

comparing, comparing, comparingDouble, comparingInt, comparingLong, naturalOrder, nullsFirst, nullsLast, reversed, reverseOrder, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

Constructor Detail

FixedOrderComparator

public FixedOrderComparator()

Constructs an empty FixedOrderComparator.

FixedOrderComparator

public FixedOrderComparator(T... 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:

java.lang.NullPointerException - if the array is null

FixedOrderComparator

public FixedOrderComparator(java.util.List<T> 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:

java.lang.NullPointerException - 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.

getUnknownObjectBehavior

public FixedOrderComparator.UnknownObjectBehavior getUnknownObjectBehavior()

Gets the behavior for comparing unknown objects.

Returns:

FixedOrderComparator.UnknownObjectBehavior

setUnknownObjectBehavior

public void setUnknownObjectBehavior(FixedOrderComparator.UnknownObjectBehavior unknownObjectBehavior)

Sets the behavior for comparing unknown objects.

Parameters:

unknownObjectBehavior - the flag for unknown behaviour - UNKNOWN_AFTER, UNKNOWN_BEFORE or UNKNOWN_THROW_EXCEPTION

Throws:

java.lang.UnsupportedOperationException - if a comparison has been performed

java.lang.NullPointerException - if unknownObjectBehavior is null

add

public boolean add(T 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:

java.lang.UnsupportedOperationException - if a comparison has already been made

addAsEqual

public boolean addAsEqual(T existingObj,
                          T 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:

java.lang.IllegalArgumentException - if existingObject is not in the Comparator's set of known objects.

java.lang.UnsupportedOperationException - if a comparison has already been made

compare

public int compare(T obj1,
                   T 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 java.util.Comparator<T>

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:

java.lang.IllegalArgumentException - if obj1 or obj2 are not known to this Comparator and an alternative behavior has not been set via setUnknownObjectBehavior(UnknownObjectBehavior).

hashCode

public int hashCode()

Implement a hash code for this comparator that is consistent with equals.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code for this comparator.

equals

public boolean equals(java.lang.Object object)

Returns true iff that Object is is a Comparator whose ordering is known to be equivalent to mine.

This implementation returns true iff that is a FixedOrderComparator whose attributes are equal to mine.

Specified by:

equals in interface java.util.Comparator<T>

Overrides:

equals in class java.lang.Object

Parameters:

object - the object to compare to

Returns:

true if equal