BeanComparator (Cojen 2.2.5 API)

java.lang.Object
- org.cojen.util.BeanComparator<T>

All Implemented Interfaces:

Serializable, Comparator<T>
```
public class BeanComparator<T>
extends Object
implements Comparator<T>, 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");
 
```
The results of sorting Threads using this Comparator and displaying the results in a table may look like this:

name threadGroup.name priority

daemon appGroup 9

main main 5

main secureGroup 5

sweeper main 1

Thread-0 main 5

Thread-1 main 5

worker appGroup 8

worker appGroup 5

worker secureGroup 8

worker secureGroup 5

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

Brian S O'Neill

See Also:
Serialized Form

name	threadGroup.name	priority
daemon	appGroup	9
main	main	5
main	secureGroup	5
sweeper	main	1
Thread-0	main	5
Thread-1	main	5
worker	appGroup	8
worker	appGroup	5
worker	secureGroup	8
worker	secureGroup	5

Method Summary

Methods
Modifier and Type	Method and Description
`BeanComparator<T>`	`caseSensitive()` Override the collator and compare just the last order-by property using `String.compareTo`, if it is of type String.
`BeanComparator<T>`	`collate(Comparator<String> c)` Set a Comparator for ordering Strings, which is passed on to all BeanComparators derived from this one.
`int`	`compare(T obj1, T obj2)`
`boolean`	`equals(Object obj)` Compares BeanComparators for equality based on their imposed ordering.
`static <T> BeanComparator<T>`	`forClass(Class<T> clazz)` Get or create a new BeanComparator for beans of the given type.
`int`	`hashCode()`
`BeanComparator<T>`	`nullHigh()` Set the order of comparisons against null as being high (the default) on just the last `order-by` property.
`BeanComparator<T>`	`nullLow()` Set the order of comparisons against null as being low on just the last `order-by` property.
`BeanComparator<T>`	`orderBy(String propertyName)` Add an order-by property to produce a more refined Comparator.
`BeanComparator<T>`	`reverse()` Toggle reverse-order option on just the last `order-by` property.
`<S> BeanComparator<T>`	`using(Comparator<S> 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 <T> BeanComparator<T> forClass(Class<T> 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<T> orderBy(String propertyName)
                          throws 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.
    As a convenience, property names may have a '-' or '+' character prefix to specify sort order. A prefix of '-' indicates that the property is to be sorted in reverse (descending). By default, properties are sorted in ascending order, and so a prefix of '+' has no effect.
    Any previously applied reverse-order, null-order and case-sensitive settings are not carried over, and are reset to the defaults for this order-by property.
    
    Throws:
    
    IllegalArgumentException - when property doesn't exist or cannot be read.
  - using
```
public <S> BeanComparator<T> using(Comparator<S> 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 previously applied 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<T> 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<T> 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<T> 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<T> 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<T> collate(Comparator<String> 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(T obj1,
          T obj2)
            throws ClassCastException
```
    Specified by:
    
    compare in interface Comparator<T>
    
    Throws:
    
    ClassCastException
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(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 Comparator<T>
    
    Overrides:
    
    equals in class Object

Class BeanComparator<T>

Method Summary

Methods inherited from class java.lang.Object

Method Detail

forClass

orderBy

using

reverse

nullHigh

nullLow

caseSensitive

collate

compare

hashCode

equals