Package org.apache.commons.lang3.builder

Class EqualsBuilder

  • All Implemented Interfaces:
    Builder<java.lang.Boolean>
    public class EqualsBuilder
extends java.lang.Object
implements Builder<java.lang.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 Description
      EqualsBuilder()
      Constructor for EqualsBuilder.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      EqualsBuilder append​(boolean[] lhs, boolean[] rhs)
      Deep comparison of array of boolean.
      EqualsBuilder append​(boolean lhs, boolean rhs)
      Test if two booleanss are equal.
      EqualsBuilder append​(byte[] lhs, byte[] rhs)
      Deep comparison of array of byte.
      EqualsBuilder append​(byte lhs, byte rhs)
      Test if two bytes are equal.
      EqualsBuilder append​(char[] lhs, char[] rhs)
      Deep comparison of array of char.
      EqualsBuilder append​(char lhs, char rhs)
      Test if two chars are equal.
      EqualsBuilder append​(double[] lhs, double[] rhs)
      Deep comparison of array of double.
      EqualsBuilder append​(double lhs, double rhs)
      Test if two doubles 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 floats 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 ints are equal.
      EqualsBuilder append​(long[] lhs, long[] rhs)
      Deep comparison of array of long.
      EqualsBuilder append​(long lhs, long rhs)
      Test if two longs are equal.
      EqualsBuilder append​(short[] lhs, short[] rhs)
      Deep comparison of array of short.
      EqualsBuilder append​(short lhs, short rhs)
      Test if two shorts are equal.
      EqualsBuilder append​(java.lang.Object[] lhs, java.lang.Object[] rhs)
      Performs a deep comparison of two Object arrays.
      EqualsBuilder append​(java.lang.Object lhs, java.lang.Object rhs)
      Test if two Objects are equal using either #reflectionAppend(Object, Object), if object are non primitives (or wrapper of primitives) or if field testRecursive is set to false.
      private void appendArray​(java.lang.Object lhs, java.lang.Object rhs)
      Test if an Object is equal to an array.
      EqualsBuilder appendSuper​(boolean superEquals)
      Adds the result of super.equals() to this builder.
      java.lang.Boolean build()
      Returns true if the fields that have been checked are all equal.
      (package private) static Pair<IDKey,​IDKey> getRegisterPair​(java.lang.Object lhs, java.lang.Object rhs)
      Converters value pair into a register pair.
      (package private) static java.util.Set<Pair<IDKey,​IDKey>> getRegistry()
      Gets the registry of object pairs being traversed by the reflection methods in the current thread.
      boolean isEquals()
      Returns true if the fields that have been checked are all equal.
      (package private) static boolean isRegistered​(java.lang.Object lhs, java.lang.Object rhs)
      Tests whether the registry contains the given object pair.
      EqualsBuilder reflectionAppend​(java.lang.Object lhs, java.lang.Object rhs)
      Tests if two objects by using reflection.
      private void reflectionAppend​(java.lang.Object lhs, java.lang.Object rhs, java.lang.Class<?> clazz)
      Appends the fields and values defined by the given object of the given Class.
      static boolean reflectionEquals​(java.lang.Object lhs, java.lang.Object rhs, boolean testTransients)
      This method uses reflection to determine if the two Objects are equal.
      static boolean reflectionEquals​(java.lang.Object lhs, java.lang.Object rhs, boolean testTransients, java.lang.Class<?> reflectUpToClass, boolean testRecursive, java.lang.String... excludeFields)
      This method uses reflection to determine if the two Objects are equal.
      static boolean reflectionEquals​(java.lang.Object lhs, java.lang.Object rhs, boolean testTransients, java.lang.Class<?> reflectUpToClass, java.lang.String... excludeFields)
      This method uses reflection to determine if the two Objects are equal.
      static boolean reflectionEquals​(java.lang.Object lhs, java.lang.Object rhs, java.lang.String... excludeFields)
      This method uses reflection to determine if the two Objects are equal.
      static boolean reflectionEquals​(java.lang.Object lhs, java.lang.Object rhs, java.util.Collection<java.lang.String> excludeFields)
      This method uses reflection to determine if the two Objects are equal.
      private static void register​(java.lang.Object lhs, java.lang.Object rhs)
      Registers the given object pair.
      void reset()
      Reset the EqualsBuilder so you can use the same object again.
      EqualsBuilder setBypassReflectionClasses​(java.util.List<java.lang.Class<?>> bypassReflectionClasses)
      Sets Classes 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​(java.lang.String... excludeFields)
      Sets field names to be excluded by reflection tests.
      EqualsBuilder setReflectUpToClass​(java.lang.Class<?> reflectUpToClass)
      Sets the superclass to reflect up to at reflective tests.
      EqualsBuilder setTestRecursive​(boolean testRecursive)
      Sets whether to test fields recursively, instead of using their equals method, when reflectively comparing objects.
      EqualsBuilder setTestTransients​(boolean testTransients)
      Sets whether to include transient fields when reflectively comparing objects.
      private static void unregister​(java.lang.Object lhs, java.lang.Object rhs)
      Unregisters the given object pair.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • REGISTRY

        private static final java.lang.ThreadLocal<java.util.Set<Pair<IDKey,​IDKey>>> REGISTRY
        A registry of objects used by reflection methods to detect cyclical object references and avoid infinite loops.
        Since:
        3.0

      • isEquals

        private boolean isEquals
        If the fields tested are equals. The default value is true.

      • testTransients

        private boolean testTransients

      • testRecursive

        private boolean testRecursive

      • bypassReflectionClasses

        private java.util.List<java.lang.Class<?>> bypassReflectionClasses

      • reflectUpToClass

        private java.lang.Class<?> reflectUpToClass

      • excludeFields

        private java.lang.String[] excludeFields

    • Constructor Detail

      • EqualsBuilder

        public EqualsBuilder()
        Constructor for EqualsBuilder.

        Starts off assuming that equals is true.

        See Also:
        Object.equals(Object)

    • Method Detail

      • getRegisterPair

        static Pair<IDKey,​IDKey> getRegisterPair​(java.lang.Object lhs,
                                               java.lang.Object rhs)
        Converters value pair into a register pair.
        Parameters:
        lhs - this object
        rhs - the other object
        Returns:
        the pair

      • getRegistry

        static java.util.Set<Pair<IDKey,​IDKey>> getRegistry()
        Gets the registry of object pairs being traversed by the reflection methods in the current thread.
        Returns:
        Set the registry of objects being traversed
        Since:
        3.0

      • isRegistered

        static boolean isRegistered​(java.lang.Object lhs,
                            java.lang.Object rhs)
        Tests whether the registry contains the given object pair.

        Used by the reflection methods to avoid infinite loops. Objects might be swapped therefore a check is needed if the object pair is registered in given or swapped order.

        Parameters:
        lhs - this object to lookup in registry
        rhs - the other object to lookup on registry
        Returns:
        boolean true if the registry contains the given object.
        Since:
        3.0

      • reflectionEquals

        public static boolean reflectionEquals​(java.lang.Object lhs,
                                       java.lang.Object rhs,
                                       boolean testTransients)
        This method uses reflection to determine if the two Objects 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​(java.lang.Object lhs,
                                       java.lang.Object rhs,
                                       boolean testTransients,
                                       java.lang.Class<?> reflectUpToClass,
                                       boolean testRecursive,
                                       java.lang.String... excludeFields)
        This method uses reflection to determine if the two Objects 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

      • reflectionEquals

        public static boolean reflectionEquals​(java.lang.Object lhs,
                                       java.lang.Object rhs,
                                       boolean testTransients,
                                       java.lang.Class<?> reflectUpToClass,
                                       java.lang.String... excludeFields)
        This method uses reflection to determine if the two Objects 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​(java.lang.Object lhs,
                                       java.lang.Object rhs,
                                       java.util.Collection<java.lang.String> excludeFields)
        This method uses reflection to determine if the two Objects 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​(java.lang.Object lhs,
                                       java.lang.Object rhs,
                                       java.lang.String... excludeFields)
        This method uses reflection to determine if the two Objects 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

      • register

        private static void register​(java.lang.Object lhs,
                             java.lang.Object rhs)
        Registers the given object pair. Used by the reflection methods to avoid infinite loops.
        Parameters:
        lhs - this object to register
        rhs - the other object to register

      • unregister

        private static void unregister​(java.lang.Object lhs,
                               java.lang.Object rhs)
        Unregisters the given object pair.

        Used by the reflection methods to avoid infinite loops.

        Parameters:
        lhs - this object to unregister
        rhs - the other object to unregister
        Since:
        3.0

      • append

        public EqualsBuilder append​(boolean lhs,
                            boolean rhs)
        Test if two booleanss are equal.
        Parameters:
        lhs - the left-hand side boolean
        rhs - the right-hand side boolean
        Returns:
        this instance.

      • 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 side boolean[]
        rhs - the right-hand side boolean[]
        Returns:
        this instance.

      • append

        public EqualsBuilder append​(byte lhs,
                            byte rhs)
        Test if two bytes are equal.
        Parameters:
        lhs - the left-hand side byte
        rhs - the right-hand side byte
        Returns:
        this instance.

      • 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 side byte[]
        rhs - the right-hand side byte[]
        Returns:
        this instance.

      • append

        public EqualsBuilder append​(char lhs,
                            char rhs)
        Test if two chars are equal.
        Parameters:
        lhs - the left-hand side char
        rhs - the right-hand side char
        Returns:
        this instance.

      • 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 side char[]
        rhs - the right-hand side char[]
        Returns:
        this instance.

      • append

        public EqualsBuilder append​(double lhs,
                            double rhs)
        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 side double
        rhs - the right-hand side double
        Returns:
        this instance.

      • 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 side double[]
        rhs - the right-hand side double[]
        Returns:
        this instance.

      • append

        public EqualsBuilder append​(float lhs,
                            float rhs)
        Test if two floats 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:
        this instance.

      • 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 side float[]
        rhs - the right-hand side float[]
        Returns:
        this instance.

      • append

        public EqualsBuilder append​(int lhs,
                            int rhs)
        Test if two ints are equal.
        Parameters:
        lhs - the left-hand side int
        rhs - the right-hand side int
        Returns:
        this instance.

      • 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 side int[]
        rhs - the right-hand side int[]
        Returns:
        this instance.

      • append

        public EqualsBuilder append​(long lhs,
                            long rhs)
        Test if two longs are equal.
        Parameters:
        lhs - the left-hand side long
        rhs - the right-hand side long
        Returns:
        this instance.

      • 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 side long[]
        rhs - the right-hand side long[]
        Returns:
        this instance.

      • append

        public EqualsBuilder append​(java.lang.Object lhs,
                            java.lang.Object rhs)
        Test if two Objects 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 side object
        rhs - the right-hand side object
        Returns:
        this instance.

      • append

        public EqualsBuilder append​(java.lang.Object[] lhs,
                            java.lang.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 side Object[]
        rhs - the right-hand side Object[]
        Returns:
        this instance.

      • append

        public EqualsBuilder append​(short lhs,
                            short rhs)
        Test if two shorts are equal.
        Parameters:
        lhs - the left-hand side short
        rhs - the right-hand side short
        Returns:
        this instance.

      • 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 side short[]
        rhs - the right-hand side short[]
        Returns:
        this instance.

      • appendArray

        private void appendArray​(java.lang.Object lhs,
                         java.lang.Object rhs)
        Test if an Object is equal to an array.
        Parameters:
        lhs - the left-hand side object, an array
        rhs - the right-hand side object

      • 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 instance.
        Since:
        2.0

      • build

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

      • isEquals

        public boolean isEquals()
        Returns true if the fields that have been checked are all equal.
        Returns:
        boolean

      • reflectionAppend

        public EqualsBuilder reflectionAppend​(java.lang.Object lhs,
                                      java.lang.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 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:
        this instance.

      • reflectionAppend

        private void reflectionAppend​(java.lang.Object lhs,
                              java.lang.Object rhs,
                              java.lang.Class<?> clazz)
        Appends the fields and values defined by the given object of the given Class.
        Parameters:
        lhs - the left-hand side object
        rhs - the right-hand side object
        clazz - the class to append details of

      • reset

        public void reset()
        Reset the EqualsBuilder so you can use the same object again.
        Since:
        2.5

      • setBypassReflectionClasses

        public EqualsBuilder setBypassReflectionClasses​(java.util.List<java.lang.Class<?>> bypassReflectionClasses)
        Sets Classes whose instances should be compared by calling their equals although 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 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 instance.
        Since:
        3.8
        See Also:
        setTestRecursive(boolean)

      • setEquals

        protected void setEquals​(boolean isEquals)
        Sets the isEquals value.
        Parameters:
        isEquals - The value to set.
        Since:
        2.1

      • setExcludeFields

        public EqualsBuilder setExcludeFields​(java.lang.String... excludeFields)
        Sets field names to be excluded by reflection tests.
        Parameters:
        excludeFields - the fields to exclude
        Returns:
        this instance.
        Since:
        3.6

      • setReflectUpToClass

        public EqualsBuilder setReflectUpToClass​(java.lang.Class<?> reflectUpToClass)
        Sets the superclass to reflect up to at reflective tests.
        Parameters:
        reflectUpToClass - the super class to reflect up to
        Returns:
        this instance.
        Since:
        3.6

      • setTestRecursive

        public EqualsBuilder setTestRecursive​(boolean testRecursive)
        Sets 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 instance.
        Since:
        3.6
        See Also:
        setBypassReflectionClasses(List)

      • setTestTransients

        public EqualsBuilder setTestTransients​(boolean testTransients)
        Sets whether to include transient fields when reflectively comparing objects.
        Parameters:
        testTransients - whether to test transient fields
        Returns:
        this instance.
        Since:
        3.6