EqualsBuilder (Core Language Utilities (Version 2.4))

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 $

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
EqualsBuilder	append(Object lhs, Object rhs) Test if two `Object`s are equal using their `equals` method.
EqualsBuilder	append(long lhs, long rhs) Test if two `long` s are equal.
EqualsBuilder	append(int lhs, int rhs) Test if two `int`s are equal.
EqualsBuilder	append(short lhs, short rhs) Test if two `short`s are equal.
EqualsBuilder	append(char lhs, char rhs) Test if two `char`s are equal.
EqualsBuilder	append(byte lhs, byte rhs) Test if two `byte`s are equal.
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`.
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`.
EqualsBuilder	append(boolean lhs, boolean rhs) Test if two `booleans`s are equal.
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.
EqualsBuilder	append(long[] lhs, long[] rhs) Deep comparison of array of `long`.
EqualsBuilder	append(int[] lhs, int[] rhs) Deep comparison of array of `int`.
EqualsBuilder	append(short[] lhs, short[] rhs) Deep comparison of array of `short`.
EqualsBuilder	append(char[] lhs, char[] rhs) Deep comparison of array of `char`.
EqualsBuilder	append(byte[] lhs, byte[] rhs) Deep comparison of array of `byte`.
EqualsBuilder	append(double[] lhs, double[] rhs) Deep comparison of array of `double`.
EqualsBuilder	append(float[] lhs, float[] rhs) Deep comparison of array of `float`.
EqualsBuilder	append(boolean[] lhs, boolean[] rhs) Deep comparison of array of `boolean`.
EqualsBuilder	appendSuper(boolean superEquals) Adds the result of `super.equals()` to this builder.
boolean	isEquals() Returns `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`s are equal. It uses `AccessibleObject.setAccessible` to gain access to private fields.
static boolean	reflectionEquals(Object lhs, Object rhs, Collection excludeFields) This method uses reflection to determine if the two `Object`s are equal. It uses `AccessibleObject.setAccessible` to gain access to private fields.
static boolean	reflectionEquals(Object lhs, Object rhs, String[] excludeFields) This method uses reflection to determine if the two `Object`s are equal. It uses `AccessibleObject.setAccessible` to gain access to private fields.
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.
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.
static boolean	reflectionEquals(Object lhs, Object rhs, boolean testTransients, Class reflectUpToClass, String[] excludeFields) This method uses reflection to determine if the two `Object`s are equal. It uses `AccessibleObject.setAccessible` to gain access to private fields.
protected void	setEquals(boolean isEquals) Sets the `isEquals` value.

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