Assists in implementing
Comparable.compareTo(Object)
methods.
It is consistent with
equals(Object)
and
hashcode()
built with
EqualsBuilder
and
HashCodeBuilder
.
Two Objects that compare equal using
equals(Object)
should normally
also compare equal using
compareTo(Object)
.
All relevant fields should be included in the calculation of the
comparison. Derived fields may be ignored. The same fields, in the same
order, should be used in both
compareTo(Object)
and
equals(Object)
.
To use this class write code as follows:
public class MyClass {
String field1;
int field2;
boolean field3;
...
public int compareTo(Object o) {
MyClass myClass = (MyClass) o;
return new CompareToBuilder()
.appendSuper(super.compareTo(o)
.append(this.field1, myClass.field1)
.append(this.field2, myClass.field2)
.append(this.field3, myClass.field3)
.toComparison();
}
}
Alternatively, there is are
reflectionCompare
method that uses
reflection to determine the fields to append. Because fields can be private,
reflectionCompare
uses
AccessibleObject.setAccessible(boolean)
to
bypass normal access control checks. This will fail under a security manager,
unless the appropriate permissions are set up correctly. It is also
slower than appending explicitly.
A typical implementation of
compareTo(Object)
using
reflectionCompare
looks like:
public int compareTo(Object o) {
return CompareToBuilder.reflectionCompare(this, o);
}
append
public CompareToBuilder append(Object lhs,
Object rhs)
Appends to the
builder
the comparison of
two
Object
s.
- Check if
lhs == rhs
- Check if either
lhs
or rhs
is null
,
a null
object is less than a non-null
object - Check the object contents
lhs
must either be an array or implement
Comparable
.
lhs
- left-hand objectrhs
- right-hand object
- this - used to chain append calls
append
public CompareToBuilder append(Object lhs,
Object rhs,
Comparator comparator)
Appends to the
builder
the comparison of
two
Object
s.
- Check if
lhs == rhs
- Check if either
lhs
or rhs
is null
,
a null
object is less than a non-null
object - Check the object contents
If
lhs
is an array, array comparison methods will be used.
Otherwise
comparator
will be used to compare the objects.
If
comparator
is
null
,
lhs
must
implement
Comparable
instead.
lhs
- left-hand objectrhs
- right-hand objectcomparator
- Comparator
used to compare the objects,
null
means treat lhs as Comparable
- this - used to chain append calls
append
public CompareToBuilder append(Object[] lhs,
Object[] rhs)
Appends to the
builder
the deep comparison of
two
Object
arrays.
- Check if arrays are the same using
==
- Check if for
null
, null
is less than non-null
- Check array length, a short length array is less than a long length array
- Check array contents element by element using
append(Object,Object,Comparator)
This method will also will be called for the top level of multi-dimensional,
ragged, and multi-typed arrays.
lhs
- left-hand arrayrhs
- right-hand array
- this - used to chain append calls
append
public CompareToBuilder append(Object[] lhs,
Object[] rhs,
Comparator comparator)
Appends to the
builder
the deep comparison of
two
Object
arrays.
- Check if arrays are the same using
==
- Check if for
null
, null
is less than non-null
- Check array length, a short length array is less than a long length array
- Check array contents element by element using
append(Object,Object,Comparator)
This method will also will be called for the top level of multi-dimensional,
ragged, and multi-typed arrays.
lhs
- left-hand arrayrhs
- right-hand arraycomparator
- Comparator
to use to compare the array elements,
null
means to treat lhs
elements as Comparable
.
- this - used to chain append calls
append
public CompareToBuilder append(boolean lhs,
boolean rhs)
Appends to the builder
the comparison of
two booleans
s.
lhs
- left-hand valuerhs
- right-hand value
- this - used to chain append calls
append
public CompareToBuilder append(boolean[] lhs,
boolean[] rhs)
Appends to the
builder
the deep comparison of
two
boolean
arrays.
- Check if arrays are the same using
==
- Check if for
null
, null
is less than non-null
- Check array length, a shorter length array is less than a longer length array
- Check array contents element by element using
append(boolean,boolean)
lhs
- left-hand arrayrhs
- right-hand array
- this - used to chain append calls
append
public CompareToBuilder append(byte lhs,
byte rhs)
Appends to the builder
the comparison of
two byte
s.
lhs
- left-hand valuerhs
- right-hand value
- this - used to chain append calls
append
public CompareToBuilder append(byte[] lhs,
byte[] rhs)
Appends to the
builder
the deep comparison of
two
byte
arrays.
- Check if arrays are the same using
==
- Check if for
null
, null
is less than non-null
- Check array length, a shorter length array is less than a longer length array
- Check array contents element by element using
append(byte,byte)
lhs
- left-hand arrayrhs
- right-hand array
- this - used to chain append calls
append
public CompareToBuilder append(char lhs,
char rhs)
Appends to the builder
the comparison of
two char
s.
lhs
- left-hand valuerhs
- right-hand value
- this - used to chain append calls
append
public CompareToBuilder append(char[] lhs,
char[] rhs)
Appends to the
builder
the deep comparison of
two
char
arrays.
- Check if arrays are the same using
==
- Check if for
null
, null
is less than non-null
- Check array length, a shorter length array is less than a longer length array
- Check array contents element by element using
append(char,char)
lhs
- left-hand arrayrhs
- right-hand array
- this - used to chain append calls
append
public CompareToBuilder append(double lhs,
double rhs)
Appends to the
builder
the comparison of
two
double
s.
This handles NaNs, Infinities, and
-0.0
.
It is compatible with the hash code generated by
HashCodeBuilder
.
lhs
- left-hand valuerhs
- right-hand value
- this - used to chain append calls
append
public CompareToBuilder append(double[] lhs,
double[] rhs)
Appends to the
builder
the deep comparison of
two
double
arrays.
- Check if arrays are the same using
==
- Check if for
null
, null
is less than non-null
- Check array length, a shorter length array is less than a longer length array
- Check array contents element by element using
append(double,double)
lhs
- left-hand arrayrhs
- right-hand array
- this - used to chain append calls
append
public CompareToBuilder append(float lhs,
float rhs)
Appends to the
builder
the comparison of
two
float
s.
This handles NaNs, Infinities, and
-0.0
.
It is compatible with the hash code generated by
HashCodeBuilder
.
lhs
- left-hand valuerhs
- right-hand value
- this - used to chain append calls
append
public CompareToBuilder append(float[] lhs,
float[] rhs)
Appends to the
builder
the deep comparison of
two
float
arrays.
- Check if arrays are the same using
==
- Check if for
null
, null
is less than non-null
- Check array length, a shorter length array is less than a longer length array
- Check array contents element by element using
append(float,float)
lhs
- left-hand arrayrhs
- right-hand array
- this - used to chain append calls
append
public CompareToBuilder append(int lhs,
int rhs)
Appends to the builder
the comparison of
two int
s.
lhs
- left-hand valuerhs
- right-hand value
- this - used to chain append calls
append
public CompareToBuilder append(int[] lhs,
int[] rhs)
Appends to the
builder
the deep comparison of
two
int
arrays.
- Check if arrays are the same using
==
- Check if for
null
, null
is less than non-null
- Check array length, a shorter length array is less than a longer length array
- Check array contents element by element using
append(int,int)
lhs
- left-hand arrayrhs
- right-hand array
- this - used to chain append calls
append
public CompareToBuilder append(long lhs,
long rhs)
Appends to the builder
the comparison of
two long
s.
lhs
- left-hand valuerhs
- right-hand value
- this - used to chain append calls
append
public CompareToBuilder append(long[] lhs,
long[] rhs)
Appends to the
builder
the deep comparison of
two
long
arrays.
- Check if arrays are the same using
==
- Check if for
null
, null
is less than non-null
- Check array length, a shorter length array is less than a longer length array
- Check array contents element by element using
append(long,long)
lhs
- left-hand arrayrhs
- right-hand array
- this - used to chain append calls
append
public CompareToBuilder append(short lhs,
short rhs)
Appends to the builder
the comparison of
two short
s.
lhs
- left-hand valuerhs
- right-hand value
- this - used to chain append calls
append
public CompareToBuilder append(short[] lhs,
short[] rhs)
Appends to the
builder
the deep comparison of
two
short
arrays.
- Check if arrays are the same using
==
- Check if for
null
, null
is less than non-null
- Check array length, a shorter length array is less than a longer length array
- Check array contents element by element using
append(short,short)
lhs
- left-hand arrayrhs
- right-hand array
- this - used to chain append calls
appendSuper
public CompareToBuilder appendSuper(int superCompareTo)
Appends to the builder
the compareTo(Object)
result of the superclass.
superCompareTo
- result of calling super.compareTo(Object)
- this - used to chain append calls
reflectionCompare
public static int reflectionCompare(Object lhs,
Object rhs)
Compares two
Object
s via reflection.
Fields can be private, thus
AccessibleObject.setAccessible
is used to bypass normal access control checks. This will fail under a
security manager unless the appropriate permissions are set.
- Static fields will not be compared
- Transient members will be not be compared, as they are likely derived
fields
- Superclass fields will be compared
If both
lhs
and
rhs
are
null
,
they are considered equal.
lhs
- left-hand objectrhs
- right-hand object
- a negative integer, zero, or a positive integer as
lhs
is less than, equal to, or greater than rhs
reflectionCompare
public static int reflectionCompare(Object lhs,
Object rhs,
boolean compareTransients)
Compares two
Object
s via reflection.
Fields can be private, thus
AccessibleObject.setAccessible
is used to bypass normal access control checks. This will fail under a
security manager unless the appropriate permissions are set.
- Static fields will not be compared
- If
compareTransients
is true
,
compares transient members. Otherwise ignores them, as they
are likely derived fields. - Superclass fields will be compared
If both
lhs
and
rhs
are
null
,
they are considered equal.
lhs
- left-hand objectrhs
- right-hand objectcompareTransients
- whether to compare transient fields
- a negative integer, zero, or a positive integer as
lhs
is less than, equal to, or greater than rhs
reflectionCompare
public static int reflectionCompare(Object lhs,
Object rhs,
boolean compareTransients,
Class reflectUpToClass)
Compares two
Object
s via reflection.
Fields can be private, thus
AccessibleObject.setAccessible
is used to bypass normal access control checks. This will fail under a
security manager unless the appropriate permissions are set.
- Static fields will not be compared
- If the
compareTransients
is true
,
compares transient members. Otherwise ignores them, as they
are likely derived fields. - Compares superclass fields up to and including
reflectUpToClass
.
If reflectUpToClass
is null
, compares all superclass fields.
If both
lhs
and
rhs
are
null
,
they are considered equal.
lhs
- left-hand objectrhs
- right-hand objectcompareTransients
- whether to compare transient fieldsreflectUpToClass
- last superclass for which fields are compared
- a negative integer, zero, or a positive integer as
lhs
is less than, equal to, or greater than rhs
toComparison
public int toComparison()
Returns a negative integer, a positive integer, or zero as
the builder
has judged the "left-hand" side
as less than, greater than, or equal to the "right-hand"
side.