org.apache.commons.lang3.builder

## Class EqualsBuilder

- java.lang.Object
- - org.apache.commons.lang3.builder.EqualsBuilder

- All Implemented Interfaces:
    Builder<Boolean>

      public class EqualsBuilder
      extends Object
      implements Builder<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

    All Methods Static Methods Instance Methods Concrete Methods
    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 `booleans`s are equal.
    `EqualsBuilder` | `append(byte[] lhs, byte[] rhs)` Deep comparison of array of `byte`.
    `EqualsBuilder` | `append(byte lhs, byte rhs)` Test if two `byte`s are equal.
    `EqualsBuilder` | `append(char[] lhs, char[] rhs)` Deep comparison of array of `char`.
    `EqualsBuilder` | `append(char lhs, char rhs)` Test if two `char`s are equal.
    `EqualsBuilder` | `append(double[] lhs, double[] rhs)` Deep comparison of array of `double`.
    `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.
    `EqualsBuilder` | `append(float[] lhs, float[] rhs)` Deep comparison of array of `float`.
    `EqualsBuilder` | `append(float lhs, float rhs)` Test if two `float`s 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 `int`s 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(Object[] lhs, Object[] rhs)` Performs a deep comparison of two `Object` arrays.
    `EqualsBuilder` | `append(Object lhs, Object rhs)` Test if two `Object`s 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 `short`s are equal.
    `EqualsBuilder` | `appendSuper(boolean superEquals)` Adds the result of `super.equals()` to this builder.
    `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(Object lhs, Object rhs)` Tests if two `objects` by using reflection.
    `static boolean` | `reflectionEquals(Object lhs, Object rhs, boolean testTransients)` This method uses reflection to determine if the two `Object`s are equal.
    `static boolean` | `reflectionEquals(Object lhs, Object rhs, boolean testTransients, Class<?> reflectUpToClass, boolean testRecursive, String... excludeFields)` This method uses reflection to determine if the two `Object`s are equal.
    `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.
    `static boolean` | `reflectionEquals(Object lhs, Object rhs, Collection<String> excludeFields)` This method uses reflection to determine if the two `Object`s are equal.
    `static boolean` | `reflectionEquals(Object lhs, Object rhs, String... excludeFields)` This method uses reflection to determine if the two `Object`s are equal.
    `void` | `reset()` Reset the EqualsBuilder so you can use the same object again
    `EqualsBuilder` | `setBypassReflectionClasses(List<Class<?>> bypassReflectionClasses)` Set `Class`es whose instances should be compared by calling their `equals` although being in recursive mode.
    `protected void` | `setEquals(boolean isEquals)` Sets the `isEquals` value.
    `EqualsBuilder` | `setExcludeFields(String... excludeFields)` Set field names to be excluded by reflection tests.
    `EqualsBuilder` | `setReflectUpToClass(Class<?> reflectUpToClass)` Set the superclass to reflect up to at reflective tests.
    `EqualsBuilder` | `setTestRecursive(boolean testRecursive)` Set whether to test fields recursively, instead of using their equals method, 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

      `clone, equals, finalize, 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:
        this
      Since:
        3.6

    - #### setTestRecursive

          public EqualsBuilder setTestRecursive(boolean testRecursive)

      Set 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 calling `setBypassReflectionClasses(List)`.
      Parameters:
        `testRecursive` - whether to do a recursive test
      Returns:
        this
      Since:
        3.6
      See Also:
        `setBypassReflectionClasses(List)`

    - #### setBypassReflectionClasses

          public EqualsBuilder setBypassReflectionClasses(List<Class<?>> bypassReflectionClasses)

      Set `Class`es 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:
        this
      Since:
        3.8
      See Also:
        `setTestRecursive(boolean)`

    - #### setReflectUpToClass

          public EqualsBuilder setReflectUpToClass(Class<?> reflectUpToClass)

      Set the superclass to reflect up to at reflective tests.
      Parameters:
        `reflectUpToClass` - the super class to reflect up to
      Returns:
        this
      Since:
        3.6

    - #### setExcludeFields

          public EqualsBuilder setExcludeFields(String... excludeFields)

      Set field names to be excluded by reflection tests.
      Parameters:
        `excludeFields` - the fields to exclude
      Returns:
        this
      Since:
        3.6

    - #### reflectionEquals

          public static boolean reflectionEquals(Object lhs,
                                                 Object rhs,
                                                 Collection<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. 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(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. 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(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. 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(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. 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(Object lhs,
                                                 Object rhs,
                                                 boolean testTransients,
                                                 Class<?> reflectUpToClass,
                                                 boolean testRecursive,
                                                 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. 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(Object lhs,
                                                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 right-hand object
      Returns:
        this

    - #### appendSuper

          public EqualsBuilder appendSuper(boolean superEquals)

      Adds the result of `super.equals()` to this builder.
      Parameters:
        `superEquals` - the result of calling `super.equals()`
      Returns:
        this
      Since:
        2.0

    - #### append

          public EqualsBuilder append(Object lhs,
                                      Object rhs)

      Test if two `Object`s 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:
        this

    - #### 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:
        this

    - #### append

          public EqualsBuilder append(int lhs,
                                      int rhs)

      Test if two `int`s are equal.
      Parameters:
        `lhs` - the left-hand `int`
        `rhs` - the right-hand `int`
      Returns:
        this

    - #### append

          public EqualsBuilder append(short lhs,
                                      short rhs)

      Test if two `short`s are equal.
      Parameters:
        `lhs` - the left-hand `short`
        `rhs` - the right-hand `short`
      Returns:
        this

    - #### append

          public EqualsBuilder append(char lhs,
                                      char rhs)

      Test if two `char`s are equal.
      Parameters:
        `lhs` - the left-hand `char`
        `rhs` - the right-hand `char`
      Returns:
        this

    - #### append

          public EqualsBuilder append(byte lhs,
                                      byte rhs)

      Test if two `byte`s are equal.
      Parameters:
        `lhs` - the left-hand `byte`
        `rhs` - the right-hand `byte`
      Returns:
        this

    - #### 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`.

      Parameters:
        `lhs` - the left-hand `double`
        `rhs` - the right-hand `double`
      Returns:
        this

    - #### append

          public EqualsBuilder append(float lhs,
                                      float rhs)

      Test if two `float`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 `float`
        `rhs` - the right-hand `float`
      Returns:
        this

    - #### append

          public EqualsBuilder append(boolean lhs,
                                      boolean rhs)

      Test if two `booleans`s are equal.
      Parameters:
        `lhs` - the left-hand `boolean`
        `rhs` - the right-hand `boolean`
      Returns:
        this

    - #### 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.

      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:
        this

    - #### 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:
        this

    - #### 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:
        this

    - #### 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:
        this

    - #### 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:
        this

    - #### 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:
        this

    - #### 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:
        this

    - #### 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:
        this

    - #### 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:
        this

    - #### isEquals

          public boolean isEquals()

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

    - #### build

          public Boolean build()

      Returns `true` if the fields that have been checked are all equal.
      Specified by:
        `build` in interface `Builder<Boolean>`
      Returns:
        `true` if all of the fields that have been checked are equal, `false` otherwise.
      Since:
        3.0

    - #### setEquals

          protected void setEquals(boolean isEquals)

      Sets the `isEquals` value.
      Parameters:
        `isEquals` - The value to set.
      Since:
        2.1

    - #### reset

          public void reset()

      Reset the EqualsBuilder so you can use the same object again
      Since:
        2.5

Copyright © 2001–2023 The Apache Software Foundation. All rights reserved.