org.apache.commons.lang.builder
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 == 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.
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 611543 2008-01-13 07:00:22Z bayard $
Constructor Summary | |
---|---|
EqualsBuilder() Constructor for EqualsBuilder. Starts off assuming that equals is |
Method Summary | |
---|---|
EqualsBuilder | append(Object lhs, Object rhs) Test if two |
EqualsBuilder | append(long lhs, long rhs)
Test if two |
EqualsBuilder | append(int lhs, int rhs) Test if two |
EqualsBuilder | append(short lhs, short rhs) Test if two |
EqualsBuilder | append(char lhs, char rhs) Test if two |
EqualsBuilder | append(byte lhs, byte rhs) Test if two |
EqualsBuilder | append(double lhs, double rhs) Test if two This handles NaNs, Infinities, and It is compatible with the hash code generated by
|
EqualsBuilder | append(float lhs, float rhs) Test if two This handles NaNs, Infinities, and It is compatible with the hash code generated by
|
EqualsBuilder | append(boolean lhs, boolean rhs) Test if two |
EqualsBuilder | append(Object[] lhs, Object[] rhs) Performs a deep comparison of two This also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays. |
EqualsBuilder | append(long[] lhs, long[] rhs) Deep comparison of array of |
EqualsBuilder | append(int[] lhs, int[] rhs) Deep comparison of array of |
EqualsBuilder | append(short[] lhs, short[] rhs) Deep comparison of array of |
EqualsBuilder | append(char[] lhs, char[] rhs) Deep comparison of array of |
EqualsBuilder | append(byte[] lhs, byte[] rhs) Deep comparison of array of |
EqualsBuilder | append(double[] lhs, double[] rhs) Deep comparison of array of |
EqualsBuilder | append(float[] lhs, float[] rhs) Deep comparison of array of |
EqualsBuilder | append(boolean[] lhs, boolean[] rhs) Deep comparison of array of |
EqualsBuilder | appendSuper(boolean superEquals) Adds the result of |
boolean | isEquals() Returns |
static boolean | reflectionEquals(Object lhs, Object rhs) This method uses reflection to determine if the two It uses |
static boolean | reflectionEquals(Object lhs, Object rhs, Collection excludeFields) This method uses reflection to determine if the two It uses |
static boolean | reflectionEquals(Object lhs, Object rhs, String[] excludeFields) This method uses reflection to determine if the two It uses |
static boolean | reflectionEquals(Object lhs, Object rhs, boolean testTransients) This method uses reflection to determine if the two It uses |
static boolean | reflectionEquals(Object lhs, Object rhs, boolean testTransients, Class reflectUpToClass) This method uses reflection to determine if the two It uses |
static boolean | reflectionEquals(Object lhs, Object rhs, boolean testTransients, Class reflectUpToClass, String[] excludeFields) This method uses reflection to determine if the two It uses |
protected void | setEquals(boolean isEquals)
Sets the isEquals value.
|
Constructor for EqualsBuilder.
Starts off assuming that equals is true
.
See Also: Object#equals(Object)
Test if two Object
s are equal using their
equals
method.
Parameters: lhs the left hand object rhs the right hand object
Returns: EqualsBuilder - used to chain calls.
Test if two long
s are equal.
Parameters: lhs
the left hand long
rhs
the right hand long
Returns: EqualsBuilder - used to chain calls.
Test if two int
s are equal.
Parameters: lhs the left hand int
rhs the right hand int
Returns: EqualsBuilder - used to chain calls.
Test if two short
s are equal.
Parameters: lhs the left hand short
rhs the right hand short
Returns: EqualsBuilder - used to chain calls.
Test if two char
s are equal.
Parameters: lhs the left hand char
rhs the right hand char
Returns: EqualsBuilder - used to chain calls.
Test if two byte
s are equal.
Parameters: lhs the left hand byte
rhs the right hand byte
Returns: EqualsBuilder - used to chain calls.
Test if two double
s 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.
Test if two float
s 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.
Test if two booleans
s are equal.
Parameters: lhs the left hand boolean
rhs the right hand boolean
Returns: EqualsBuilder - used to chain calls.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
Returns true
if the fields that have been checked
are all equal.
Returns: boolean
This method uses reflection to determine if the two Object
s
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.
This method uses reflection to determine if the two Object
s
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.
This method uses reflection to determine if the two Object
s
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.
This method uses reflection to determine if the two Object
s
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.
This method uses reflection to determine if the two Object
s
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
This method uses reflection to determine if the two Object
s
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
isEquals
value.
Parameters: isEquals The value to set.
Since: 2.1