| java.lang.Object
 org.cojen.util.BeanComparator
| BeanComparator | | public class BeanComparator implements Comparator,Serializable(Code) | | 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 |
| caseSensitive | | public BeanComparator caseSensitive()(Code) | | Override the collator and compare just the last order-by property using
String.compareTo(String) String.compareTo , if it is of type
String. If no order-by properties have been specified then this call is
ineffective.
A
BeanComparator.using using Comparator disables this setting. Passing null to
the using method will re-enable a case-sensitive setting.
|
| equals | | public boolean equals(Object obj)(Code) | | 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.
|
| forClass | | public static BeanComparator forClass(Class clazz)(Code) | | Get or create a new BeanComparator for beans of the given type. Without
any
BeanComparator.orderBy order-by properties specified, the returned
BeanComparator can only order against null beans (null is
BeanComparator.nullHigh high by default), and treats all other comparisons as
equal.
|
| hashCode | | public int hashCode()(Code) | | |
| nullHigh | | public BeanComparator nullHigh()(Code) | | Set the order of comparisons against null as being high (the default)
on just the last
BeanComparator.orderBy 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
Float.NaN NaN by
Float.compareTo(Float) Float .
Calling 'nullHigh, reverse' is equivalent to calling 'reverse, nullLow'.
|
| nullLow | | public BeanComparator nullLow()(Code) | | Set the order of comparisons against null as being low
on just the last
BeanComparator.orderBy 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'.
|
| orderBy | | public BeanComparator orderBy(String propertyName) throws IllegalArgumentException(Code) | | Add an order-by property to produce a more refined Comparator. If the
property does not return a
Comparable object when
BeanComparator.compare compare is called on the returned comparator, the
property is ignored. Call
BeanComparator.using 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(Float) Float.compareTo and
Double.compareTo(Double) 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
BeanComparator.reverse reverse-order ,
BeanComparator.nullHighnull-order and
BeanComparator.caseSensitive 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 cannotbe read. |
| reverse | | public BeanComparator reverse()(Code) | | Toggle reverse-order option on just the last
BeanComparator.orderBy 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.
|
| using | | public BeanComparator using(Comparator c)(Code) | | Specifiy a Comparator to use on just the last
BeanComparator.orderBy 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
BeanComparator.caseSensitive case-sensitive or
BeanComparator.collate 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 nullrestores the default comparison for the last order-by property. |
|
|