org.apache.commons.lang.builder

Class EqualsBuilder

public class EqualsBuilder extends Object

Assists in implementing Object#equals(Object) methods.

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 Objects 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 obj) {
   if (obj instanceof MyClass == false) {
     return false;
   }
   if (this == obj) {
     return true;
   }
   MyClass rhs = (MyClass) obj;
   return new EqualsBuilder()
                 .appendSuper(super.equals(obj))
                 .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 AccessibleObject.setAccessible to change the visibility of the fields. This will fail under a security manager, unless the appropriate permissions are set up correctly. It is also slower than testing explicitly.

A typical invocation for this method would look like:

 public boolean equals(Object obj) {
   return EqualsBuilder.reflectionEquals(this, obj);
 }
 

Since: 1.0

Version: $Id: EqualsBuilder.java 437554 2006-08-28 06:21:41Z bayard $

Author: Steve Downey Stephen Colebourne Gary Gregory Pete Gieser Arun Mammen Thomas

Constructor Summary
EqualsBuilder()

Constructor for EqualsBuilder.

Starts off assuming that equals is true.

Method Summary
EqualsBuilderappend(Object lhs, Object rhs)

Test if two Objects are equal using their equals method.

EqualsBuilderappend(long lhs, long rhs)

Test if two long s are equal.

EqualsBuilderappend(int lhs, int rhs)

Test if two ints are equal.

EqualsBuilderappend(short lhs, short rhs)

Test if two shorts are equal.

EqualsBuilderappend(char lhs, char rhs)

Test if two chars are equal.

EqualsBuilderappend(byte lhs, byte rhs)

Test if two bytes are equal.

EqualsBuilderappend(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, Infinities, and -0.0.

It is compatible with the hash code generated by HashCodeBuilder.

EqualsBuilderappend(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, Infinities, and -0.0.

It is compatible with the hash code generated by HashCodeBuilder.

EqualsBuilderappend(boolean lhs, boolean rhs)

Test if two booleanss are equal.

EqualsBuilderappend(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.

EqualsBuilderappend(long[] lhs, long[] rhs)

Deep comparison of array of long.

EqualsBuilderappend(int[] lhs, int[] rhs)

Deep comparison of array of int.

EqualsBuilderappend(short[] lhs, short[] rhs)

Deep comparison of array of short.

EqualsBuilderappend(char[] lhs, char[] rhs)

Deep comparison of array of char.

EqualsBuilderappend(byte[] lhs, byte[] rhs)

Deep comparison of array of byte.

EqualsBuilderappend(double[] lhs, double[] rhs)

Deep comparison of array of double.

EqualsBuilderappend(float[] lhs, float[] rhs)

Deep comparison of array of float.

EqualsBuilderappend(boolean[] lhs, boolean[] rhs)

Deep comparison of array of boolean.

EqualsBuilderappendSuper(boolean superEquals)

Adds the result of super.equals() to this builder.

booleanisEquals()

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

static booleanreflectionEquals(Object lhs, Object rhs)

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

It uses AccessibleObject.setAccessible to gain access to private fields.

static booleanreflectionEquals(Object lhs, Object rhs, Collection excludeFields)

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

It uses AccessibleObject.setAccessible to gain access to private fields.

static booleanreflectionEquals(Object lhs, Object rhs, String[] excludeFields)

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

It uses AccessibleObject.setAccessible to gain access to private fields.

static booleanreflectionEquals(Object lhs, Object rhs, boolean testTransients)

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

It uses AccessibleObject.setAccessible to gain access to private fields.

static booleanreflectionEquals(Object lhs, Object rhs, boolean testTransients, Class reflectUpToClass)

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

It uses AccessibleObject.setAccessible to gain access to private fields.

static booleanreflectionEquals(Object lhs, Object rhs, boolean testTransients, Class reflectUpToClass, String[] excludeFields)

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

It uses AccessibleObject.setAccessible to gain access to private fields.

protected voidsetEquals(boolean isEquals)
Sets the isEquals value.

Constructor Detail

EqualsBuilder

public EqualsBuilder()

Constructor for EqualsBuilder.

Starts off assuming that equals is true.

See Also: Object#equals(Object)

Method Detail

append

public EqualsBuilder append(Object lhs, Object rhs)

Test if two Objects are equal using their equals method.

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

Returns: EqualsBuilder - used to chain calls.

append

public EqualsBuilder append(long lhs, long rhs)

Test if two long s are equal.

Parameters: lhs the left hand long rhs the right hand long

Returns: EqualsBuilder - used to chain calls.

append

public EqualsBuilder append(int lhs, int rhs)

Test if two ints are equal.

Parameters: lhs the left hand int rhs the right hand int

Returns: EqualsBuilder - used to chain calls.

append

public EqualsBuilder append(short lhs, short rhs)

Test if two shorts are equal.

Parameters: lhs the left hand short rhs the right hand short

Returns: EqualsBuilder - used to chain calls.

append

public EqualsBuilder append(char lhs, char rhs)

Test if two chars are equal.

Parameters: lhs the left hand char rhs the right hand char

Returns: EqualsBuilder - used to chain calls.

append

public EqualsBuilder append(byte lhs, byte rhs)

Test if two bytes are equal.

Parameters: lhs the left hand byte rhs the right hand byte

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, Infinities, and -0.0.

It is compatible with the hash code generated by HashCodeBuilder.

Parameters: lhs the left hand double rhs the right hand double

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, Infinities, and -0.0.

It is compatible with the hash code generated by HashCodeBuilder.

Parameters: lhs the left hand float rhs the right hand float

Returns: EqualsBuilder - used to chain calls.

append

public EqualsBuilder append(boolean lhs, boolean rhs)

Test if two booleanss are equal.

Parameters: lhs the left hand boolean rhs the right hand boolean

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 the left hand Object[] rhs the right hand Object[]

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 EqualsBuilder is used.

Parameters: lhs the left hand long[] rhs the right hand long[]

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 EqualsBuilder is used.

Parameters: lhs the left hand int[] rhs the right hand int[]

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 EqualsBuilder is used.

Parameters: lhs the left hand short[] rhs the right hand short[]

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 EqualsBuilder is used.

Parameters: lhs the left hand char[] rhs the right hand char[]

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 EqualsBuilder is used.

Parameters: lhs the left hand byte[] rhs the right hand byte[]

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 EqualsBuilder is used.

Parameters: lhs the left hand double[] rhs the right hand double[]

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 EqualsBuilder is used.

Parameters: lhs the left hand float[] rhs the right hand float[]

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 EqualsBuilder is used.

Parameters: lhs the left hand boolean[] rhs the right hand boolean[]

Returns: EqualsBuilder - used to chain calls.

appendSuper

public EqualsBuilder appendSuper(boolean superEquals)

Adds the result of super.equals() to this builder.

Parameters: superEquals the result of calling super.equals()

Returns: EqualsBuilder - used to chain calls.

Since: 2.0

isEquals

public boolean isEquals()

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

Returns: boolean

reflectionEquals

public static boolean reflectionEquals(Object lhs, Object rhs)

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

It uses AccessibleObject.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. 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. Superclass fields will be included.

Parameters: lhs this object rhs the other object

Returns: true if the two Objects have tested equals.

reflectionEquals

public static boolean reflectionEquals(Object lhs, Object rhs, Collection excludeFields)

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

It uses AccessibleObject.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. 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. Superclass fields will be included.

Parameters: lhs this object rhs the other object excludeFields Collection of String field names to exclude from testing

Returns: true if the two Objects have tested equals.

reflectionEquals

public static boolean reflectionEquals(Object lhs, Object rhs, String[] excludeFields)

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

It uses AccessibleObject.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. 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. Superclass fields will be included.

Parameters: lhs this object rhs the other object excludeFields array of field names to exclude from testing

Returns: true 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 Objects are equal.

It uses AccessibleObject.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. 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. Superclass fields will be included.

Parameters: lhs this object rhs the other object testTransients whether to include transient fields

Returns: true if the two Objects have tested equals.

reflectionEquals

public static boolean reflectionEquals(Object lhs, Object rhs, boolean testTransients, Class reflectUpToClass)

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

It uses AccessibleObject.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. 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 included. Superclass fields will be appended up to and including the specified superclass. A null superclass is treated as java.lang.Object.

Parameters: lhs this object rhs the other object testTransients whether to include transient fields reflectUpToClass the superclass to reflect up to (inclusive), may be null

Returns: true if the two Objects have tested equals.

Since: 2.0

reflectionEquals

public static boolean reflectionEquals(Object lhs, Object rhs, boolean testTransients, Class reflectUpToClass, String[] excludeFields)

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

It uses AccessibleObject.setAccessible to gain access to private fields. This means that it will throw a security exception if run under a security manager, if the permissions are not set up correctly. 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 included. Superclass fields will be appended up to and including the specified superclass. A null superclass is treated as java.lang.Object.

Parameters: lhs this object rhs the other object testTransients whether to include transient fields reflectUpToClass the superclass to reflect up to (inclusive), may be null excludeFields array of field names to exclude from testing

Returns: true if the two Objects have tested equals.

Since: 2.0

setEquals

protected void setEquals(boolean isEquals)
Sets the isEquals value.

Parameters: isEquals The value to set.

Since: 2.1

Copyright © 2001-2005 - Apache Software Foundation