Class CompareToBuilder
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();
}
}
Values are compared in the order they are appended to the builder. If any comparison returns
a non-zero result, then that value will be the result returned by toComparison() and all
subsequent comparisons are skipped.
Alternatively, there are reflectionCompare methods that use
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);
}
The reflective methods compare object fields in the order returned by
Class.getDeclaredFields(). The fields of the class are compared first, followed by those
of its parent classes (in order from the bottom to the top of the class hierarchy).
- Since:
- 1.0
- See Also:
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionappend(boolean[] lhs, boolean[] rhs) Appends to thebuilderthe deep comparison of twobooleanarrays.append(boolean lhs, boolean rhs) Appends to thebuilderthe comparison of twobooleanss.append(byte[] lhs, byte[] rhs) Appends to thebuilderthe deep comparison of twobytearrays.append(byte lhs, byte rhs) Appends to thebuilderthe comparison of twobytes.append(char[] lhs, char[] rhs) Appends to thebuilderthe deep comparison of twochararrays.append(char lhs, char rhs) Appends to thebuilderthe comparison of twochars.append(double[] lhs, double[] rhs) Appends to thebuilderthe deep comparison of twodoublearrays.append(double lhs, double rhs) Appends to thebuilderthe comparison of twodoubles.append(float[] lhs, float[] rhs) Appends to thebuilderthe deep comparison of twofloatarrays.append(float lhs, float rhs) Appends to thebuilderthe comparison of twofloats.append(int[] lhs, int[] rhs) Appends to thebuilderthe deep comparison of twointarrays.append(int lhs, int rhs) Appends to thebuilderthe comparison of twoints.append(long[] lhs, long[] rhs) Appends to thebuilderthe deep comparison of twolongarrays.append(long lhs, long rhs) Appends to thebuilderthe comparison of twolongs.append(short[] lhs, short[] rhs) Appends to thebuilderthe deep comparison of twoshortarrays.append(short lhs, short rhs) Appends to thebuilderthe comparison of twoshorts.Appends to thebuilderthe deep comparison of twoObjectarrays.append(Object[] lhs, Object[] rhs, Comparator<?> comparator) Appends to thebuilderthe deep comparison of twoObjectarrays.Appends to thebuilderthe comparison of twoObjects.append(Object lhs, Object rhs, Comparator<?> comparator) Appends to thebuilderthe comparison of twoObjects.appendSuper(int superCompareTo) Appends to thebuilderthecompareTo(Object)result of the superclass.build()Returns a negative Integer, a positive Integer, or zero as thebuilderhas judged the "left-hand" side as less than, greater than, or equal to the "right-hand" side.static intreflectionCompare(Object lhs, Object rhs) Compares twoObjects via reflection.static intreflectionCompare(Object lhs, Object rhs, boolean compareTransients) Compares twoObjects via reflection.static intreflectionCompare(Object lhs, Object rhs, boolean compareTransients, Class<?> reflectUpToClass, String... excludeFields) Compares twoObjects via reflection.static intreflectionCompare(Object lhs, Object rhs, String... excludeFields) Compares twoObjects via reflection.static intreflectionCompare(Object lhs, Object rhs, Collection<String> excludeFields) Compares twoObjects via reflection.intReturns a negative integer, a positive integer, or zero as thebuilderhas judged the "left-hand" side as less than, greater than, or equal to the "right-hand" side.
-
Constructor Details
-
CompareToBuilder
public CompareToBuilder()Constructor for CompareToBuilder.Starts off assuming that the objects are equal. Multiple calls are then made to the various append methods, followed by a call to
toComparison()to get the result.
-
-
Method Details
-
reflectionCompare
Compares twoObjects via reflection.Fields can be private, thus
AccessibleObject.setAccessibleis 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
lhsandrhsarenull, they are considered equal.- Parameters:
lhs- left-hand side objectrhs- right-hand side object- Returns:
- a negative integer, zero, or a positive integer as
lhsis less than, equal to, or greater thanrhs - Throws:
NullPointerException- if either (but not both) parameters arenullClassCastException- ifrhsis not assignment-compatible withlhs
-
reflectionCompare
Compares twoObjects via reflection.Fields can be private, thus
AccessibleObject.setAccessibleis 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
compareTransientsistrue, compares transient members. Otherwise ignores them, as they are likely derived fields. - Superclass fields will be compared
If both
lhsandrhsarenull, they are considered equal.- Parameters:
lhs- left-hand side objectrhs- right-hand side objectcompareTransients- whether to compare transient fields- Returns:
- a negative integer, zero, or a positive integer as
lhsis less than, equal to, or greater thanrhs - Throws:
NullPointerException- if eitherlhsorrhs(but not both) isnullClassCastException- ifrhsis not assignment-compatible withlhs
-
reflectionCompare
public static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients, Class<?> reflectUpToClass, String... excludeFields) Compares twoObjects via reflection.Fields can be private, thus
AccessibleObject.setAccessibleis 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
compareTransientsistrue, compares transient members. Otherwise ignores them, as they are likely derived fields. - Compares superclass fields up to and including
reflectUpToClass. IfreflectUpToClassisnull, compares all superclass fields.
If both
lhsandrhsarenull, they are considered equal.- Parameters:
lhs- left-hand side objectrhs- right-hand side objectcompareTransients- whether to compare transient fieldsreflectUpToClass- last superclass for which fields are comparedexcludeFields- fields to exclude- Returns:
- a negative integer, zero, or a positive integer as
lhsis less than, equal to, or greater thanrhs - Throws:
NullPointerException- if eitherlhsorrhs(but not both) isnullClassCastException- ifrhsis not assignment-compatible withlhs- Since:
- 2.2 (2.0 as
reflectionCompare(Object, Object, boolean, Class))
-
reflectionCompare
Compares twoObjects via reflection.Fields can be private, thus
AccessibleObject.setAccessibleis 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
compareTransientsistrue, compares transient members. Otherwise ignores them, as they are likely derived fields. - Superclass fields will be compared
If both
lhsandrhsarenull, they are considered equal.- Parameters:
lhs- left-hand side objectrhs- right-hand side objectexcludeFields- Collection of String fields to exclude- Returns:
- a negative integer, zero, or a positive integer as
lhsis less than, equal to, or greater thanrhs - Throws:
NullPointerException- if eitherlhsorrhs(but not both) isnullClassCastException- ifrhsis not assignment-compatible withlhs- Since:
- 2.2
-
reflectionCompare
Compares twoObjects via reflection.Fields can be private, thus
AccessibleObject.setAccessibleis 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
compareTransientsistrue, compares transient members. Otherwise ignores them, as they are likely derived fields. - Superclass fields will be compared
If both
lhsandrhsarenull, they are considered equal.- Parameters:
lhs- left-hand side objectrhs- right-hand side objectexcludeFields- array of fields to exclude- Returns:
- a negative integer, zero, or a positive integer as
lhsis less than, equal to, or greater thanrhs - Throws:
NullPointerException- if eitherlhsorrhs(but not both) isnullClassCastException- ifrhsis not assignment-compatible withlhs- Since:
- 2.2
-
append
Appends to thebuilderthe comparison of twobooleanss.- Parameters:
lhs- left-hand side valuerhs- right-hand side value- Returns:
thisinstance.
-
append
Appends to thebuilderthe deep comparison of twobooleanarrays.- Check if arrays are the same using
== - Check if for
null,nullis 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)
- Parameters:
lhs- left-hand side arrayrhs- right-hand side array- Returns:
thisinstance.
- Check if arrays are the same using
-
append
Appends to thebuilderthe comparison of twobytes.- Parameters:
lhs- left-hand side valuerhs- right-hand side value- Returns:
thisinstance.
-
append
Appends to thebuilderthe deep comparison of twobytearrays.- Check if arrays are the same using
== - Check if for
null,nullis 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)
- Parameters:
lhs- left-hand side arrayrhs- right-hand side array- Returns:
thisinstance.
- Check if arrays are the same using
-
append
Appends to thebuilderthe comparison of twochars.- Parameters:
lhs- left-hand side valuerhs- right-hand side value- Returns:
thisinstance.
-
append
Appends to thebuilderthe deep comparison of twochararrays.- Check if arrays are the same using
== - Check if for
null,nullis 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)
- Parameters:
lhs- left-hand side arrayrhs- right-hand side array- Returns:
thisinstance.
- Check if arrays are the same using
-
append
Appends to thebuilderthe comparison of twodoubles.This handles NaNs, Infinities, and
-0.0.It is compatible with the hash code generated by
HashCodeBuilder.- Parameters:
lhs- left-hand side valuerhs- right-hand side value- Returns:
thisinstance.
-
append
Appends to thebuilderthe deep comparison of twodoublearrays.- Check if arrays are the same using
== - Check if for
null,nullis 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)
- Parameters:
lhs- left-hand side arrayrhs- right-hand side array- Returns:
thisinstance.
- Check if arrays are the same using
-
append
Appends to thebuilderthe comparison of twofloats.This handles NaNs, Infinities, and
-0.0.It is compatible with the hash code generated by
HashCodeBuilder.- Parameters:
lhs- left-hand side valuerhs- right-hand side value- Returns:
thisinstance.
-
append
Appends to thebuilderthe deep comparison of twofloatarrays.- Check if arrays are the same using
== - Check if for
null,nullis 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)
- Parameters:
lhs- left-hand side arrayrhs- right-hand side array- Returns:
thisinstance.
- Check if arrays are the same using
-
append
Appends to thebuilderthe comparison of twoints.- Parameters:
lhs- left-hand side valuerhs- right-hand side value- Returns:
thisinstance.
-
append
Appends to thebuilderthe deep comparison of twointarrays.- Check if arrays are the same using
== - Check if for
null,nullis 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)
- Parameters:
lhs- left-hand side arrayrhs- right-hand side array- Returns:
thisinstance.
- Check if arrays are the same using
-
append
Appends to thebuilderthe comparison of twolongs.- Parameters:
lhs- left-hand side valuerhs- right-hand side value- Returns:
thisinstance.
-
append
Appends to thebuilderthe deep comparison of twolongarrays.- Check if arrays are the same using
== - Check if for
null,nullis 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)
- Parameters:
lhs- left-hand side arrayrhs- right-hand side array- Returns:
thisinstance.
- Check if arrays are the same using
-
append
Appends to thebuilderthe comparison of twoObjects.- Check if
lhs == rhs - Check if either
lhsorrhsisnull, anullobject is less than a non-nullobject - Check the object contents
lhsmust either be an array or implementComparable.- Parameters:
lhs- left-hand side objectrhs- right-hand side object- Returns:
thisinstance.- Throws:
ClassCastException- ifrhsis not assignment-compatible withlhs
- Check if
-
append
Appends to thebuilderthe comparison of twoObjects.- Check if
lhs == rhs - Check if either
lhsorrhsisnull, anullobject is less than a non-nullobject - Check the object contents
If
lhsis an array, array comparison methods will be used. Otherwisecomparatorwill be used to compare the objects. Ifcomparatorisnull,lhsmust implementComparableinstead.- Parameters:
lhs- left-hand side objectrhs- right-hand side objectcomparator-Comparatorused to compare the objects,nullmeans treat lhs asComparable- Returns:
thisinstance.- Throws:
ClassCastException- ifrhsis not assignment-compatible withlhs- Since:
- 2.0
- Check if
-
append
Appends to thebuilderthe deep comparison of twoObjectarrays.- Check if arrays are the same using
== - Check if for
null,nullis 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.
- Parameters:
lhs- left-hand side arrayrhs- right-hand side array- Returns:
thisinstance.- Throws:
ClassCastException- ifrhsis not assignment-compatible withlhs
- Check if arrays are the same using
-
append
Appends to thebuilderthe deep comparison of twoObjectarrays.- Check if arrays are the same using
== - Check if for
null,nullis 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.
- Parameters:
lhs- left-hand side arrayrhs- right-hand side arraycomparator-Comparatorto use to compare the array elements,nullmeans to treatlhselements asComparable.- Returns:
thisinstance.- Throws:
ClassCastException- ifrhsis not assignment-compatible withlhs- Since:
- 2.0
- Check if arrays are the same using
-
append
Appends to thebuilderthe comparison of twoshorts.- Parameters:
lhs- left-hand side valuerhs- right-hand side value- Returns:
thisinstance.
-
append
Appends to thebuilderthe deep comparison of twoshortarrays.- Check if arrays are the same using
== - Check if for
null,nullis 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)
- Parameters:
lhs- left-hand side arrayrhs- right-hand side array- Returns:
thisinstance.
- Check if arrays are the same using
-
appendSuper
Appends to thebuilderthecompareTo(Object)result of the superclass.- Parameters:
superCompareTo- result of callingsuper.compareTo(Object)- Returns:
thisinstance.- Since:
- 2.0
-
build
Returns a negative Integer, a positive Integer, or zero as thebuilderhas judged the "left-hand" side as less than, greater than, or equal to the "right-hand" side. -
toComparison
Returns a negative integer, a positive integer, or zero as thebuilderhas judged the "left-hand" side as less than, greater than, or equal to the "right-hand" side.- Returns:
- final comparison result
- See Also:
-