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 SummaryConstructors
- 
Method SummaryModifier 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- 
CompareToBuilderpublic 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- 
reflectionCompareCompares 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 object
- rhs- 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 are- null
- ClassCastException- if- rhsis not assignment-compatible with- lhs
 
- 
reflectionCompareCompares 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 object
- rhs- right-hand side object
- compareTransients- 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 either- lhsor- rhs(but not both) is- null
- ClassCastException- if- rhsis not assignment-compatible with- lhs
 
- 
reflectionComparepublic 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 object
- rhs- right-hand side object
- compareTransients- whether to compare transient fields
- reflectUpToClass- last superclass for which fields are compared
- excludeFields- fields to exclude
- Returns:
- a negative integer, zero, or a positive integer as lhsis less than, equal to, or greater thanrhs
- Throws:
- NullPointerException- if either- lhsor- rhs(but not both) is- null
- ClassCastException- if- rhsis not assignment-compatible with- lhs
- Since:
- 2.2 (2.0 as reflectionCompare(Object, Object, boolean, Class))
 
- 
reflectionCompareCompares 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 object
- rhs- right-hand side object
- excludeFields- 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 either- lhsor- rhs(but not both) is- null
- ClassCastException- if- rhsis not assignment-compatible with- lhs
- Since:
- 2.2
 
- 
reflectionCompareCompares 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 object
- rhs- right-hand side object
- excludeFields- 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 either- lhsor- rhs(but not both) is- null
- ClassCastException- if- rhsis not assignment-compatible with- lhs
- Since:
- 2.2
 
- 
appendAppends to thebuilderthe comparison of twobooleanss.- Parameters:
- lhs- left-hand side value
- rhs- right-hand side value
- Returns:
- thisinstance.
 
- 
appendAppends 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 array
- rhs- right-hand side array
- Returns:
- thisinstance.
 
- Check if arrays are the same using 
- 
appendAppends to thebuilderthe comparison of twobytes.- Parameters:
- lhs- left-hand side value
- rhs- right-hand side value
- Returns:
- thisinstance.
 
- 
appendAppends 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 array
- rhs- right-hand side array
- Returns:
- thisinstance.
 
- Check if arrays are the same using 
- 
appendAppends to thebuilderthe comparison of twochars.- Parameters:
- lhs- left-hand side value
- rhs- right-hand side value
- Returns:
- thisinstance.
 
- 
appendAppends 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 array
- rhs- right-hand side array
- Returns:
- thisinstance.
 
- Check if arrays are the same using 
- 
appendAppends 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 value
- rhs- right-hand side value
- Returns:
- thisinstance.
 
- 
appendAppends 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 array
- rhs- right-hand side array
- Returns:
- thisinstance.
 
- Check if arrays are the same using 
- 
appendAppends 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 value
- rhs- right-hand side value
- Returns:
- thisinstance.
 
- 
appendAppends 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 array
- rhs- right-hand side array
- Returns:
- thisinstance.
 
- Check if arrays are the same using 
- 
appendAppends to thebuilderthe comparison of twoints.- Parameters:
- lhs- left-hand side value
- rhs- right-hand side value
- Returns:
- thisinstance.
 
- 
appendAppends 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 array
- rhs- right-hand side array
- Returns:
- thisinstance.
 
- Check if arrays are the same using 
- 
appendAppends to thebuilderthe comparison of twolongs.- Parameters:
- lhs- left-hand side value
- rhs- right-hand side value
- Returns:
- thisinstance.
 
- 
appendAppends 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 array
- rhs- right-hand side array
- Returns:
- thisinstance.
 
- Check if arrays are the same using 
- 
appendAppends 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 object
- rhs- right-hand side object
- Returns:
- thisinstance.
- Throws:
- ClassCastException- if- rhsis not assignment-compatible with- lhs
 
- Check if 
- 
appendAppends 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 object
- rhs- right-hand side object
- comparator-- Comparatorused to compare the objects,- nullmeans treat lhs as- Comparable
- Returns:
- thisinstance.
- Throws:
- ClassCastException- if- rhsis not assignment-compatible with- lhs
- Since:
- 2.0
 
- Check if 
- 
appendAppends 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 array
- rhs- right-hand side array
- Returns:
- thisinstance.
- Throws:
- ClassCastException- if- rhsis not assignment-compatible with- lhs
 
- Check if arrays are the same using 
- 
appendAppends 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 array
- rhs- right-hand side array
- comparator-- Comparatorto use to compare the array elements,- nullmeans to treat- lhselements as- Comparable.
- Returns:
- thisinstance.
- Throws:
- ClassCastException- if- rhsis not assignment-compatible with- lhs
- Since:
- 2.0
 
- Check if arrays are the same using 
- 
appendAppends to thebuilderthe comparison of twoshorts.- Parameters:
- lhs- left-hand side value
- rhs- right-hand side value
- Returns:
- thisinstance.
 
- 
appendAppends 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 array
- rhs- right-hand side array
- Returns:
- thisinstance.
 
- Check if arrays are the same using 
- 
appendSuperAppends to thebuilderthecompareTo(Object)result of the superclass.- Parameters:
- superCompareTo- result of calling- super.compareTo(Object)
- Returns:
- thisinstance.
- Since:
- 2.0
 
- 
buildReturns 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.
- 
toComparisonReturns 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:
 
 
-