org.apache.commons.lang.builder
Class EqualsBuilder

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

public class EqualsBuilder

extends Object

Equals generation routines.

This class provides methods to build a good equals method for any class. It follows rules laid out in Effective Java, by Joshua Bloch. In particular the rule for comparing doubles , floats, and arrays can be tricky. Also, making sure that equals() and hashCode() are consistent can be difficult.

Two object that compare as equals must generate the same hash code. But two objects with the same hash code do not have to be equal.

All relevant fields should be included in the calculation of equals. Derived fields may be ignored. In particular, any field used in generating a hash code must be used in the equals method, and vice versa.

Typical use for the code is as follows:

 public boolean equals(Object o) {
   if (!o instanceof MyClass) {
    return false;
   }
  MyClass rhs = (MyClass) o;
  return new EqualsBuilder()
                 .append(field1, rhs.field1)
                 .append(field2, rhs.field2)
                 .append(field3, rhs.field3)
                 .isEquals();
  }
 

Alternatively, there is a method that uses reflection to determine the fields to test. Because these fields are usually private, the method, reflectionEquals, 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 boolean equals(Object o) {
   return EqualsBuilder.reflectionEquals(this, obj);
 }
 

Version:

$Id: EqualsBuilder.java,v 1.4 2002/10/01 20:00:43 stevencaswell Exp $

Author:

Steve Downey, Stephen Colebourne

Field Summary

private boolean

isEquals If the fields tested are equals.

Constructor Summary

EqualsBuilder()
Constructor for EqualsBuilder.

Method Summary

EqualsBuilder	append(boolean[] lhs, boolean[] rhs) Deep comparison of array of boolean Length and all values are compared.
EqualsBuilder	append(boolean lhs, boolean rhs) Test if two booleanss are equal using ==.
EqualsBuilder	append(byte[] lhs, byte[] rhs) Deep comparison of array of byte Length and all values are compared.
EqualsBuilder	append(byte lhs, byte rhs) Test if two bytes are equal using ==.
EqualsBuilder	append(char[] lhs, char[] rhs) Deep comparison of array of char Length and all values are compared.
EqualsBuilder	append(char lhs, char rhs) Test if two chars are equal using ==.
EqualsBuilder	append(double[] lhs, double[] rhs) Deep comparison of array of double Length and all values are compared.
EqualsBuilder	append(double lhs, double rhs) Test if two doubles are equal by testing that the pattern of bits returned by doubleToLong are equal.
EqualsBuilder	append(float[] lhs, float[] rhs) Deep comparison of array of float Length and all values are compared.
EqualsBuilder	append(float lhs, float rhs) Test if two floats are equal byt testing that the pattern of bits returned by doubleToLong are equal.
EqualsBuilder	append(int[] lhs, int[] rhs) Deep comparison of array of int Length and all values are compared.
EqualsBuilder	append(int lhs, int rhs) Test if two ints are equal using ==.
EqualsBuilder	append(long[] lhs, long[] rhs) Deep comparison of array of long Length and all values are compared.
EqualsBuilder	append(long lhs, long rhs) Test if two longs are equal using ==.
EqualsBuilder	append(Object[] lhs, Object[] rhs) Performs a deep comparison of two object arrays.
EqualsBuilder	append(Object lhs, Object rhs) Test if two Objects are equal using their equals method.
EqualsBuilder	append(short[] lhs, short[] rhs) Deep comparison of array of short Length and all values are compared.
EqualsBuilder	append(short lhs, short rhs) Test if two shorts are equal using ==.
boolean	isEquals() Return true if the fields that have been checked are all equal.
static boolean	reflectionEquals(Object lhs, Object rhs) This method uses reflection to determine if the two object are equal.
static boolean	reflectionEquals(Object lhs, Object rhs, boolean testTransients) This method uses reflection to determine if the two object are equal.

Methods inherited from class java.lang.Object

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

Field Detail

isEquals

private boolean isEquals

If the fields tested are equals.

Constructor Detail

EqualsBuilder

public EqualsBuilder()

Constructor for EqualsBuilder. Starts off assuming that equals is true.

See Also:

Object.Object()

Method Detail

reflectionEquals

public static boolean reflectionEquals(Object lhs,
                                       Object rhs)

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

boolean - if the two objects have tested equals.

reflectionEquals

public static boolean reflectionEquals(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:

boolean - if the two objects have tested equals.

append

public EqualsBuilder append(Object lhs,
                            Object rhs)

Test if two Objects are equal using their equals method.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder append(long lhs,
                            long rhs)

Test if two longs are equal using ==.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder append(int lhs,
                            int rhs)

Test if two ints are equal using ==.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder append(short lhs,
                            short rhs)

Test if two shorts are equal using ==.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder append(char lhs,
                            char rhs)

Test if two chars are equal using ==.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder append(byte lhs,
                            byte rhs)

Test if two bytes are equal using ==.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder append(double lhs,
                            double rhs)

Test if two doubles are equal by testing that the pattern of bits returned by doubleToLong are equal. 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:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder append(float lhs,
                            float rhs)

Test if two floats are equal byt testing that the pattern of bits returned by doubleToLong are equal. 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:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder append(boolean lhs,
                            boolean rhs)

Test if two booleanss are equal using ==.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder 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.

Parameters:

lhs - - Left Hand Side

rhs - - Right Hand Side

Returns:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder 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:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder 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:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder 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:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder 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:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder 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:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder 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:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder 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:

EqualsBuilder - used to chain calls.

append

public EqualsBuilder 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:

EqualsBuilder - used to chain calls.

isEquals

public boolean isEquals()

Return true if the fields that have been checked are all equal.

Returns:

boolean