CompareToBuilder¶

public class org.apache.commons.lang3.builder.CompareToBuilder extends AbstractReflection implements Builder<Integer>[source]¶

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 java.lang.reflect.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).

See also:

Since:

1.0

Constructors¶

CompareToBuilder()

Constructor for CompareToBuilder.

public CompareToBuilder()[source]¶

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.

Methods¶

`append(boolean, boolean)`	Appends to the `builder` the comparison of two `booleans`s.
`append(boolean[], boolean[])`	Appends to the `builder` the deep comparison of two `boolean` arrays.
`append(byte, byte)`	Appends to the `builder` the comparison of two `byte`s.
`append(byte[], byte[])`	Appends to the `builder` the deep comparison of two `byte` arrays.
`append(char, char)`	Appends to the `builder` the comparison of two `char`s.
`append(char[], char[])`	Appends to the `builder` the deep comparison of two `char` arrays.
`append(double, double)`	Appends to the `builder` the comparison of two `double`s.
`append(double[], double[])`	Appends to the `builder` the deep comparison of two `double` arrays.
`append(float, float)`	Appends to the `builder` the comparison of two `float`s.
`append(float[], float[])`	Appends to the `builder` the deep comparison of two `float` arrays.
`append(int, int)`	Appends to the `builder` the comparison of two `int`s.
`append(int[], int[])`	Appends to the `builder` the deep comparison of two `int` arrays.
`append(Object, Object)`	Appends to the `builder` the comparison of two `Object`s.
`append(Object, Object, Comparator)`	Appends to the `builder` the comparison of two `Object`s.
`append(Object[], Object[])`	Appends to the `builder` the deep comparison of two `Object` arrays.
`append(Object[], Object[], Comparator)`	Appends to the `builder` the deep comparison of two `Object` arrays.
`append(long, long)`	Appends to the `builder` the comparison of two `long`s.
`append(long[], long[])`	Appends to the `builder` the deep comparison of two `long` arrays.
`append(short, short)`	Appends to the `builder` the comparison of two `short`s.
`append(short[], short[])`	Appends to the `builder` the deep comparison of two `short` arrays.
`appendSuper(int)`	Appends to the `builder` the `compareTo(Object)` result of the superclass.
`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.
`builder()`	Constructs a new Builder.
`reflectionCompare(Object, Object)`	Compares two `Object`s via reflection.
`reflectionCompare(Object, Object, boolean)`	Compares two `Object`s via reflection.
`reflectionCompare(Object, Object, boolean, Class, String[])`	Compares two `Object`s via reflection.
`reflectionCompare(Object, Object, String[])`	Compares two `Object`s via reflection.
`reflectionCompare(Object, Object, Collection)`	Compares two `Object`s via reflection.
`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.

public CompareToBuilder append(boolean lhs, boolean rhs)[source]¶

Appends to the builder the comparison of two booleanss.

Parameters:

lhs – left-hand side value.
rhs – right-hand side value.

Returns:

this instance.

public CompareToBuilder append(boolean[] lhs, boolean[] rhs)[source]¶

Appends to the builder the deep comparison of two 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(boolean, boolean)

Parameters:

lhs – left-hand side array.
rhs – right-hand side array.

Returns:

this instance.

public CompareToBuilder append(byte lhs, byte rhs)[source]¶

Appends to the builder the comparison of two bytes.

Parameters:

lhs – left-hand side value.
rhs – right-hand side value.

Returns:

this instance.

public CompareToBuilder append(byte[] lhs, byte[] rhs)[source]¶

Appends to the builder the deep comparison of two 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(byte, byte)

Parameters:

lhs – left-hand side array.
rhs – right-hand side array.

Returns:

this instance.

public CompareToBuilder append(char lhs, char rhs)[source]¶

Appends to the builder the comparison of two chars.

Parameters:

lhs – left-hand side value.
rhs – right-hand side value.

Returns:

this instance.

public CompareToBuilder append(char[] lhs, char[] rhs)[source]¶

Appends to the builder the deep comparison of two 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(char, char)

Parameters:

lhs – left-hand side array.
rhs – right-hand side array.

Returns:

this instance.

public CompareToBuilder append(double lhs, double rhs)[source]¶

Appends to the builder the comparison of two doubles.

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.

public CompareToBuilder append(double[] lhs, double[] rhs)[source]¶

Appends to the builder the deep comparison of two 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(double, double)

Parameters:

lhs – left-hand side array.
rhs – right-hand side array.

Returns:

this instance.

public CompareToBuilder append(float lhs, float rhs)[source]¶

Appends to the builder the comparison of two floats.

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.

public CompareToBuilder append(float[] lhs, float[] rhs)[source]¶

Appends to the builder the deep comparison of two 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(float, float)

Parameters:

lhs – left-hand side array.
rhs – right-hand side array.

Returns:

this instance.

public CompareToBuilder append(int lhs, int rhs)[source]¶

Appends to the builder the comparison of two ints.

Parameters:

lhs – left-hand side value.
rhs – right-hand side value.

Returns:

this instance.

public CompareToBuilder append(int[] lhs, int[] rhs)[source]¶

Appends to the builder the deep comparison of two 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(int, int)

Parameters:

lhs – left-hand side array.
rhs – right-hand side array.

Returns:

this instance.

public CompareToBuilder append(Object lhs, Object rhs)[source]¶

Appends to the builder the comparison of two 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 side object.
rhs – right-hand side object.

Returns:

this instance.

Throws:

java.lang.ClassCastException – Thrown if rhs is not assignment-compatible with lhs.

public CompareToBuilder append(Object lhs, Object rhs, Comparator<?> comparator)[source]¶

Appends to the builder the comparison of two 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 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:

java.lang.ClassCastException – Thrown if rhs is not assignment-compatible with lhs.

Since:

2.0

public CompareToBuilder append(Object[] lhs, Object[] rhs)[source]¶

Appends to the builder the deep comparison of two 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(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:

java.lang.ClassCastException – Thrown if rhs is not assignment-compatible with lhs.

public CompareToBuilder append(Object[] lhs, Object[] rhs, Comparator<?> comparator)[source]¶

Appends to the builder the deep comparison of two 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(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:

java.lang.ClassCastException – Thrown if rhs is not assignment-compatible with lhs.

Since:

2.0

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

Appends to the builder the comparison of two longs.

Parameters:

lhs – left-hand side value.
rhs – right-hand side value.

Returns:

this instance.

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

Appends to the builder the deep comparison of two 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(long, long)

Parameters:

lhs – left-hand side array.
rhs – right-hand side array.

Returns:

this instance.

public CompareToBuilder append(short lhs, short rhs)[source]¶

Appends to the builder the comparison of two shorts.

Parameters:

lhs – left-hand side value.
rhs – right-hand side value.

Returns:

this instance.

public CompareToBuilder append(short[] lhs, short[] rhs)[source]¶

Appends to the builder the deep comparison of two 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(short, short)

Parameters:

lhs – left-hand side array.
rhs – right-hand side array.

Returns:

this instance.

public CompareToBuilder appendSuper(int superCompareTo)[source]¶

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

@Override public Integer build()[source]¶

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 as an Integer.
See also:: #toComparison()
Since:: 3.0

public static CompareToBuilder.Builder builder()[source]¶

Constructs a new Builder.

Returns:: A new Builder.

public static int reflectionCompare(Object lhs, Object rhs)[source]¶

Compares two Objects 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:

java.lang.NullPointerException – Thrown if either (but not both) parameters are null.
java.lang.ClassCastException – Thrown if rhs is not assignment-compatible with lhs.

public static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients)[source]¶

Compares two Objects 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:

java.lang.NullPointerException – Thrown if either lhs or rhs (but not both) is null.
java.lang.ClassCastException – Thrown if rhs is not assignment-compatible with lhs.

public static int reflectionCompare(Object lhs, Object rhs, boolean compareTransients, Class<?> reflectUpToClass, String... excludeFields)[source]¶

Compares two Objects 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:

java.lang.NullPointerException – Thrown if either lhs or rhs (but not both) is null.
java.lang.ClassCastException – Thrown if rhs is not assignment-compatible with lhs.

Since:

2.2 (2.0 as reflectionCompare(Object, Object, boolean, Class)).

public static int reflectionCompare(Object lhs, Object rhs, String... excludeFields)[source]¶

Compares two Objects 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:

java.lang.NullPointerException – Thrown if either lhs or rhs (but not both) is null.
java.lang.ClassCastException – Thrown if rhs is not assignment-compatible with lhs.

Since:

2.2

public static int reflectionCompare(Object lhs, Object rhs, Collection<String> excludeFields)[source]¶

Compares two Objects 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:

java.lang.NullPointerException – Thrown if either lhs or rhs (but not both) is null.
java.lang.ClassCastException – Thrown if rhs is not assignment-compatible with lhs.

Since:

2.2

public int toComparison()[source]¶

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()