CompareToBuilder (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3.builder, class: CompareToBuilder

Package org.apache.commons.lang3.builder

# Class CompareToBuilder

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

All Implemented Interfaces:
  `Builder<Integer>`

public class CompareToBuilder extends Object implements Builder<Integer>
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();
       }
     }

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:
  - `Comparable`
  - `Object.equals(Object)`
  - `Object.hashCode()`
  - `EqualsBuilder`
  - `HashCodeBuilder`

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  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(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`
  `append(Object[] lhs, Object[] rhs)`
  Appends to the `builder` the deep comparison of two `Object` arrays.
  `CompareToBuilder`
  `append(Object[] lhs, Object[] rhs, Comparator<?> comparator)`
  Appends to the `builder` the deep comparison of two `Object` arrays.
  `CompareToBuilder`
  `append(Object lhs, Object rhs)`
  Appends to the `builder` the comparison of two `Object`s.
  `CompareToBuilder`
  `append(Object lhs, Object rhs, Comparator<?> comparator)`
  Appends to the `builder` the comparison of two `Object`s.
  `CompareToBuilder`
  `appendSuper(int superCompareTo)`
  Appends to the `builder` the `compareTo(Object)` result of the superclass.
  `Integer`
  `build()`
  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.
  `static int`
  `reflectionCompare(Object lhs, Object rhs)`
  Compares two `Object`s via reflection.
  `static int`
  `reflectionCompare(Object lhs, Object rhs, boolean compareTransients)`
  Compares two `Object`s via reflection.
  `static int`
  `reflectionCompare(Object lhs, Object rhs, boolean compareTransients, Class<?> reflectUpToClass, String... excludeFields)`
  Compares two `Object`s via reflection.
  `static int`
  `reflectionCompare(Object lhs, Object rhs, String... excludeFields)`
  Compares two `Object`s via reflection.
  `static int`
  `reflectionCompare(Object lhs, Object rhs, Collection<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 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

    public static int reflectionCompare(Object lhs, 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 side object
      `rhs` - right-hand side object
    Returns:
      a negative integer, zero, or a positive integer as `lhs` is less than, equal to, or greater than `rhs`
    Throws:
      `NullPointerException` - if either (but not both) parameters are `null`
      `ClassCastException` - if `rhs` is not assignment-compatible with `lhs`

  - ### reflectionCompare

    public static int reflectionCompare(Object lhs, 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 side object
      `rhs` - right-hand side 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:
      `NullPointerException` - if either `lhs` or `rhs` (but not both) is `null`
      `ClassCastException` - if `rhs` is not assignment-compatible with `lhs`

  - ### reflectionCompare

    public static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients, Class<?> reflectUpToClass, 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 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 `lhs` is less than, equal to, or greater than `rhs`
    Throws:
      `NullPointerException` - if either `lhs` or `rhs` (but not both) is `null`
      `ClassCastException` - if `rhs` is not assignment-compatible with `lhs`
    Since:
      2.2 (2.0 as `reflectionCompare(Object, Object, boolean, Class)`)

  - ### reflectionCompare

    public static int reflectionCompare(Object lhs, Object rhs, Collection<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 side object
      `rhs` - right-hand side 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:
      `NullPointerException` - if either `lhs` or `rhs` (but not both) is `null`
      `ClassCastException` - if `rhs` is not assignment-compatible with `lhs`
    Since:
      2.2

  - ### reflectionCompare

    public static int reflectionCompare(Object lhs, Object rhs, 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 side object
      `rhs` - right-hand side 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:
      `NullPointerException` - if either `lhs` or `rhs` (but not both) is `null`
      `ClassCastException` - if `rhs` is not assignment-compatible with `lhs`
    Since:
      2.2

  - ### append

    public CompareToBuilder append(boolean lhs, boolean rhs)
    Appends to the `builder` the comparison of two `booleans`s.
    Parameters:
      `lhs` - left-hand side value
      `rhs` - right-hand side value
    Returns:
      `this` instance.

  - ### 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 side array
      `rhs` - right-hand side array
    Returns:
      `this` instance.

  - ### append

    public CompareToBuilder append(byte lhs, byte rhs)
    Appends to the `builder` the comparison of two `byte`s.
    Parameters:
      `lhs` - left-hand side value
      `rhs` - right-hand side value
    Returns:
      `this` instance.

  - ### 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 side array
      `rhs` - right-hand side array
    Returns:
      `this` instance.

  - ### append

    public CompareToBuilder append(char lhs, char rhs)
    Appends to the `builder` the comparison of two `char`s.
    Parameters:
      `lhs` - left-hand side value
      `rhs` - right-hand side value
    Returns:
      `this` instance.

  - ### 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 side array
      `rhs` - right-hand side array
    Returns:
      `this` instance.

  - ### 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 side value
      `rhs` - right-hand side value
    Returns:
      `this` instance.

  - ### 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 side array
      `rhs` - right-hand side array
    Returns:
      `this` instance.

  - ### 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 side value
      `rhs` - right-hand side value
    Returns:
      `this` instance.

  - ### 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 side array
      `rhs` - right-hand side array
    Returns:
      `this` instance.

  - ### append

    public CompareToBuilder append(int lhs, int rhs)
    Appends to the `builder` the comparison of two `int`s.
    Parameters:
      `lhs` - left-hand side value
      `rhs` - right-hand side value
    Returns:
      `this` instance.

  - ### 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 side array
      `rhs` - right-hand side array
    Returns:
      `this` instance.

  - ### append

    public CompareToBuilder append(long lhs, long rhs)
    Appends to the `builder` the comparison of two `long`s.
    Parameters:
      `lhs` - left-hand side value
      `rhs` - right-hand side value
    Returns:
      `this` instance.

  - ### 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 side array
      `rhs` - right-hand side array
    Returns:
      `this` instance.

  - ### append

    public CompareToBuilder append(Object lhs, 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 side object
      `rhs` - right-hand side object
    Returns:
      `this` instance.
    Throws:
      `ClassCastException` - if `rhs` is not assignment-compatible with `lhs`

  - ### append

    public CompareToBuilder append(Object lhs, Object rhs, 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 side object
      `rhs` - right-hand side object
      `comparator` - `Comparator` used to compare the objects, `null` means treat lhs as `Comparable`
    Returns:
      `this` instance.
    Throws:
      `ClassCastException` - if `rhs` is not assignment-compatible with `lhs`
    Since:
      2.0

  - ### append

    public CompareToBuilder append(Object[] lhs, 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 side array
      `rhs` - right-hand side array
    Returns:
      `this` instance.
    Throws:
      `ClassCastException` - if `rhs` is not assignment-compatible with `lhs`

  - ### append

    public CompareToBuilder append(Object[] lhs, Object[] rhs, 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 side array
      `rhs` - right-hand side array
      `comparator` - `Comparator` to use to compare the array elements, `null` means to treat `lhs` elements as `Comparable`.
    Returns:
      `this` instance.
    Throws:
      `ClassCastException` - if `rhs` is not assignment-compatible with `lhs`
    Since:
      2.0

  - ### append

    public CompareToBuilder append(short lhs, short rhs)
    Appends to the `builder` the comparison of two `short`s.
    Parameters:
      `lhs` - left-hand side value
      `rhs` - right-hand side value
    Returns:
      `this` instance.

  - ### 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 side array
      `rhs` - right-hand side array
    Returns:
      `this` instance.

  - ### 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` instance.
    Since:
      2.0

  - ### build

    public Integer build()
    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.
    Specified by:
      `build` in interface `Builder<Integer>`
    Returns:
      final comparison result as an Integer
    Since:
      3.0
    See Also:
      - `toComparison()`

  - ### 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
    See Also:
      - `build()`