org.apache.commons.lang.builder

Class CompareToBuilder

public class CompareToBuilder extends Object

Assists in implementing {@link java.lang.Comparable#compareTo(Object)} methods. It is consistent with equals(Object) and hashcode() built with {@link EqualsBuilder} and {@link HashCodeBuilder}.

Two Objects that compare equal using equals(Object) should normally also compare equal using compareTo(Object).

All relevant fields should be included in the calculation of the comparison. Derived fields may be ignored. The same fields, in the same order, should be used in both compareTo(Object) and equals(Object).

To use this class write code as follows:

 public class MyClass {
   String field1;
   int field2;
   boolean field3;

   ...

   public int compareTo(Object o) {
     MyClass myClass = (MyClass) o;
     return new CompareToBuilder()
       .appendSuper(super.compareTo(o)
       .append(this.field1, myClass.field1)
       .append(this.field2, myClass.field2)
       .append(this.field3, myClass.field3)
       .toComparison();
   }
 }
 

Alternatively, there is are {@link #reflectionCompare reflectionCompare} method that uses reflection to determine the fields to append. Because fields can be private, reflectionCompare uses {@link 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);
 }
 

Since: 1.0

Version: $Id: CompareToBuilder.java 161243 2005-04-14 04:30:28Z ggregory $

Author: Steve Downey Stephen Colebourne Gary Gregory Pete Gieser

See Also: java.lang.Comparable java.lang.Object#equals(Object) java.lang.Object#hashCode() EqualsBuilder HashCodeBuilder

Constructor Summary
CompareToBuilder()

Constructor for CompareToBuilder.

Starts off assuming that the objects are equal.

Method Summary
CompareToBuilderappend(Object lhs, 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 {@link Comparable}.

CompareToBuilderappend(Object lhs, Object rhs, 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.

CompareToBuilderappend(long lhs, long rhs)
Appends to the builder the comparison of two longs.
CompareToBuilderappend(int lhs, int rhs)
Appends to the builder the comparison of two ints.
CompareToBuilderappend(short lhs, short rhs)
Appends to the builder the comparison of two shorts.
CompareToBuilderappend(char lhs, char rhs)
Appends to the builder the comparison of two chars.
CompareToBuilderappend(byte lhs, byte rhs)
Appends to the builder the comparison of two bytes.
CompareToBuilderappend(double lhs, 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.

CompareToBuilderappend(float lhs, 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.

CompareToBuilderappend(boolean lhs, boolean rhs)
Appends to the builder the comparison of two booleanss.
CompareToBuilderappend(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 {@link #append(Object, Object, Comparator)}

This method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays.

CompareToBuilderappend(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 {@link #append(Object, Object, Comparator)}

This method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays.

CompareToBuilderappend(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 {@link #append(long, long)}
CompareToBuilderappend(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 {@link #append(int, int)}
CompareToBuilderappend(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 {@link #append(short, short)}
CompareToBuilderappend(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 {@link #append(char, char)}
CompareToBuilderappend(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 {@link #append(byte, byte)}
CompareToBuilderappend(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 {@link #append(double, double)}
CompareToBuilderappend(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 {@link #append(float, float)}
CompareToBuilderappend(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 {@link #append(boolean, boolean)}
CompareToBuilderappendSuper(int superCompareTo)

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

static intreflectionCompare(Object lhs, Object rhs)

Compares two Objects via reflection.

Fields can be private, thus AccessibleObject.setAccessible is used to bypass normal access control checks.

static intreflectionCompare(Object lhs, Object rhs, boolean compareTransients)

Compares two Objects via reflection.

Fields can be private, thus AccessibleObject.setAccessible is used to bypass normal access control checks.

static intreflectionCompare(Object lhs, Object rhs, boolean compareTransients, Class reflectUpToClass)

Compares two Objects via reflection.

Fields can be private, thus AccessibleObject.setAccessible is used to bypass normal access control checks.

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

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 {@link #toComparison} to get the result.

Method Detail

append

public CompareToBuilder append(Object lhs, 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 {@link Comparable}.

Parameters: lhs left-hand object rhs right-hand object

Returns: this - used to chain append calls

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 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 {@link 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: 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 longs.

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 ints.

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 shorts.

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 chars.

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 bytes.

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 doubles.

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 floats.

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 booleanss.

Parameters: lhs left-hand value rhs right-hand value

Returns: this - used to chain append calls

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 {@link #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: 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 {@link #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: 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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #append(boolean, boolean)}

Parameters: lhs left-hand array rhs right-hand array

Returns: this - used to chain append calls

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

reflectionCompare

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

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

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

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.

If both lhs and rhs are null, they are considered equal.

Parameters: lhs left-hand object rhs right-hand object compareTransients whether to compare transient fields reflectUpToClass last superclass for which fields are compared

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

Throws: NullPointerException if either lhs or rhs (but not both) is null ClassCastException if rhs is not assignment-compatible with lhs

Since: 2.0

toComparison

public int toComparison()
Returns a negative integer, a positive integer, or zero as the builder has judged the "left-hand" side as less than, greater than, or equal to the "right-hand" side.

Returns: final comparison result

Copyright © 2001-2005 - Apache Software Foundation