org.josef.util

Class MultiFieldComparator<T>

java.lang.Object

org.josef.util.MultiFieldComparator<T>

Type Parameters:

T - The type of the Objects to compare.

All Implemented Interfaces:

Comparator<T>

@Status(stage=PRODUCTION,
        unitTests=COMPLETE)
 @Review(by="Kees Schotanus",
        at="2009-09-28")
 @ThreadSafety(level=NOT_THREAD_SAFE,
              doc="MultiFieldComparators are mutable!")
public final class MultiFieldComparator<T>
extends Object
implements Comparator<T>

Comparator Class that allows for the comparison of multiple fields.
When using CompareField objects (as opposed to Method objects to construct this MultiFieldComparator it is possible to compare fields that are present in an object that has a one to one relationship with type <T>.

Version:

1.0 $Revision: 5877 $

Author:

Kees Schotanus

Constructor Summary

Constructors

Constructor and Description
MultiFieldComparator(CompareField... allowedCompareFields) Constructs this MultiFieldComparator from the supplied compareFields.
MultiFieldComparator(Method... methods) Creates this MultiFieldComparator from the supplied methods by converting them to CompareField objects.

Method Summary

Modifier and Type	Method and Description
int	compare(T left, T right) Utility method to compare two objects of type <T>.
CompareField	getCompareField(int ordinal) Gets an CompareField by its ordinal number.
CompareField	getCompareField(String methodName) Gets a CompareField by the name of its corresponding method.
void	setCompareFields(CompareField... compareFields) Sets the fields to compare upon.
void	sort(List<T> items, String... sortColumns) Sort the supplied items on the supplied sortColumns.
String	toString() Creates a String representation of this MultiFieldComparator.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Comparator

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

Constructor Detail

MultiFieldComparator

public MultiFieldComparator(CompareField... allowedCompareFields)

Constructs this MultiFieldComparator from the supplied compareFields.

Parameters:

allowedCompareFields - All the compare fields that can possibly be compared upon.

Throws:

NullPointerException - When the supplied allowedCompareFields is null.

IllegalArgumentException - When the supplied allowedCompareFields is empty.

MultiFieldComparator

public MultiFieldComparator(Method... methods)

Creates this MultiFieldComparator from the supplied methods by converting them to CompareField objects.

Parameters:

methods - The methods used for ordering.

Throws:

NullPointerException - When the supplied methods is null.

IllegalArgumentException - When the supplied methods is empty.

Method Detail

setCompareFields

public void setCompareFields(CompareField... compareFields)

Sets the fields to compare upon.
When the current compare fields are equal to the supplied compareFields the order of the first compare field is toggled.

Parameters:

compareFields - The fields to compare upon.

Throws:

NullPointerException - When the supplied compareFields is null.

IllegalArgumentException - When the supplied compareFields is empty or contains a CompareField that is not one of the allowed CompareFields supplied at construction time.

getCompareField

public CompareField getCompareField(String methodName)

Gets a CompareField by the name of its corresponding method.

Parameters:

methodName - The name of the method.
The name of the method follows standard java bean conventions. Examples of method names are: getName, getColor.
When the method name is involved in a one to one relationship the method name has to be qualified. org.josef.demo.jpa.Car for example has a one to one relationship with org.josef.demo.jpa.CarDetail. To get the number of seats, supply: "getCarDetail.getSeats" as the method name.

Returns:

The CompareField with the supplied methodName.

Throws:

IllegalArgumentException - When the supplied methodName is empty or when no CompareField with the supplied methodName exists.

NullPointerException - When the supplied methodName is null.

getCompareField

public CompareField getCompareField(int ordinal)

Gets an CompareField by its ordinal number.

Parameters:

ordinal - The ordinal of the compare field (0 based).

Returns:

The CompareField with the supplied ordinal.

Throws:

IllegalArgumentException - When no CompareField with the supplied ordinal exists.

compare

public int compare(T left,
                   T right)

Utility method to compare two objects of type <T>.
When the actual fields to compare are Comparable comparing is trivial, when the actual fields to compare are not Comparable, they are both converted to a String before being compared.

Specified by:

compare in interface Comparator<T>

Parameters:

left - The Object on the left.

right - The Object on the right.

Returns:

-1 (left < right), 0 (left == right) or 1 (left > right).

Throws:

NullPointerException - When either the supplied left or right object is null.

IllegalStateException - When a reflection exception occurs or when no columns to sort upon have been set.

sort

public void sort(List<T> items,
                 String... sortColumns)

Sort the supplied items on the supplied sortColumns.

Parameters:

items - The items to sort.

sortColumns - The names of the columns to sort on.
Each individual sortColumn may consist of names separated by a point.

Throws:

IllegalArgumentException - When the supplied sortColumns is empty.

NullPointerException - When the supplied sortColumns is null.

toString

public String toString()

Creates a String representation of this MultiFieldComparator.
The format is: allowed_compare_field[,allowed_compare_field]...:used_compare_field[,used_compare_field]...
The format of each individual compare field is determined by its CompareField.toString() method.

Overrides:

toString in class Object

Returns:

String representation of this MultiFieldComparator.