CompareToBuilder (Lang 2.6)
Date: 2018-05-07

org.apache.commons.lang.builder

## Class CompareToBuilder

- java.lang.Object
- - org.apache.commons.lang.builder.CompareToBuilder

-     public class CompareToBuilder
      extends java.lang.Object

  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 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);
       }

  Since:
    1.0
  Version:
    $Id: CompareToBuilder.java 1056843 2011-01-09 00:29:01Z niallp $
  See Also:
    `Comparable`, `Object.equals(Object)`, `Object.hashCode()`, `EqualsBuilder`, `HashCodeBuilder`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CompareToBuilder()` Constructor for CompareToBuilder.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `CompareToBuilder` | `append(boolean[] lhs, boolean[] rhs)` Appends to the `builder` the deep comparison of two `boolean` arrays.
    `CompareToBuilder` | `append(boolean lhs, boolean rhs)` Appends to the `builder` the comparison of two `booleans`s.
    `CompareToBuilder` | `append(byte[] lhs, byte[] rhs)` Appends to the `builder` the deep comparison of two `byte` arrays.
    `CompareToBuilder` | `append(byte lhs, byte rhs)` Appends to the `builder` the comparison of two `byte`s.
    `CompareToBuilder` | `append(char[] lhs, char[] rhs)` Appends to the `builder` the deep comparison of two `char` arrays.
    `CompareToBuilder` | `append(char lhs, char rhs)` Appends to the `builder` the comparison of two `char`s.
    `CompareToBuilder` | `append(double[] lhs, double[] rhs)` Appends to the `builder` the deep comparison of two `double` arrays.
    `CompareToBuilder` | `append(double lhs, double rhs)` Appends to the `builder` the comparison of two `double`s.
    `CompareToBuilder` | `append(float[] lhs, float[] rhs)` Appends to the `builder` the deep comparison of two `float` arrays.
    `CompareToBuilder` | `append(float lhs, float rhs)` Appends to the `builder` the comparison of two `float`s.
    `CompareToBuilder` | `append(int[] lhs, int[] rhs)` Appends to the `builder` the deep comparison of two `int` arrays.
    `CompareToBuilder` | `append(int lhs, int rhs)` Appends to the `builder` the comparison of two `int`s.
    `CompareToBuilder` | `append(long[] lhs, long[] rhs)` Appends to the `builder` the deep comparison of two `long` arrays.
    `CompareToBuilder` | `append(long lhs, long rhs)` Appends to the `builder` the comparison of two `long`s.
    `CompareToBuilder` | `append(java.lang.Object[] lhs, java.lang.Object[] rhs)` Appends to the `builder` the deep comparison of two `Object` arrays.
    `CompareToBuilder` | `append(java.lang.Object[] lhs, java.lang.Object[] rhs, java.util.Comparator comparator)` Appends to the `builder` the deep comparison of two `Object` arrays.
    `CompareToBuilder` | `append(java.lang.Object lhs, java.lang.Object rhs)` Appends to the `builder` the comparison of two `Object`s.
    `CompareToBuilder` | `append(java.lang.Object lhs, java.lang.Object rhs, java.util.Comparator comparator)` Appends to the `builder` the comparison of two `Object`s.
    `CompareToBuilder` | `append(short[] lhs, short[] rhs)` Appends to the `builder` the deep comparison of two `short` arrays.
    `CompareToBuilder` | `append(short lhs, short rhs)` Appends to the `builder` the comparison of two `short`s.
    `CompareToBuilder` | `appendSuper(int superCompareTo)` Appends to the `builder` the `compareTo(Object)` result of the superclass.
    `static int` | `reflectionCompare(java.lang.Object lhs, java.lang.Object rhs)` Compares two `Object`s via reflection.
    `static int` | `reflectionCompare(java.lang.Object lhs, java.lang.Object rhs, boolean compareTransients)` Compares two `Object`s via reflection.
    `static int` | `reflectionCompare(java.lang.Object lhs, java.lang.Object rhs, boolean compareTransients, java.lang.Class reflectUpToClass)` Compares two `Object`s via reflection.
    `static int` | `reflectionCompare(java.lang.Object lhs, java.lang.Object rhs, boolean compareTransients, java.lang.Class reflectUpToClass, java.lang.String[] excludeFields)` Compares two `Object`s via reflection.
    `static int` | `reflectionCompare(java.lang.Object lhs, java.lang.Object rhs, java.util.Collection excludeFields)` Compares two `Object`s via reflection.
    `static int` | `reflectionCompare(java.lang.Object lhs, java.lang.Object rhs, java.lang.String[] excludeFields)` Compares two `Object`s via reflection.
    `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.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### 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 Detail

    - #### reflectionCompare

          public static int reflectionCompare(java.lang.Object lhs,
                              java.lang.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.

      Parameters:
        `lhs` - left-hand object
        `rhs` - right-hand object
      Returns:
        a negative integer, zero, or a positive integer as `lhs` is less than, equal to, or greater than `rhs`
      Throws:
        `java.lang.NullPointerException` - if either (but not both) parameters are `null`
        `java.lang.ClassCastException` - if `rhs` is not assignment-compatible with `lhs`

    - #### reflectionCompare

          public static int reflectionCompare(java.lang.Object lhs,
                              java.lang.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.

      Parameters:
        `lhs` - left-hand object
        `rhs` - right-hand object
        `compareTransients` - whether to compare transient fields
      Returns:
        a negative integer, zero, or a positive integer as `lhs` is less than, equal to, or greater than `rhs`
      Throws:
        `java.lang.NullPointerException` - if either `lhs` or `rhs` (but not both) is `null`
        `java.lang.ClassCastException` - if `rhs` is not assignment-compatible with `lhs`

    - #### reflectionCompare

          public static int reflectionCompare(java.lang.Object lhs,
                              java.lang.Object rhs,
                              java.util.Collection excludeFields)

      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.

      Parameters:
        `lhs` - left-hand object
        `rhs` - right-hand object
        `excludeFields` - Collection of String fields to exclude
      Returns:
        a negative integer, zero, or a positive integer as `lhs` is less than, equal to, or greater than `rhs`
      Throws:
        `java.lang.NullPointerException` - if either `lhs` or `rhs` (but not both) is `null`
        `java.lang.ClassCastException` - if `rhs` is not assignment-compatible with `lhs`
      Since:
        2.2

    - #### reflectionCompare

          public static int reflectionCompare(java.lang.Object lhs,
                              java.lang.Object rhs,
                              java.lang.String[] excludeFields)

      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.

      Parameters:
        `lhs` - left-hand object
        `rhs` - right-hand object
        `excludeFields` - array of fields to exclude
      Returns:
        a negative integer, zero, or a positive integer as `lhs` is less than, equal to, or greater than `rhs`
      Throws:
        `java.lang.NullPointerException` - if either `lhs` or `rhs` (but not both) is `null`
        `java.lang.ClassCastException` - if `rhs` is not assignment-compatible with `lhs`
      Since:
        2.2

    - #### reflectionCompare

          public static int reflectionCompare(java.lang.Object lhs,
                              java.lang.Object rhs,
                              boolean compareTransients,
                              java.lang.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.

      Parameters:
        `lhs` - left-hand object
        `rhs` - right-hand object
        `compareTransients` - whether to compare transient fields
        `reflectUpToClass` - last superclass for which fields are compared
      Returns:
        a negative integer, zero, or a positive integer as `lhs` is less than, equal to, or greater than `rhs`
      Throws:
        `java.lang.NullPointerException` - if either `lhs` or `rhs` (but not both) is `null`
        `java.lang.ClassCastException` - if `rhs` is not assignment-compatible with `lhs`
      Since:
        2.0

    - #### reflectionCompare

          public static int reflectionCompare(java.lang.Object lhs,
                              java.lang.Object rhs,
                              boolean compareTransients,
                              java.lang.Class reflectUpToClass,
                              java.lang.String[] excludeFields)

      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.

      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
      Returns:
        a negative integer, zero, or a positive integer as `lhs` is less than, equal to, or greater than `rhs`
      Throws:
        `java.lang.NullPointerException` - if either `lhs` or `rhs` (but not both) is `null`
        `java.lang.ClassCastException` - if `rhs` is not assignment-compatible with `lhs`
      Since:
        2.2

    - #### appendSuper

          public CompareToBuilder appendSuper(int superCompareTo)

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

      Parameters:
        `superCompareTo` - result of calling `super.compareTo(Object)`
      Returns:
        this - used to chain append calls
      Since:
        2.0

    - #### append

          public CompareToBuilder append(java.lang.Object lhs,
                                java.lang.Object rhs)

      Appends to the `builder` the comparison of two `Object`s.

      1. Check if `lhs == rhs`
      2. Check if either `lhs` or `rhs` is `null`, a `null` object is less than a non-`null` object
      3. Check the object contents

      `lhs` must either be an array or implement `Comparable`.

      Parameters:
        `lhs` - left-hand object
        `rhs` - right-hand object
      Returns:
        this - used to chain append calls
      Throws:
        `java.lang.ClassCastException` - if `rhs` is not assignment-compatible with `lhs`

    - #### append

          public CompareToBuilder append(java.lang.Object lhs,
                                java.lang.Object rhs,
                                java.util.Comparator comparator)

      Appends to the `builder` the comparison of two `Object`s.

      1. Check if `lhs == rhs`
      2. Check if either `lhs` or `rhs` is `null`, a `null` object is less than a non-`null` object
      3. 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.

      Parameters:
        `lhs` - left-hand object
        `rhs` - right-hand object
        `comparator` - `Comparator` used to compare the objects, `null` means treat lhs as `Comparable`
      Returns:
        this - used to chain append calls
      Throws:
        `java.lang.ClassCastException` - if `rhs` is not assignment-compatible with `lhs`
      Since:
        2.0

    - #### append

          public CompareToBuilder append(long lhs,
                                long rhs)

      Appends to the `builder` the comparison of two `long`s.
      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append(int lhs,
                                int rhs)

      Appends to the `builder` the comparison of two `int`s.
      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append(short lhs,
                                short rhs)

      Appends to the `builder` the comparison of two `short`s.
      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append(char lhs,
                                char rhs)

      Appends to the `builder` the comparison of two `char`s.
      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append(byte lhs,
                                byte rhs)

      Appends to the `builder` the comparison of two `byte`s.
      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        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`.

      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        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`.

      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append(boolean lhs,
                                boolean rhs)

      Appends to the `builder` the comparison of two `booleans`s.
      Parameters:
        `lhs` - left-hand value
        `rhs` - right-hand value
      Returns:
        this - used to chain append calls

    - #### append

          public CompareToBuilder append(java.lang.Object[] lhs,
                                java.lang.Object[] rhs)

      Appends to the `builder` the deep comparison of two `Object` arrays.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a short length array is less than a long length array
      4. 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 array
        `rhs` - right-hand array
      Returns:
        this - used to chain append calls
      Throws:
        `java.lang.ClassCastException` - if `rhs` is not assignment-compatible with `lhs`

    - #### append

          public CompareToBuilder append(java.lang.Object[] lhs,
                                java.lang.Object[] rhs,
                                java.util.Comparator comparator)

      Appends to the `builder` the deep comparison of two `Object` arrays.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a short length array is less than a long length array
      4. 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 array
        `rhs` - right-hand array
        `comparator` - `Comparator` to use to compare the array elements, `null` means to treat `lhs` elements as `Comparable`.
      Returns:
        this - used to chain append calls
      Throws:
        `java.lang.ClassCastException` - if `rhs` is not assignment-compatible with `lhs`
      Since:
        2.0

    - #### append

          public CompareToBuilder append(long[] lhs,
                                long[] rhs)

      Appends to the `builder` the deep comparison of two `long` arrays.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(long, long)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        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.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(int, int)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        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.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(short, short)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        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.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(char, char)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        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.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(byte, byte)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        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.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(double, double)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        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.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(float, float)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        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.

      1. Check if arrays are the same using `==`
      2. Check if for `null`, `null` is less than non-`null`
      3. Check array length, a shorter length array is less than a longer length array
      4. Check array contents element by element using `append(boolean, boolean)`
      Parameters:
        `lhs` - left-hand array
        `rhs` - right-hand array
      Returns:
        this - used to chain append calls

    - #### 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.
      Returns:
        final comparison result

Copyright © 2001-2018 - Apache Software Foundation