org.apache.commons.lang.builder
Class CompareToBuilder

java.lang.Object
  |
  +--org.apache.commons.lang.builder.CompareToBuilder

public class CompareToBuilder

extends Object

CompareTo generation routines.

This class provides methods to build a good compareTo() method for any class. It is consistent with the equals and hashcode built with EqualsBuilder and HashCodeBuilder.

Two object that compare equal using equals should compare equals using compareTo.

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 and equals.

Typical use for the code is as follows:

  public int comapareTo(Object o) {
    MyClass rhs = (MyClass) o;
    return new CompareToBuilder()
                 .append(field1, rhs.field1)
                 .append(field2, rhs.field2)
                 .appendb(field3, rhs.field3)
                 .toComparison();
  }
 

Alternatively, there is a method that uses reflection to determine the fields to test. Because these fields are usually private, the method, reflectionCompare, uses Field.setAccessible to change the visibility of the fields. This will fail under a security manager, unless the appropriate permissions are set. It is also slower than testing explicitly.

A typical invocation for this method would look like:

 public int compareTo(Object o) {
   return CompareToBuilder.reflectionCompare(this, obj);
 }
 

Version:

$Id: CompareToBuilder.java,v 1.4 2002/09/28 10:44:51 scolebourne Exp $

Author:

Steve Downey, Stephen Colebourne

Field Summary

private int

comparison If the fields tested are equals.

Constructor Summary

CompareToBuilder()
Constructor for CompareToBuilder.

Method Summary

CompareToBuilder	append(boolean[] lhs, boolean[] rhs) Deep comparison of array of boolean Length and all values are compared.
CompareToBuilder	append(boolean lhs, boolean rhs) Test if two booleanss are <, > or ==.
CompareToBuilder	append(byte[] lhs, byte[] rhs) Deep comparison of array of byte Length and all values are compared.
CompareToBuilder	append(byte lhs, byte rhs) Test if two bytes are <, > or ==.
CompareToBuilder	append(char[] lhs, char[] rhs) Deep comparison of array of char Length and all values are compared.
CompareToBuilder	append(char lhs, char rhs) Test if two chars are <, > or ==.
CompareToBuilder	append(double[] lhs, double[] rhs) Deep comparison of array of double Length and all values are compared.
CompareToBuilder	append(double lhs, double rhs) Test if two doubles are <, > or ==.
CompareToBuilder	append(float[] lhs, float[] rhs) Deep comparison of array of float Length and all values are compared.
CompareToBuilder	append(float lhs, float rhs) Test if two doubles are <, > or ==.
CompareToBuilder	append(int[] lhs, int[] rhs) Deep comparison of array of int Length and all values are compared.
CompareToBuilder	append(int lhs, int rhs) Test if two ints are <, > or ==.
CompareToBuilder	append(long[] lhs, long[] rhs) Deep comparison of array of long Length and all values are compared.
CompareToBuilder	append(long lhs, long rhs) Test if two longs are <, > or ==.
CompareToBuilder	append(Object[] lhs, Object[] rhs) Performs a deep comparison of two object arrays.
CompareToBuilder	append(Object lhs, Object rhs) Test if two Objects are equal using either the compareTo method, or native comparison if the Objects are actually arrays.
CompareToBuilder	append(short[] lhs, short[] rhs) Deep comparison of array of short Length and all values are compared.
CompareToBuilder	append(short lhs, short rhs) Test if two shorts are <, > or ==.
static int	reflectionCompare(Object lhs, Object rhs) This method uses reflection to determine the ordering between two objects.
static int	reflectionCompare(Object lhs, Object rhs, boolean testTransients) This method uses reflection to determine if the two object are equal.
int	toComparison() Return a negative integer if the object is less than, a positive integer if the object is greater than, or 0 if the object is equal.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

comparison

private int comparison

If the fields tested are equals.

Constructor Detail

CompareToBuilder

public CompareToBuilder()

Constructor for CompareToBuilder. Starts off assuming that the objects are equal.

See Also:

Object.Object()

Method Detail

reflectionCompare

public static int reflectionCompare(Object lhs,
                                    Object rhs)

This method uses reflection to determine the ordering between two objects.

It uses Field.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manger, if the permissions are not set up. It is also not as efficient as testing explicitly. Transient members will be not be tested, as they are likely derived fields, and not part of the value of the object. Static fields will not be tested.

Parameters:

lhs - Left Hand Side

rhs - Right Hand Side

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Throws:

NullPointerException - if either (but not both) parameter is null

ClassCastException - if the specified object's type prevents it from being compared to this Object.

reflectionCompare

public static int reflectionCompare(Object lhs,
                                    Object rhs,
                                    boolean testTransients)

This method uses reflection to determine if the two object are equal.

It uses Field.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manger, if the permissions are not set up. It is also not as efficient as testing explicitly. If the TestTransients parameter is set to true, transient members will be tested, otherwise they are ignored, as they are likely derived fields, and not part of the value of the object. Static fields will not be tested.

Parameters:

lhs - Left Hand Side

rhs - Right Hand Side

testTransients - whether to include transient fields

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Throws:

NullPointerException - if either (but not both) parameter is null

ClassCastException - if the specified object's type prevents it from being compared to this Object.

append

public CompareToBuilder append(Object lhs,
                               Object rhs)

Test if two Objects are equal using either the compareTo method, or native comparison if the Objects are actually arrays.

The objects must be Comparable. If they are not, the method will throw a ClassCastException.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

Throws:

NullPointerException - if either (but not both) parameter is null

ClassCastException - if the specified object's type prevents it from being compared to this Object.

append

public CompareToBuilder append(long lhs,
                               long rhs)

Test if two longs are <, > or ==.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

append

public CompareToBuilder append(int lhs,
                               int rhs)

Test if two ints are <, > or ==.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

append

public CompareToBuilder append(short lhs,
                               short rhs)

Test if two shorts are <, > or ==.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

append

public CompareToBuilder append(char lhs,
                               char rhs)

Test if two chars are <, > or ==.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

append

public CompareToBuilder append(byte lhs,
                               byte rhs)

Test if two bytes are <, > or ==.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

append

public CompareToBuilder append(double lhs,
                               double rhs)

Test if two doubles are <, > or ==. This handles NaNs, Infinties, and -0.0. It is compatible with the hash code generated by HashCodeBuilder.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

append

public CompareToBuilder append(float lhs,
                               float rhs)

Test if two doubles are <, > or ==. This handles NaNs, Infinties, and -0.0. It is compatible with the hash code generated by HashCodeBuilder.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

append

public CompareToBuilder append(boolean lhs,
                               boolean rhs)

Test if two booleanss are <, > or ==.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

append

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

Performs a deep comparison of two object arrays. This also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays. If two arrays are of different lengths, and all elements of the shorter array are equal to the elements in the longer array, the longer array is the greater. This is dictionary, or lexical, ordering.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

Throws:

NullPointerException - if either (but not both) parameter is null

ClassCastException - if the specified object's type prevents it from being compared to this Object.

append

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

Deep comparison of array of long Length and all values are compared. The method append(long, long) is used.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

Throws:

NullPointerException - if either (but not both) parameter is null

append

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

Deep comparison of array of int Length and all values are compared. The method append(int, int) is used.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

Throws:

NullPointerException - if either (but not both) parameter is null

append

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

Deep comparison of array of short Length and all values are compared. The method append(short, short) is used.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

Throws:

NullPointerException - if either (but not both) parameter is null

append

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

Deep comparison of array of char Length and all values are compared. The method append(char, char) is used.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

Throws:

NullPointerException - if either (but not both) parameter is null

append

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

Deep comparison of array of byte Length and all values are compared. The method append(byte, byte) is used.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

Throws:

NullPointerException - if either (but not both) parameter is null

append

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

Deep comparison of array of double Length and all values are compared. The method append(double, double) is used.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

Throws:

NullPointerException - if either (but not both) parameter is null

append

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

Deep comparison of array of float Length and all values are compared. The method append(float, float) is used.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

Throws:

NullPointerException - if either (but not both) parameter is null

append

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

Deep comparison of array of boolean Length and all values are compared. The method append(boolean, boolean) is used.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

CompareToBuilder - used to chain calls.

Throws:

NullPointerException - if either (but not both) parameter is null

toComparison

public int toComparison()

Return a negative integer if the object is less than, a positive integer if the object is greater than, or 0 if the object is equal.

Returns:

int - a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.