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);
}
append
public EqualsBuilder append(Object lhs,
Object rhs)
Test if two Object
s are equal using their
equals
method.
lhs
- the left hand objectrhs
- the right hand object
- 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.
lhs
- the left hand Object[]
rhs
- the right hand Object[]
- EqualsBuilder - used to chain calls.
append
public EqualsBuilder append(boolean lhs,
boolean rhs)
Test if two booleans
s are equal.
lhs
- the left hand boolean
rhs
- the right hand boolean
- 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.
lhs
- the left hand boolean[]
rhs
- the right hand boolean[]
- EqualsBuilder - used to chain calls.
append
public EqualsBuilder append(byte lhs,
byte rhs)
Test if two byte
s are equal.
lhs
- the left hand byte
rhs
- the right hand byte
- 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.
lhs
- the left hand byte[]
rhs
- the right hand byte[]
- EqualsBuilder - used to chain calls.
append
public EqualsBuilder append(char lhs,
char rhs)
Test if two char
s are equal.
lhs
- the left hand char
rhs
- the right hand char
- 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.
lhs
- the left hand char[]
rhs
- the right hand char[]
- EqualsBuilder - used to chain calls.
append
public EqualsBuilder append(double lhs,
double rhs)
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
.
lhs
- the left hand double
rhs
- the right hand double
- 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.
lhs
- the left hand double[]
rhs
- the right hand double[]
- EqualsBuilder - used to chain calls.
append
public EqualsBuilder append(float lhs,
float rhs)
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
.
lhs
- the left hand float
rhs
- the right hand float
- 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.
lhs
- the left hand float[]
rhs
- the right hand float[]
- EqualsBuilder - used to chain calls.
append
public EqualsBuilder append(int lhs,
int rhs)
Test if two int
s are equal.
lhs
- the left hand int
rhs
- the right hand int
- 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.
lhs
- the left hand int[]
rhs
- the right hand int[]
- EqualsBuilder - used to chain calls.
append
public EqualsBuilder append(long lhs,
long rhs)
Test if two long
s are equal.
lhs
- the left hand long
rhs
- the right hand long
- 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.
lhs
- the left hand long[]
rhs
- the right hand long[]
- EqualsBuilder - used to chain calls.
append
public EqualsBuilder append(short lhs,
short rhs)
Test if two short
s are equal.
lhs
- the left hand short
rhs
- the right hand short
- 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.
lhs
- the left hand short[]
rhs
- the right hand short[]
- EqualsBuilder - used to chain calls.
appendSuper
public EqualsBuilder appendSuper(boolean superEquals)
Adds the result of super.equals()
to this builder.
superEquals
- the result of calling super.equals()
- EqualsBuilder - used to chain calls.
isEquals
public boolean isEquals()
Returns true
if the fields that have been checked
are all equal.
reflectionEquals
public static boolean reflectionEquals(Object lhs,
Object rhs)
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.
lhs
- this
objectrhs
- the other object
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
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.
lhs
- this
objectrhs
- the other objecttestTransients
- whether to include transient fields
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
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.
lhs
- this
objectrhs
- the other objecttestTransients
- whether to include transient fieldsreflectUpToClass
- the superclass to reflect up to (inclusive),
may be null
true
if the two Objects have tested equals.
setEquals
protected void setEquals(boolean isEquals)
Sets the isEquals
value.
isEquals
- The value to set.