Package org.apache.commons.lang3.builder

## Class CompareToBuilder

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

All Implemented Interfaces:
  `Builder<java.lang.Integer>`

    public class CompareToBuilder
    extends java.lang.Object
    implements Builder<java.lang.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
`CompareToBuilder()` Constructor for CompareToBuilder.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`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​(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` `appendSuper​(int superCompareTo)` Appends to the `builder` the `compareTo(Object)` result of the superclass.
`java.lang.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​(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, java.lang.String... 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.
`static int` `reflectionCompare​(java.lang.Object lhs, java.lang.Object rhs, java.util.Collection<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<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` - 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,
                                        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 (2.0 as `reflectionCompare(Object, Object, boolean, Class)`)

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

#### build

    public java.lang.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<java.lang.Integer>`
Returns:
  final comparison result as an Integer
Since:
  3.0
See Also:
  `toComparison()`