Class EqualsBuilder
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 SummaryConstructors
- 
Method SummaryModifier and TypeMethodDescriptionappend(boolean[] lhs, boolean[] rhs) Deep comparison of array ofboolean.append(boolean lhs, boolean rhs) Test if twobooleanss are equal.append(byte[] lhs, byte[] rhs) Deep comparison of array ofbyte.append(byte lhs, byte rhs) Test if twobytes are equal.append(char[] lhs, char[] rhs) Deep comparison of array ofchar.append(char lhs, char rhs) Test if twochars are equal.append(double[] lhs, double[] rhs) Deep comparison of array ofdouble.append(double lhs, double rhs) Test if twodoubles are equal by testing that the pattern of bits returned bydoubleToLongare equal.append(float[] lhs, float[] rhs) Deep comparison of array offloat.append(float lhs, float rhs) Test if twofloats are equal by testing that the pattern of bits returned by doubleToLong are equal.append(int[] lhs, int[] rhs) Deep comparison of array ofint.append(int lhs, int rhs) Test if twoints are equal.append(long[] lhs, long[] rhs) Deep comparison of array oflong.append(long lhs, long rhs) Test if twolongs are equal.append(short[] lhs, short[] rhs) Deep comparison of array ofshort.append(short lhs, short rhs) Test if twoshorts are equal.Performs a deep comparison of twoObjectarrays.Test if twoObjects are equal using either #reflectionAppend(Object, Object), if object are non primitives (or wrapper of primitives) or if fieldtestRecursiveis set tofalse.appendSuper(boolean superEquals) Adds the result ofsuper.equals()to this builder.build()Returnstrueif the fields that have been checked are all equal.booleanisEquals()Returnstrueif the fields that have been checked are all equal.reflectionAppend(Object lhs, Object rhs) Tests if twoobjectsby using reflection.static booleanreflectionEquals(Object lhs, Object rhs, boolean testTransients) This method uses reflection to determine if the twoObjects are equal.static booleanreflectionEquals(Object lhs, Object rhs, boolean testTransients, Class<?> reflectUpToClass, boolean testRecursive, String... excludeFields) This method uses reflection to determine if the twoObjects are equal.static booleanreflectionEquals(Object lhs, Object rhs, boolean testTransients, Class<?> reflectUpToClass, String... excludeFields) This method uses reflection to determine if the twoObjects are equal.static booleanreflectionEquals(Object lhs, Object rhs, String... excludeFields) This method uses reflection to determine if the twoObjects are equal.static booleanreflectionEquals(Object lhs, Object rhs, Collection<String> excludeFields) This method uses reflection to determine if the twoObjects are equal.voidreset()Reset the EqualsBuilder so you can use the same object again.setBypassReflectionClasses(List<Class<?>> bypassReflectionClasses) SetsClasses whose instances should be compared by calling theirequalsalthough being in recursive mode.protected voidsetEquals(boolean isEquals) Sets theisEqualsvalue.setExcludeFields(String... excludeFields) Sets field names to be excluded by reflection tests.setReflectUpToClass(Class<?> reflectUpToClass) Sets the superclass to reflect up to at reflective tests.setTestRecursive(boolean testRecursive) Sets whether to test fields recursively, instead of using their equals method, when reflectively comparing objects.setTestTransients(boolean testTransients) Sets whether to include transient fields when reflectively comparing objects.
- 
Constructor Details- 
EqualsBuilderpublic EqualsBuilder()Constructor for EqualsBuilder.Starts off assuming that equals is true.- See Also:
 
 
- 
- 
Method Details- 
reflectionEqualsThis method uses reflection to determine if the twoObjects are equal.It uses AccessibleObject.setAccessibleto 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 usingequals().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 theObject.Static fields will not be tested. Superclass fields will be included. - Parameters:
- lhs-- thisobject
- rhs- the other object
- testTransients- whether to include transient fields
- Returns:
- trueif the two Objects have tested equals.
- See Also:
 
- 
reflectionEqualspublic static boolean reflectionEquals(Object lhs, Object rhs, boolean testTransients, Class<?> reflectUpToClass, boolean testRecursive, String... excludeFields) This method uses reflection to determine if the twoObjects are equal.It uses AccessibleObject.setAccessibleto 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 usingequals().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 theObject.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 byEqualsBuilderrecursively instead of invoking theirequals()method. Leading to a deep reflection equals test.- Parameters:
- lhs-- thisobject
- 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:
- trueif the two Objects have tested equals.
- Since:
- 3.6
- See Also:
 
- 
reflectionEqualspublic static boolean reflectionEquals(Object lhs, Object rhs, boolean testTransients, Class<?> reflectUpToClass, String... excludeFields) This method uses reflection to determine if the twoObjects are equal.It uses AccessibleObject.setAccessibleto 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 usingequals().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 theObject.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-- thisobject
- 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:
- trueif the two Objects have tested equals.
- Since:
- 2.0
- See Also:
 
- 
reflectionEqualsThis method uses reflection to determine if the twoObjects are equal.It uses AccessibleObject.setAccessibleto 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 usingequals().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-- thisobject
- rhs- the other object
- excludeFields- Collection of String field names to exclude from testing
- Returns:
- trueif the two Objects have tested equals.
- See Also:
 
- 
reflectionEqualsThis method uses reflection to determine if the twoObjects are equal.It uses AccessibleObject.setAccessibleto 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 usingequals().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-- thisobject
- rhs- the other object
- excludeFields- array of field names to exclude from testing
- Returns:
- trueif the two Objects have tested equals.
- See Also:
 
- 
appendTest if twobooleanss are equal.- Parameters:
- lhs- the left-hand side- boolean
- rhs- the right-hand side- boolean
- Returns:
- thisinstance.
 
- 
appendDeep comparison of array ofboolean. Length and all values are compared.The method append(boolean, boolean)is used.- Parameters:
- lhs- the left-hand side- boolean[]
- rhs- the right-hand side- boolean[]
- Returns:
- thisinstance.
 
- 
appendTest if twobytes are equal.- Parameters:
- lhs- the left-hand side- byte
- rhs- the right-hand side- byte
- Returns:
- thisinstance.
 
- 
appendDeep comparison of array ofbyte. Length and all values are compared.The method append(byte, byte)is used.- Parameters:
- lhs- the left-hand side- byte[]
- rhs- the right-hand side- byte[]
- Returns:
- thisinstance.
 
- 
appendTest if twochars are equal.- Parameters:
- lhs- the left-hand side- char
- rhs- the right-hand side- char
- Returns:
- thisinstance.
 
- 
appendDeep comparison of array ofchar. Length and all values are compared.The method append(char, char)is used.- Parameters:
- lhs- the left-hand side- char[]
- rhs- the right-hand side- char[]
- Returns:
- thisinstance.
 
- 
appendTest if twodoubles are equal by testing that the pattern of bits returned bydoubleToLongare equal.This handles NaNs, Infinities, and -0.0.It is compatible with the hash code generated by HashCodeBuilder.- Parameters:
- lhs- the left-hand side- double
- rhs- the right-hand side- double
- Returns:
- thisinstance.
 
- 
appendDeep comparison of array ofdouble. Length and all values are compared.The method append(double, double)is used.- Parameters:
- lhs- the left-hand side- double[]
- rhs- the right-hand side- double[]
- Returns:
- thisinstance.
 
- 
appendTest if twofloats 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 side- float
- rhs- the right-hand side- float
- Returns:
- thisinstance.
 
- 
appendDeep comparison of array offloat. Length and all values are compared.The method append(float, float)is used.- Parameters:
- lhs- the left-hand side- float[]
- rhs- the right-hand side- float[]
- Returns:
- thisinstance.
 
- 
appendTest if twoints are equal.- Parameters:
- lhs- the left-hand side- int
- rhs- the right-hand side- int
- Returns:
- thisinstance.
 
- 
appendDeep comparison of array ofint. Length and all values are compared.The method append(int, int)is used.- Parameters:
- lhs- the left-hand side- int[]
- rhs- the right-hand side- int[]
- Returns:
- thisinstance.
 
- 
appendTest if twolongs are equal.- Parameters:
- lhs- the left-hand side- long
- rhs- the right-hand side- long
- Returns:
- thisinstance.
 
- 
appendDeep comparison of array oflong. Length and all values are compared.The method append(long, long)is used.- Parameters:
- lhs- the left-hand side- long[]
- rhs- the right-hand side- long[]
- Returns:
- thisinstance.
 
- 
appendTest if twoObjects are equal using either #reflectionAppend(Object, Object), if object are non primitives (or wrapper of primitives) or if fieldtestRecursiveis set tofalse. Otherwise, using theirequalsmethod.- Parameters:
- lhs- the left-hand side object
- rhs- the right-hand side object
- Returns:
- thisinstance.
 
- 
appendPerforms a deep comparison of twoObjectarrays.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 side- Object[]
- rhs- the right-hand side- Object[]
- Returns:
- thisinstance.
 
- 
appendTest if twoshorts are equal.- Parameters:
- lhs- the left-hand side- short
- rhs- the right-hand side- short
- Returns:
- thisinstance.
 
- 
appendDeep comparison of array ofshort. Length and all values are compared.The method append(short, short)is used.- Parameters:
- lhs- the left-hand side- short[]
- rhs- the right-hand side- short[]
- Returns:
- thisinstance.
 
- 
appendSuperAdds the result ofsuper.equals()to this builder.- Parameters:
- superEquals- the result of calling- super.equals()
- Returns:
- thisinstance.
- Since:
- 2.0
 
- 
buildReturnstrueif the fields that have been checked are all equal.
- 
isEqualsReturnstrueif the fields that have been checked are all equal.- Returns:
- boolean
 
- 
reflectionAppendTests if twoobjectsby using reflection.It uses AccessibleObject.setAccessibleto 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 usingequals().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 theObject.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 excludeFieldswill 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 side object with the right-hand side object as an argument.- Parameters:
- lhs- the left-hand side object
- rhs- the right-hand side object
- Returns:
- thisinstance.
 
- 
resetReset the EqualsBuilder so you can use the same object again.- Since:
- 2.5
 
- 
setBypassReflectionClassesSetsClasses whose instances should be compared by calling theirequalsalthough being in recursive mode. So the fields of these 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 beingStringclass with its hash code cache field. Due to the importance of theStringclass, it is included in the default bypasses classes. Usually, if you use your own set of classes here, remember to includeStringclass, too.- Parameters:
- bypassReflectionClasses- classes to bypass reflection test
- Returns:
- thisinstance.
- Since:
- 3.8
- See Also:
 
- 
setEqualsSets theisEqualsvalue.- Parameters:
- isEquals- The value to set.
- Since:
- 2.1
 
- 
setExcludeFieldsSets field names to be excluded by reflection tests.- Parameters:
- excludeFields- the fields to exclude
- Returns:
- thisinstance.
- Since:
- 3.6
 
- 
setReflectUpToClassSets the superclass to reflect up to at reflective tests.- Parameters:
- reflectUpToClass- the super class to reflect up to
- Returns:
- thisinstance.
- Since:
- 3.6
 
- 
setTestRecursiveSets whether to test fields recursively, instead of using their equals method, when reflectively comparing objects. String objects, which cache a hash value, are automatically excluded from recursive testing. You may specify other exceptions by callingsetBypassReflectionClasses(List).- Parameters:
- testRecursive- whether to do a recursive test
- Returns:
- thisinstance.
- Since:
- 3.6
- See Also:
 
- 
setTestTransientsSets whether to include transient fields when reflectively comparing objects.- Parameters:
- testTransients- whether to test transient fields
- Returns:
- thisinstance.
- Since:
- 3.6
 
 
-