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.

Nested and Inner Type Summary

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

Modifier and Type	Field and Description
private int	counter Counter used in determining the position in the map
private boolean	isLocked Is the comparator locked against further change
private final Map<T, Integer>	map Internal map of object to position
private static final long	serialVersionUID Serialization version from Collections 4.0.
private FixedOrderComparator.UnknownObjectBehavior	unknownObjectBehavior The behaviour in the case of an unknown object

Constructor Summary

Access	Constructor and Description
public	FixedOrderComparator() Constructs an empty FixedOrderComparator.
public	FixedOrderComparator(final T... the items that the comparator can compare in order items) Constructs a FixedOrderComparator which uses the order of the given array to compare the objects.
public	FixedOrderComparator(final List<T> the items that the comparator can compare in order items) Constructs a FixedOrderComparator which uses the order of the given list to compare the objects.

Method Summary

Modifier and Type	Method and Description
public boolean	Returns: true if obj has been added for the first time, false if it was already known to the Comparator. add(final T the item to be added to the Comparator. obj) Adds an item, which compares as after all items known to the Comparator.
public boolean	Returns: true if newObj has been added for the first time, false if it was already known to the Comparator. addAsEqual(final T an item already in the Comparator's set of known objects existingObj, final T an item to be added to the Comparator's set of known objects 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	Returns: negative if obj1 is less, positive if greater, zero if equal compare(final T the first object to compare obj1, final T the second object to compare obj2) Implements java.util.Comparator.compare. Compares two objects according to the order of this Comparator.
public boolean	Returns: true if equal equals(final Object the object to compare to object) Overrides java.lang.Object.equals. Implements java.util.Comparator.equals. Returns `true` iff that Object is is a `Comparator` whose ordering is known to be equivalent to mine.
public FixedOrderComparator.UnknownObjectBehavior	Returns: `UnknownObjectBehavior` getUnknownObjectBehavior() Gets the behavior for comparing unknown objects.
public int	Returns: a hash code for this comparator. hashCode() Overrides java.lang.Object.hashCode. Implement a hash code for this comparator that is consistent with `equals`.
public boolean	Returns: true if attempts to change the FixedOrderComparator yield an UnsupportedOperationException, false if it can be changed. isLocked() Returns true if modifications cannot be made to the FixedOrderComparator.
public void	setUnknownObjectBehavior(final FixedOrderComparator.UnknownObjectBehavior the flag for unknown behaviour - UNKNOWN_AFTER, UNKNOWN_BEFORE or UNKNOWN_THROW_EXCEPTION unknownObjectBehavior) Sets the behavior for comparing unknown objects.

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll toString wait wait wait

Field Detail

counter	back to summary
private int counter Counter used in determining the position in the map

isLocked	back to summary
private boolean isLocked Is the comparator locked against further change

map	back to summary
private final Map<T, Integer> map Internal map of object to position

serialVersionUID	back to summary
private static final long serialVersionUID Serialization version from Collections 4.0.

unknownObjectBehavior	back to summary
private FixedOrderComparator.UnknownObjectBehavior unknownObjectBehavior The behaviour in the case of an unknown object

Constructor Detail

FixedOrderComparator	back to summary
public FixedOrderComparator() Constructs an empty FixedOrderComparator.

FixedOrderComparator	back to summary
public FixedOrderComparator(final 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:T[] the items that the comparator can compare in order Exceptions NullPointerException: if the array is null

FixedOrderComparator

back to summary

public FixedOrderComparator(final 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:T[]: the items that the comparator can compare in order

Exceptions

NullPointerException:: if the array is null

FixedOrderComparator	back to summary
public FixedOrderComparator(final 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:List<T> the items that the comparator can compare in order Exceptions NullPointerException: if the list is null

FixedOrderComparator

back to summary

public FixedOrderComparator(final 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:List<T>: the items that the comparator can compare in order

Exceptions

NullPointerException:: if the list is null

Method Detail

add	back to summary
public boolean add(final 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:T the item to be added to the Comparator. Returns:boolean true if obj has been added for the first time, false if it was already known to the Comparator. Exceptions UnsupportedOperationException: if a comparison has already been made

add

back to summary

public boolean add(final 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:T: the item to be added to the Comparator.

Returns:boolean

true if obj has been added for the first time, false if it was already known to the Comparator.

Exceptions

UnsupportedOperationException:: if a comparison has already been made

addAsEqual	back to summary
public boolean addAsEqual(final T existingObj, final T newObj) Adds a new item, which compares as equal to the given existing item. Parameters existingObj:T an item already in the Comparator's set of known objects newObj:T an item to be added to the Comparator's set of known objects Returns:boolean true if newObj has been added for the first time, false if it was already known to the Comparator. Exceptions IllegalArgumentException: if existingObject is not in the Comparator's set of known objects. UnsupportedOperationException: if a comparison has already been made

addAsEqual

back to summary

public boolean addAsEqual(final T existingObj, final T newObj)

Adds a new item, which compares as equal to the given existing item.

Parameters

existingObj:T: an item already in the Comparator's set of known objects
newObj:T: an item to be added to the Comparator's set of known objects

Returns:boolean

true if newObj has been added for the first time, false if it was already known to the Comparator.

Exceptions

IllegalArgumentException:: if existingObject is not in the Comparator's set of known objects.
UnsupportedOperationException:: if a comparison has already been made

checkLocked	back to summary
protected void checkLocked() Checks to see whether the comparator is now locked against further changes. Exceptions UnsupportedOperationException: if the comparator is locked

checkLocked

back to summary

protected void checkLocked()

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

Exceptions

UnsupportedOperationException:: if the comparator is locked

compare back to summary

compare	back to summary
public int compare(final T obj1, final T obj2) Implements java.util.Comparator.compare. 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 unrecognized object. This is not specified in the Comparator interface, but is the most appropriate exception. Parameters obj1:T the first object to compare obj2:T the second object to compare Returns:int negative if obj1 is less, positive if greater, zero if equal Annotations @Override Exceptions IllegalArgumentException: if obj1 or obj2 are not known to this Comparator and an alternative behavior has not been set via `setUnknownObjectBehavior(UnknownObjectBehavior)`.

public int compare(final T obj1, final T obj2)

Implements java.util.Comparator.compare.

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 unrecognized object. This is not specified in the Comparator interface, but is the most appropriate exception.

Parameters

obj1:T: the first object to compare
obj2:T: the second object to compare

Returns:int

negative if obj1 is less, positive if greater, zero if equal

Annotations

@Override

Exceptions

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

equals back to summary

equals	back to summary
public boolean equals(final Object object) Overrides java.lang.Object.equals. Implements java.util.Comparator.equals. 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. Parameters object:Object the object to compare to Returns:boolean true if equal Annotations @Override

public boolean equals(final Object object)

Overrides java.lang.Object.equals.

Implements java.util.Comparator.equals.

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.

Parameters

object:Object: the object to compare to

Returns:boolean

true if equal

Annotations

@Override

getUnknownObjectBehavior back to summary

getUnknownObjectBehavior	back to summary
public FixedOrderComparator.UnknownObjectBehavior getUnknownObjectBehavior() Gets the behavior for comparing unknown objects. Returns:FixedOrderComparator.UnknownObjectBehavior `UnknownObjectBehavior`

public FixedOrderComparator.UnknownObjectBehavior getUnknownObjectBehavior()

Gets the behavior for comparing unknown objects.

Returns:FixedOrderComparator.UnknownObjectBehavior: UnknownObjectBehavior

hashCode back to summary

hashCode	back to summary
public int hashCode() Overrides java.lang.Object.hashCode. Implement a hash code for this comparator that is consistent with `equals`. Returns:int a hash code for this comparator. Annotations @Override

public int hashCode()

Overrides java.lang.Object.hashCode.

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

Returns:int

a hash code for this comparator.

Annotations

@Override

isLocked	back to summary
public boolean isLocked() Returns true if modifications cannot be made to the FixedOrderComparator. FixedOrderComparators cannot be modified once they have performed a comparison. Returns:boolean true if attempts to change the FixedOrderComparator yield an UnsupportedOperationException, false if it can be changed.

isLocked

back to summary

public boolean isLocked()

Returns true if modifications cannot be made to the FixedOrderComparator. FixedOrderComparators cannot be modified once they have performed a comparison.

Returns:boolean: true if attempts to change the FixedOrderComparator yield an UnsupportedOperationException, false if it can be changed.

setUnknownObjectBehavior	back to summary
public void setUnknownObjectBehavior(final FixedOrderComparator.UnknownObjectBehavior unknownObjectBehavior) Sets the behavior for comparing unknown objects. Parameters unknownObjectBehavior:FixedOrderComparator.UnknownObjectBehavior the flag for unknown behaviour - UNKNOWN_AFTER, UNKNOWN_BEFORE or UNKNOWN_THROW_EXCEPTION Exceptions UnsupportedOperationException: if a comparison has been performed NullPointerException: if unknownObjectBehavior is null

setUnknownObjectBehavior

back to summary

public void setUnknownObjectBehavior(final FixedOrderComparator.UnknownObjectBehavior unknownObjectBehavior)

Sets the behavior for comparing unknown objects.

Parameters

unknownObjectBehavior:FixedOrderComparator.UnknownObjectBehavior: the flag for unknown behaviour - UNKNOWN_AFTER, UNKNOWN_BEFORE or UNKNOWN_THROW_EXCEPTION

Exceptions

UnsupportedOperationException:: if a comparison has been performed
NullPointerException:: if unknownObjectBehavior is null

org.apache.commons.collections4.comparators back to summary

public final Enum FixedOrderComparator.UnknownObjectBehavior

Class Inheritance

extends Enum<FixedOrderComparator.UnknownObjectBehavior>

java.lang.Object
java.lang.Enum
org.apache.commons.collections4.comparators.FixedOrderComparator.UnknownObjectBehavior

Unknown object behavior enum.

Since: 4.0

Field Summary

Modifier and Type	Field and Description
public static final FixedOrderComparator.UnknownObjectBehavior	AFTER
public static final FixedOrderComparator.UnknownObjectBehavior	BEFORE
public static final FixedOrderComparator.UnknownObjectBehavior	EXCEPTION

Constructor Summary

Access	Constructor and Description
private	UnknownObjectBehavior()

Method Summary

Modifier and Type	Method and Description
public static FixedOrderComparator.UnknownObjectBehavior	valueOf(String name)
public static FixedOrderComparator.UnknownObjectBehavior[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

AFTER	back to summary
public static final FixedOrderComparator.UnknownObjectBehavior AFTER

BEFORE	back to summary
public static final FixedOrderComparator.UnknownObjectBehavior BEFORE

EXCEPTION	back to summary
public static final FixedOrderComparator.UnknownObjectBehavior EXCEPTION

Constructor Detail

UnknownObjectBehavior	back to summary
private UnknownObjectBehavior()

Method Detail

valueOf	back to summary
public static FixedOrderComparator.UnknownObjectBehavior valueOf(String name)

values	back to summary
public static FixedOrderComparator.UnknownObjectBehavior[] values()

public Class FixedOrderComparator<T>

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Enum FixedOrderComparator.UnknownObjectBehavior

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail