org.apache.commons.lang3.builder

Class EqualsBuilder

java.lang.Object

org.apache.commons.lang3.builder.EqualsBuilder

All Implemented Interfaces:

Builder<java.lang.Boolean>

public class EqualsBuilder
extends java.lang.Object
implements Builder<java.lang.Boolean>

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 == null) { return false; }
   if (obj == this) { return true; }
   if (obj.getClass() != getClass()) {
     return false;
   }
   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. Non-primitive fields are compared using equals().

A typical invocation for this method would look like:

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

The EqualsExclude annotation can be used to exclude fields from being used by the reflectionEquals methods.

Since:

1.0

Constructor Summary

Constructors

Constructor and Description
EqualsBuilder() Constructor for EqualsBuilder.

Method Summary

Modifier and Type	Method and Description
EqualsBuilder	append(boolean[] lhs, boolean[] rhs) Deep comparison of array of boolean.
EqualsBuilder	append(boolean lhs, boolean rhs) Test if two booleanss are equal.
EqualsBuilder	append(byte[] lhs, byte[] rhs) Deep comparison of array of byte.
EqualsBuilder	append(byte lhs, byte rhs) Test if two bytes are equal.
EqualsBuilder	append(char[] lhs, char[] rhs) Deep comparison of array of char.
EqualsBuilder	append(char lhs, char rhs) Test if two chars are equal.
EqualsBuilder	append(double[] lhs, double[] rhs) Deep comparison of array of double.
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.
EqualsBuilder	append(float lhs, float rhs) Test if two floats are equal by testing that the pattern of bits returned by doubleToLong are equal.
EqualsBuilder	append(int[] lhs, int[] rhs) Deep comparison of array of int.
EqualsBuilder	append(int lhs, int rhs) Test if two ints are equal.
EqualsBuilder	append(long[] lhs, long[] rhs) Deep comparison of array of long.
EqualsBuilder	append(long lhs, long rhs) Test if two long s are equal.
EqualsBuilder	append(java.lang.Object[] lhs, java.lang.Object[] rhs) Performs a deep comparison of two Object arrays.
EqualsBuilder	append(java.lang.Object lhs, java.lang.Object rhs) Test if two Objects are equal using either #reflectionAppend(Object, Object), if object are non primitives (or wrapper of primitives) or if field testRecursive is set to false.
EqualsBuilder	append(short[] lhs, short[] rhs) Deep comparison of array of short.
EqualsBuilder	append(short lhs, short rhs) Test if two shorts are equal.
EqualsBuilder	appendSuper(boolean superEquals) Adds the result of super.equals() to this builder.
java.lang.Boolean	build() Returns true if the fields that have been checked are all equal.
boolean	isEquals() Returns true if the fields that have been checked are all equal.
EqualsBuilder	reflectionAppend(java.lang.Object lhs, java.lang.Object rhs) Tests if two objects by using reflection.
static boolean	reflectionEquals(java.lang.Object lhs, java.lang.Object rhs, boolean testTransients) This method uses reflection to determine if the two Objects are equal.
static boolean	reflectionEquals(java.lang.Object lhs, java.lang.Object rhs, boolean testTransients, java.lang.Class<?> reflectUpToClass, boolean testRecursive, java.lang.String... excludeFields) This method uses reflection to determine if the two Objects are equal.
static boolean	reflectionEquals(java.lang.Object lhs, java.lang.Object rhs, boolean testTransients, java.lang.Class<?> reflectUpToClass, java.lang.String... excludeFields) This method uses reflection to determine if the two Objects are equal.
static boolean	reflectionEquals(java.lang.Object lhs, java.lang.Object rhs, java.util.Collection<java.lang.String> excludeFields) This method uses reflection to determine if the two Objects are equal.
static boolean	reflectionEquals(java.lang.Object lhs, java.lang.Object rhs, java.lang.String... excludeFields) This method uses reflection to determine if the two Objects are equal.
void	reset() Reset the EqualsBuilder so you can use the same object again
EqualsBuilder	setBypassReflectionClasses(java.util.List<java.lang.Class<?>> bypassReflectionClasses) Set Classes whose instances should be compared by calling their equals although being in recursive mode.
EqualsBuilder	setExcludeFields(java.lang.String... excludeFields) Set field names to be excluded by reflection tests.
EqualsBuilder	setReflectUpToClass(java.lang.Class<?> reflectUpToClass) Set the superclass to reflect up to at reflective tests.
EqualsBuilder	setTestRecursive(boolean testRecursive) Set whether to include transient fields when reflectively comparing objects.
EqualsBuilder	setTestTransients(boolean testTransients) Set whether to include transient fields when reflectively comparing objects.

Methods inherited from class java.lang.Object

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

Constructor Detail

EqualsBuilder

public EqualsBuilder()

Constructor for EqualsBuilder.

Starts off assuming that equals is true.

See Also:

Object.equals(Object)

Method Detail

setTestTransients

public EqualsBuilder setTestTransients(boolean testTransients)

Set whether to include transient fields when reflectively comparing objects.

Parameters:

testTransients - whether to test transient fields

Returns:

EqualsBuilder - used to chain calls.

Since:

3.6

setTestRecursive

public EqualsBuilder setTestRecursive(boolean testRecursive)

Set whether to include transient fields when reflectively comparing objects.

Parameters:

testRecursive - whether to do a recursive test

Returns:

EqualsBuilder - used to chain calls.

Since:

3.6

setBypassReflectionClasses

public EqualsBuilder setBypassReflectionClasses(java.util.List<java.lang.Class<?>> bypassReflectionClasses)

Set Classes whose instances should be compared by calling their equals although being in recursive mode. So the fields of theses classes will not be compared recursively by reflection.

Here you should name classes having non-transient fields which are cache fields being set lazily.
Prominent example being String class with its hash code cache field. Due to the importance of the String class, it is included in the default bypasses classes. Usually, if you use your own set of classes here, remember to include String class, too.

Parameters:

bypassReflectionClasses - classes to bypass reflection test

Returns:

EqualsBuilder - used to chain calls.

Since:

3.8

setReflectUpToClass

public EqualsBuilder setReflectUpToClass(java.lang.Class<?> reflectUpToClass)

Set the superclass to reflect up to at reflective tests.

Parameters:

reflectUpToClass - the super class to reflect up to

Returns:

EqualsBuilder - used to chain calls.

Since:

3.6

setExcludeFields

public EqualsBuilder setExcludeFields(java.lang.String... excludeFields)

Set field names to be excluded by reflection tests.

Parameters:

excludeFields - the fields to exclude

Returns:

EqualsBuilder - used to chain calls.

Since:

3.6

reflectionEquals

public static boolean reflectionEquals(java.lang.Object lhs,
                                       java.lang.Object rhs,
                                       java.util.Collection<java.lang.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. Non-primitive fields are compared using equals().

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.

See Also:

EqualsExclude

reflectionEquals

public static boolean reflectionEquals(java.lang.Object lhs,
                                       java.lang.Object rhs,
                                       java.lang.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. Non-primitive fields are compared using equals().

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.

See Also:

EqualsExclude

reflectionEquals

public static boolean reflectionEquals(java.lang.Object lhs,
                                       java.lang.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. Non-primitive fields are compared using equals().

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.

See Also:

EqualsExclude

reflectionEquals

public static boolean reflectionEquals(java.lang.Object lhs,
                                       java.lang.Object rhs,
                                       boolean testTransients,
                                       java.lang.Class<?> reflectUpToClass,
                                       java.lang.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. Non-primitive fields are compared using equals().

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

See Also:

EqualsExclude

reflectionEquals

public static boolean reflectionEquals(java.lang.Object lhs,
                                       java.lang.Object rhs,
                                       boolean testTransients,
                                       java.lang.Class<?> reflectUpToClass,
                                       boolean testRecursive,
                                       java.lang.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. Non-primitive fields are compared using equals().

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.

If the testRecursive parameter is set to true, non primitive (and non primitive wrapper) field types will be compared by EqualsBuilder recursively instead of invoking their equals() method. Leading to a deep reflection equals test.

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

testRecursive - whether to call reflection equals on non primitive fields recursively.

excludeFields - array of field names to exclude from testing

Returns:

true if the two Objects have tested equals.

Since:

3.6

See Also:

EqualsExclude

reflectionAppend

public EqualsBuilder reflectionAppend(java.lang.Object lhs,
                                      java.lang.Object rhs)

Tests if two objects by using reflection.

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. Non-primitive fields are compared using equals().

If the testTransients field 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 in field reflectUpToClass. A null superclass is treated as java.lang.Object.

Field names listed in field excludeFields will be ignored.

If either class of the compared objects is contained in bypassReflectionClasses, both objects are compared by calling the equals method of the left hand object with the right hand object as an argument.

Parameters:

lhs - the left hand object

rhs - the left hand object

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

append

public EqualsBuilder append(java.lang.Object lhs,
                            java.lang.Object rhs)

Test if two Objects are equal using either #reflectionAppend(Object, Object), if object are non primitives (or wrapper of primitives) or if field testRecursive is set to false. Otherwise, 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 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 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(java.lang.Object[] lhs,
                            java.lang.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.

Note that this method does not compare the type of the arrays; it only compares the contents.

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 append(long, long) 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 append(int, int) 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 append(short, short) 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 append(char, char) 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 append(byte, byte) 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 append(double, double) 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 append(float, float) 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 append(boolean, boolean) is used.

Parameters:

lhs - the left hand boolean[]

rhs - the right hand boolean[]

Returns:

EqualsBuilder - used to chain calls.

isEquals

public boolean isEquals()

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

Returns:

boolean

build

public java.lang.Boolean build()

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

Specified by:

build in interface Builder<java.lang.Boolean>

Returns:

true if all of the fields that have been checked are equal, false otherwise.

Since:

3.0

reset

public void reset()

Reset the EqualsBuilder so you can use the same object again

Since:

2.5