Package 

Class CompareToBuilder

  • All Implemented Interfaces:
    external.org.apache.commons.lang3.builder.Builder 
    
public class CompareToBuilder
 implements Builder<Integer>

    Assists in implementing compareTo 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 are reflectionCompare methods that use reflection to determine the fields to append. Because fields can be private, reflectionCompare uses setAccessible 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);
}

    • Constructor Detail

      • CompareToBuilder

        CompareToBuilder()
        Constructor for CompareToBuilder.

    • Method Detail

      • reflectionCompare

         static int reflectionCompare(Object lhs, Object rhs)

        Compares two Objects 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 derivedfields
        • Superclass fields will be compared

        If both lhs and rhs are null,they are considered equal.

        Parameters:
        lhs - left-hand object
        rhs - right-hand object

      • reflectionCompare

         static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients)

        Compares two Objects 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 compareTransients is true,compares transient members. Otherwise ignores them, as theyare likely derived fields.
        • Superclass fields will be compared

        If both lhs and rhs are null,they are considered equal.

        Parameters:
        lhs - left-hand object
        rhs - right-hand object
        compareTransients - whether to compare transient fields

      • reflectionCompare

         static int reflectionCompare(Object lhs, Object rhs, Collection<String> excludeFields)

        Compares two Objects 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 compareTransients is true,compares transient members. Otherwise ignores them, as theyare likely derived fields.
        • Superclass fields will be compared

        If both lhs and rhs are null,they are considered equal.

        Parameters:
        lhs - left-hand object
        rhs - right-hand object
        excludeFields - Collection of String fields to exclude

      • reflectionCompare

         static int reflectionCompare(Object lhs, Object rhs, Array<String> excludeFields)

        Compares two Objects 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 compareTransients is true,compares transient members. Otherwise ignores them, as theyare likely derived fields.
        • Superclass fields will be compared

        If both lhs and rhs are null,they are considered equal.

        Parameters:
        lhs - left-hand object
        rhs - right-hand object
        excludeFields - array of fields to exclude

      • reflectionCompare

         static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients, Class<out Object> reflectUpToClass, Array<String> excludeFields)

        Compares two Objects 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 compareTransients is true,compares transient members. Otherwise ignores them, as theyare 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.

        Parameters:
        lhs - left-hand object
        rhs - right-hand object
        compareTransients - whether to compare transient fields
        reflectUpToClass - last superclass for which fields are compared
        excludeFields - fields to exclude

      • appendSuper

         CompareToBuilder appendSuper(int superCompareTo)

        Appends to the builder the compareTo(Object)result of the superclass.

        Parameters:
        superCompareTo - result of calling super.compareTo(Object)

      • append

         CompareToBuilder append(Object lhs, Object rhs)

        Appends to the builder the comparison oftwo 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.

        Parameters:
        lhs - left-hand object
        rhs - right-hand object

      • append

         CompareToBuilder append(Object lhs, Object rhs, Comparator<out Object> comparator)

        Appends to the builder the comparison oftwo 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 mustimplement Comparable instead.

        Parameters:
        lhs - left-hand object
        rhs - right-hand object
        comparator - Comparator used to compare the objects,null means treat lhs as Comparable

      • append

         CompareToBuilder append(long lhs, long rhs)

        Appends to the builder the comparison oftwo longs.

        Parameters:
        lhs - left-hand value
        rhs - right-hand value

      • append

         CompareToBuilder append(int lhs, int rhs)

        Appends to the builder the comparison oftwo ints.

        Parameters:
        lhs - left-hand value
        rhs - right-hand value

      • append

         CompareToBuilder append(short lhs, short rhs)

        Appends to the builder the comparison oftwo shorts.

        Parameters:
        lhs - left-hand value
        rhs - right-hand value

      • append

         CompareToBuilder append(char lhs, char rhs)

        Appends to the builder the comparison oftwo chars.

        Parameters:
        lhs - left-hand value
        rhs - right-hand value

      • append

         CompareToBuilder append(byte lhs, byte rhs)

        Appends to the builder the comparison oftwo bytes.

        Parameters:
        lhs - left-hand value
        rhs - right-hand value

      • append

         CompareToBuilder append(double lhs, double rhs)

        Appends to the builder the comparison oftwo doubles.

        This handles NaNs, Infinities, and -0.0.

        It is compatible with the hash code generated byHashCodeBuilder.

        Parameters:
        lhs - left-hand value
        rhs - right-hand value

      • append

         CompareToBuilder append(float lhs, float rhs)

        Appends to the builder the comparison oftwo floats.

        This handles NaNs, Infinities, and -0.0.

        It is compatible with the hash code generated byHashCodeBuilder.

        Parameters:
        lhs - left-hand value
        rhs - right-hand value

      • append

         CompareToBuilder append(boolean lhs, boolean rhs)

        Appends to the builder the comparison oftwo booleanss.

        Parameters:
        lhs - left-hand value
        rhs - right-hand value

      • append

         CompareToBuilder append(Array<Object> lhs, Array<Object> rhs)

        Appends to the builder the deep comparison oftwo 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

        This method will also will be called for the top level of multi-dimensional,ragged, and multi-typed arrays.

        Parameters:
        lhs - left-hand array
        rhs - right-hand array

      • append

         CompareToBuilder append(Array<Object> lhs, Array<Object> rhs, Comparator<out Object> comparator)

        Appends to the builder the deep comparison oftwo 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

        This method will also will be called for the top level of multi-dimensional,ragged, and multi-typed arrays.

        Parameters:
        lhs - left-hand array
        rhs - right-hand array
        comparator - Comparator to use to compare the array elements,null means to treat lhs elements as Comparable.

      • append

         CompareToBuilder append(Array<long> lhs, Array<long> rhs)

        Appends to the builder the deep comparison oftwo 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
        Parameters:
        lhs - left-hand array
        rhs - right-hand array

      • append

         CompareToBuilder append(Array<int> lhs, Array<int> rhs)

        Appends to the builder the deep comparison oftwo 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
        Parameters:
        lhs - left-hand array
        rhs - right-hand array

      • append

         CompareToBuilder append(Array<short> lhs, Array<short> rhs)

        Appends to the builder the deep comparison oftwo 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
        Parameters:
        lhs - left-hand array
        rhs - right-hand array

      • append

         CompareToBuilder append(Array<char> lhs, Array<char> rhs)

        Appends to the builder the deep comparison oftwo 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
        Parameters:
        lhs - left-hand array
        rhs - right-hand array

      • append

         CompareToBuilder append(Array<byte> lhs, Array<byte> rhs)

        Appends to the builder the deep comparison oftwo 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
        Parameters:
        lhs - left-hand array
        rhs - right-hand array

      • append

         CompareToBuilder append(Array<double> lhs, Array<double> rhs)

        Appends to the builder the deep comparison oftwo 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
        Parameters:
        lhs - left-hand array
        rhs - right-hand array

      • append

         CompareToBuilder append(Array<float> lhs, Array<float> rhs)

        Appends to the builder the deep comparison oftwo 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
        Parameters:
        lhs - left-hand array
        rhs - right-hand array

      • append

         CompareToBuilder append(Array<boolean> lhs, Array<boolean> rhs)

        Appends to the builder the deep comparison oftwo 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
        Parameters:
        lhs - left-hand array
        rhs - right-hand array

      • toComparison

         int toComparison()

        Returns a negative integer, a positive integer, or zero asthe builder has judged the "left-hand" sideas less than, greater than, or equal to the "right-hand"side.

      • build

         Integer build()

        Returns a negative Integer, a positive Integer, or zero asthe builder has judged the "left-hand" sideas less than, greater than, or equal to the "right-hand"side.