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
Objects.
- 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
Objects.
- 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 booleanss.
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 bytes.
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 chars.
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
doubles.
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
floats.
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 ints.
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 longs.
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 shorts.
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
Objects 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
Objects 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
Objects 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.