Top Description Fields Constructors Methods
org.apache.commons.lang3.builder

public Class CompareToBuilder

extends Object
implements Builder<Integer>
Class Inheritance
All Implemented Interfaces
org.apache.commons.lang3.builder.Builder
Imports
java.lang.reflect.AccessibleObject, .Field, .Modifier, java.util.Collection, .Comparator, .Objects, org.apache.commons.lang3.ArrayUtils, .ObjectUtils
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).

Since
1.0
See Also
Comparable, Object#equals(Object), Object#hashCode(), EqualsBuilder, HashCodeBuilder

Field Summary

Modifier and TypeField and Description
private int
comparison

Current state of the comparison as appended fields are checked.

Constructor Summary

AccessConstructor and Description
public
CompareToBuilder()

Constructor for CompareToBuilder.

Method Summary

Modifier and TypeMethod and Description
public CompareToBuilder

Returns:

this instance.
append(final boolean
left-hand side value
lhs, final boolean
right-hand side value
rhs)

Appends to the builder the comparison of two booleanss.

public CompareToBuilder

Returns:

this instance.
append(final boolean[]
left-hand side array
lhs, final boolean[]
right-hand side array
rhs)

Appends to the builder the deep comparison of two boolean arrays.

public CompareToBuilder

Returns:

this instance.
append(final byte
left-hand side value
lhs, final byte
right-hand side value
rhs)

Appends to the builder the comparison of two bytes.

public CompareToBuilder

Returns:

this instance.
append(final byte[]
left-hand side array
lhs, final byte[]
right-hand side array
rhs)

Appends to the builder the deep comparison of two byte arrays.

public CompareToBuilder

Returns:

this instance.
append(final char
left-hand side value
lhs, final char
right-hand side value
rhs)

Appends to the builder the comparison of two chars.

public CompareToBuilder

Returns:

this instance.
append(final char[]
left-hand side array
lhs, final char[]
right-hand side array
rhs)

Appends to the builder the deep comparison of two char arrays.

public CompareToBuilder

Returns:

this instance.
append(final double
left-hand side value
lhs, final double
right-hand side value
rhs)

Appends to the builder the comparison of two doubles.

public CompareToBuilder

Returns:

this instance.
append(final double[]
left-hand side array
lhs, final double[]
right-hand side array
rhs)

Appends to the builder the deep comparison of two double arrays.

public CompareToBuilder

Returns:

this instance.
append(final float
left-hand side value
lhs, final float
right-hand side value
rhs)

Appends to the builder the comparison of two floats.

public CompareToBuilder

Returns:

this instance.
append(final float[]
left-hand side array
lhs, final float[]
right-hand side array
rhs)

Appends to the builder the deep comparison of two float arrays.

public CompareToBuilder

Returns:

this instance.
append(final int
left-hand side value
lhs, final int
right-hand side value
rhs)

Appends to the builder the comparison of two ints.

public CompareToBuilder

Returns:

this instance.
append(final int[]
left-hand side array
lhs, final int[]
right-hand side array
rhs)

Appends to the builder the deep comparison of two int arrays.

public CompareToBuilder

Returns:

this instance.
append(final long
left-hand side value
lhs, final long
right-hand side value
rhs)

Appends to the builder the comparison of two longs.

public CompareToBuilder

Returns:

this instance.
append(final long[]
left-hand side array
lhs, final long[]
right-hand side array
rhs)

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

public CompareToBuilder

Returns:

this instance.
append(final Object
left-hand side object
lhs, final Object
right-hand side object
rhs)

Appends to the builder the comparison of two Objects.

public CompareToBuilder

Returns:

this instance.
append(final Object
left-hand side object
lhs, final Object
right-hand side object
rhs, final Comparator<?>
Comparator used to compare the objects, null means treat lhs as Comparable
comparator)

Appends to the builder the comparison of two Objects.

public CompareToBuilder

Returns:

this instance.
append(final Object[]
left-hand side array
lhs, final Object[]
right-hand side array
rhs)

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

public CompareToBuilder

Returns:

this instance.
append(final Object[]
left-hand side array
lhs, final Object[]
right-hand side array
rhs, final Comparator<?>
Comparator to use to compare the array elements, null means to treat lhs elements as Comparable.
comparator)

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

public CompareToBuilder

Returns:

this instance.
append(final short
left-hand side value
lhs, final short
right-hand side value
rhs)

Appends to the builder the comparison of two shorts.

public CompareToBuilder

Returns:

this instance.
append(final short[]
left-hand side array
lhs, final short[]
right-hand side array
rhs)

Appends to the builder the deep comparison of two short arrays.

private void
appendArray(final Object lhs, final Object rhs, final Comparator<?> comparator)

public CompareToBuilder

Returns:

this instance.
appendSuper(final int
result of calling super.compareTo(Object)
superCompareTo)

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

public Integer

Returns:

final comparison result as an Integer
build()

Implements org.apache.commons.lang3.builder.Builder.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.

private static void
reflectionAppend(final Object
left-hand side object
lhs, final Object
right-hand side object
rhs, final Class<?>
Class that defines fields to be compared
clazz, final CompareToBuilder
CompareToBuilder to append to
builder, final boolean
whether to compare transient fields
useTransients, final String[]
fields to exclude
excludeFields)

Appends to builder the comparison of lhs to rhs using the fields defined in clazz.

public static int

Returns:

a negative integer, zero, or a positive integer as lhs is less than, equal to, or greater than rhs
reflectionCompare(final Object
left-hand side object
lhs, final Object
right-hand side object
rhs)

Compares two Objects via reflection.

public static int

Returns:

a negative integer, zero, or a positive integer as lhs is less than, equal to, or greater than rhs
reflectionCompare(final Object
left-hand side object
lhs, final Object
right-hand side object
rhs, final boolean
whether to compare transient fields
compareTransients)

Compares two Objects via reflection.

public static int

Returns:

a negative integer, zero, or a positive integer as lhs is less than, equal to, or greater than rhs
reflectionCompare(final Object
left-hand side object
lhs, final Object
right-hand side object
rhs, final boolean
whether to compare transient fields
compareTransients, final Class<?>
last superclass for which fields are compared
reflectUpToClass, final String...
fields to exclude
excludeFields)

Compares two Objects via reflection.

public static int

Returns:

a negative integer, zero, or a positive integer as lhs is less than, equal to, or greater than rhs
reflectionCompare(final Object
left-hand side object
lhs, final Object
right-hand side object
rhs, final Collection<String>
Collection of String fields to exclude
excludeFields)

Compares two Objects via reflection.

public static int

Returns:

a negative integer, zero, or a positive integer as lhs is less than, equal to, or greater than rhs
reflectionCompare(final Object
left-hand side object
lhs, final Object
right-hand side object
rhs, final String...
array of fields to exclude
excludeFields)

Compares two Objects via reflection.

public int

Returns:

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

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

comparisonback to summary
private int comparison

Current state of the comparison as appended fields are checked.

Constructor Detail

CompareToBuilderback to summary
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

appendback to summary
public CompareToBuilder append(final boolean lhs, final boolean rhs)

Appends to the builder the comparison of two booleanss.

Parameters
lhs:boolean

left-hand side value

rhs:boolean

right-hand side value

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final boolean[] lhs, final 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:boolean[]

left-hand side array

rhs:boolean[]

right-hand side array

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final byte lhs, final byte rhs)

Appends to the builder the comparison of two bytes.

Parameters
lhs:byte

left-hand side value

rhs:byte

right-hand side value

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final byte[] lhs, final 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:byte[]

left-hand side array

rhs:byte[]

right-hand side array

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final char lhs, final char rhs)

Appends to the builder the comparison of two chars.

Parameters
lhs:char

left-hand side value

rhs:char

right-hand side value

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final char[] lhs, final 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:char[]

left-hand side array

rhs:char[]

right-hand side array

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final double lhs, final double rhs)

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:double

left-hand side value

rhs:double

right-hand side value

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final double[] lhs, final 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:double[]

left-hand side array

rhs:double[]

right-hand side array

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final float lhs, final float rhs)

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:float

left-hand side value

rhs:float

right-hand side value

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final float[] lhs, final 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:float[]

left-hand side array

rhs:float[]

right-hand side array

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final int lhs, final int rhs)

Appends to the builder the comparison of two ints.

Parameters
lhs:int

left-hand side value

rhs:int

right-hand side value

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final int[] lhs, final 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:int[]

left-hand side array

rhs:int[]

right-hand side array

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final long lhs, final long rhs)

Appends to the builder the comparison of two longs.

Parameters
lhs:long

left-hand side value

rhs:long

right-hand side value

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final long[] lhs, final 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:long[]

left-hand side array

rhs:long[]

right-hand side array

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final Object lhs, final Object rhs)

Appends to the builder the comparison of two Objects.

  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:Object

left-hand side object

rhs:Object

right-hand side object

Returns:CompareToBuilder

this instance.

Exceptions
ClassCastException:
if rhs is not assignment-compatible with lhs
appendback to summary
public CompareToBuilder append(final Object lhs, final Object rhs, final Comparator<?> comparator)

Appends to the builder the comparison of two Objects.

  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:Object

left-hand side object

rhs:Object

right-hand side object

comparator:Comparator<?>

Comparator used to compare the objects, null means treat lhs as Comparable

Returns:CompareToBuilder

this instance.

Exceptions
ClassCastException:
if rhs is not assignment-compatible with lhs
Since
2.0
appendback to summary
public CompareToBuilder append(final Object[] lhs, final 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:Object[]

left-hand side array

rhs:Object[]

right-hand side array

Returns:CompareToBuilder

this instance.

Exceptions
ClassCastException:
if rhs is not assignment-compatible with lhs
appendback to summary
public CompareToBuilder append(final Object[] lhs, final Object[] rhs, final 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:Object[]

left-hand side array

rhs:Object[]

right-hand side array

comparator:Comparator<?>

Comparator to use to compare the array elements, null means to treat lhs elements as Comparable.

Returns:CompareToBuilder

this instance.

Exceptions
ClassCastException:
if rhs is not assignment-compatible with lhs
Since
2.0
appendback to summary
public CompareToBuilder append(final short lhs, final short rhs)

Appends to the builder the comparison of two shorts.

Parameters
lhs:short

left-hand side value

rhs:short

right-hand side value

Returns:CompareToBuilder

this instance.

appendback to summary
public CompareToBuilder append(final short[] lhs, final 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:short[]

left-hand side array

rhs:short[]

right-hand side array

Returns:CompareToBuilder

this instance.

appendArrayback to summary
private void appendArray(final Object lhs, final Object rhs, final Comparator<?> comparator)
appendSuperback to summary
public CompareToBuilder appendSuper(final int superCompareTo)

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

Parameters
superCompareTo:int

result of calling super.compareTo(Object)

Returns:CompareToBuilder

this instance.

Since
2.0
buildback to summary
public Integer build()

Implements org.apache.commons.lang3.builder.Builder.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.

Returns:Integer

final comparison result as an Integer

Annotations
@Override
Since
3.0
See Also
toComparison()
reflectionAppendback to summary
private static void reflectionAppend(final Object lhs, final Object rhs, final Class<?> clazz, final CompareToBuilder builder, final boolean useTransients, final String[] excludeFields)

Appends to builder the comparison of lhs to rhs using the fields defined in clazz.

Parameters
lhs:Object

left-hand side object

rhs:Object

right-hand side object

clazz:Class<?>

Class that defines fields to be compared

builder:CompareToBuilder

CompareToBuilder to append to

useTransients:boolean

whether to compare transient fields

excludeFields:String[]

fields to exclude

reflectionCompareback to summary
public static int reflectionCompare(final Object lhs, final Object rhs)

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:Object

left-hand side object

rhs:Object

right-hand side object

Returns:int

a negative integer, zero, or a positive integer as lhs is less than, equal to, or greater than rhs

Exceptions
NullPointerException:
if either (but not both) parameters are null
ClassCastException:
if rhs is not assignment-compatible with lhs
reflectionCompareback to summary
public static int reflectionCompare(final Object lhs, final Object rhs, final boolean compareTransients)

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:Object

left-hand side object

rhs:Object

right-hand side object

compareTransients:boolean

whether to compare transient fields

Returns:int

a negative integer, zero, or a positive integer as lhs is less than, equal to, or greater than rhs

Exceptions
NullPointerException:
if either lhs or rhs (but not both) is null
ClassCastException:
if rhs is not assignment-compatible with lhs
reflectionCompareback to summary
public static int reflectionCompare(final Object lhs, final Object rhs, final boolean compareTransients, final Class<?> reflectUpToClass, final String... excludeFields)

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:Object

left-hand side object

rhs:Object

right-hand side object

compareTransients:boolean

whether to compare transient fields

reflectUpToClass:Class<?>

last superclass for which fields are compared

excludeFields:String[]

fields to exclude

Returns:int

a negative integer, zero, or a positive integer as lhs is less than, equal to, or greater than rhs

Exceptions
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))
reflectionCompareback to summary
public static int reflectionCompare(final Object lhs, final Object rhs, final Collection<String> excludeFields)

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:Object

left-hand side object

rhs:Object

right-hand side object

excludeFields:Collection<String>

Collection of String fields to exclude

Returns:int

a negative integer, zero, or a positive integer as lhs is less than, equal to, or greater than rhs

Exceptions
NullPointerException:
if either lhs or rhs (but not both) is null
ClassCastException:
if rhs is not assignment-compatible with lhs
Since
2.2
reflectionCompareback to summary
public static int reflectionCompare(final Object lhs, final Object rhs, final String... excludeFields)

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:Object

left-hand side object

rhs:Object

right-hand side object

excludeFields:String[]

array of fields to exclude

Returns:int

a negative integer, zero, or a positive integer as lhs is less than, equal to, or greater than rhs

Exceptions
NullPointerException:
if either lhs or rhs (but not both) is null
ClassCastException:
if rhs is not assignment-compatible with lhs
Since
2.2
toComparisonback to summary
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:int

final comparison result

See Also
build()