com.go.trove.util
Class BeanComparator

java.lang.Object
  |
  +--com.go.trove.util.BeanComparator
All Implemented Interfaces:
java.util.Comparator, java.io.Serializable

public class BeanComparator
extends java.lang.Object
implements java.util.Comparator, java.io.Serializable

A highly customizable, high-performance Comparator, designed specifically for advanced sorting of JavaBeans. BeanComparators contain dynamically auto-generated code and perform as well as hand written Comparators.

BeanComparator instances are immutable; order customization methods return new BeanComparators with refined rules. Calls to customizers can be chained together to read like a formula. The following example produces a Comparator that orders Threads by name, thread group name, and reverse priority.

 Comparator c = BeanComparator.forClass(Thread.class)
     .orderBy("name")
     .orderBy("threadGroup.name")
     .orderBy("priority")
     .reverse();
 
The results of sorting Threads using this Comparator and displaying the results in a table may look like this:

namethreadGroup.namepriority
daemonappGroup9
mainmain5
mainsecureGroup5
sweepermain1
Thread-0main5
Thread-1main5
workerappGroup8
workerappGroup5
workersecureGroup8
workersecureGroup5

An equivalent Thread ordering Comparator may be specified as:

 Comparator c = BeanComparator.forClass(Thread.class)
     .orderBy("name")
     .orderBy("threadGroup")
     .using(BeanComparator.forClass(ThreadGroup.class).orderBy("name"))
     .orderBy("priority")
     .reverse();
 
The current implementation of BeanComparator has been optimized for fast construction and execution of BeanComparators. For maximum performance, however, save and re-use BeanComparators wherever possible.

Even though BeanComparator makes use of auto-generated code, instances are fully Serializable, as long as all passed in Comparators are also Serializable.

Version:
18 , 00/12/18
Author:
Brian S O'Neill
See Also:
Introspector, CompleteIntrospector, java.util.Collections.sort, java.util.Arrays.sort, Serialized Form

Method Summary
 BeanComparator caseSensitive()
          Override the collator and compare just the last order-by property using String.compareTo, if it is of type String.
 BeanComparator collate(java.util.Comparator c)
          Set a Comparator for ordering Strings, which is passed on to all BeanComparators derived from this one.
 int compare(java.lang.Object obj1, java.lang.Object obj2)
           
 boolean equals(java.lang.Object obj)
          Compares BeanComparators for equality based on their imposed ordering.
static BeanComparator forClass(java.lang.Class clazz)
          Get or create a new BeanComparator for beans of the given type.
 int hashCode()
           
 BeanComparator nullHigh()
          Set the order of comparisons against null as being high (the default) on just the last order-by property.
 BeanComparator nullLow()
          Set the order of comparisons against null as being low on just the last order-by property.
 BeanComparator orderBy(java.lang.String propertyName)
          Add an order-by property to produce a more refined Comparator.
 BeanComparator reverse()
          Toggle reverse-order option on just the last order-by property.
 BeanComparator using(java.util.Comparator c)
          Specifiy a Comparator to use on just the last order-by property.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

forClass

public static BeanComparator forClass(java.lang.Class clazz)
Get or create a new BeanComparator for beans of the given type. Without any order-by properties specified, the returned BeanComparator can only order against null beans (null is high by default), and treats all other comparisons as equal.

orderBy

public BeanComparator orderBy(java.lang.String propertyName)
                       throws java.lang.IllegalArgumentException
Add an order-by property to produce a more refined Comparator. If the property does not return a Comparable object when compare is called on the returned comparator, the property is ignored. Call using on the returned BeanComparator to specify a Comparator to use for this property instead.

The specified propery name may refer to sub-properties using a dot notation. For example, if the bean being compared contains a property named "info" of type "Information", and "Information" contains a property named "text", then ordering by the info text can be specified by "info.text". Sub-properties of sub-properties may be refered to as well, a.b.c.d.e etc.

If property type is a primitive, ordering is the same as for its Comparable object peer. Primitive booleans are ordered false low, true high. Floating point primitves are ordered exactly the same way as Float.compareTo and Double.compareTo.

Any reverse-order, null-order and case-sensitive settings are not carried over, and are reset to the defaults for this order-by property.

Throws:
java.lang.IllegalArgumentException - when property doesn't exist or cannot be read.

using

public BeanComparator using(java.util.Comparator c)
Specifiy a Comparator to use on just the last order-by property. This is good for comparing properties that are not Comparable or for applying special ordering rules for a property. If no order-by properties have been specified, then Comparator is applied to the compared beans.

Any String case-sensitive or collator settings are overridden by this Comparator. If property values being compared are primitive, they are converted to their object peers before being passed to the Comparator.

Parameters:
c - Comparator to use on the last order-by property. Passing null restores the default comparison for the last order-by property.

reverse

public BeanComparator reverse()
Toggle reverse-order option on just the last order-by property. By default, order is ascending. If no order-by properties have been specified, then reverse order is applied to the compared beans.

nullHigh

public BeanComparator nullHigh()
Set the order of comparisons against null as being high (the default) on just the last order-by property. If no order-by properties have been specified, then null high order is applied to the compared beans. Null high order is the default for consistency with the high ordering of NaN by Float.

Calling 'nullHigh, reverse' is equivalent to calling 'reverse, nullLow'.


nullLow

public BeanComparator nullLow()
Set the order of comparisons against null as being low on just the last order-by property. If no order-by properties have been specified, then null low order is applied to the compared beans.

Calling 'reverse, nullLow' is equivalent to calling 'nullHigh, reverse'.


caseSensitive

public BeanComparator caseSensitive()
Override the collator and compare just the last order-by property using String.compareTo, if it is of type String. If no order-by properties have been specified then this call is ineffective.

A using Comparator disables this setting. Passing null to the using method will re-enable a case-sensitive setting.


collate

public BeanComparator collate(java.util.Comparator c)
Set a Comparator for ordering Strings, which is passed on to all BeanComparators derived from this one. By default, String are compared using String.CASE_INSENSITIVE_ORDER. Passing null for a collator will cause all String comparisons to use String.compareTo.

A using Comparator disables this setting. Passing null to the using method will re-enable a collator.

Parameters:
c - Comparator to use for ordering all Strings. Passing null causes all Strings to be ordered by String.compareTo.

compare

public int compare(java.lang.Object obj1,
                   java.lang.Object obj2)
            throws java.lang.ClassCastException
Specified by:
compare in interface java.util.Comparator

hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)
Compares BeanComparators for equality based on their imposed ordering. Returns true only if the given object is a BeanComparater and it can be determined without a doubt that the ordering is identical. Because equality testing is dependent on the behavior of the equals methods of any 'using' Comparators and/or collators, false may be returned even though ordering is in fact identical.
Specified by:
equals in interface java.util.Comparator
Overrides:
equals in class java.lang.Object