Package 

Class EqualsBuilder

  • All Implemented Interfaces:
    external.org.apache.commons.lang3.builder.Builder 
    
public class EqualsBuilder
 implements Builder<Boolean>

    Assists in implementing equals 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);
}

    • Constructor Detail

      • EqualsBuilder

        EqualsBuilder()
        Constructor for EqualsBuilder.

    • Method Detail

      • isEquals

         boolean isEquals()

        Returns true if the fields that have been checkedare all equal.

      • reflectionEquals

         static boolean reflectionEquals(Object lhs, Object rhs, Collection<String> excludeFields)

        This method uses reflection to determine if the two Objectsare equal.

        It uses AccessibleObject.setAccessible to gain access to privatefields. This means that it will throw a security exception if run undera security manager, if the permissions are not set up correctly. It is alsonot as efficient as testing explicitly.

        Transient members will be not be tested, as they are likely derivedfields, 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

      • reflectionEquals

         static boolean reflectionEquals(Object lhs, Object rhs, Array<String> excludeFields)

        This method uses reflection to determine if the two Objectsare equal.

        It uses AccessibleObject.setAccessible to gain access to privatefields. This means that it will throw a security exception if run undera security manager, if the permissions are not set up correctly. It is alsonot as efficient as testing explicitly.

        Transient members will be not be tested, as they are likely derivedfields, 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

      • reflectionEquals

         static boolean reflectionEquals(Object lhs, Object rhs, boolean testTransients)

        This method uses reflection to determine if the two Objectsare equal.

        It uses AccessibleObject.setAccessible to gain access to privatefields. This means that it will throw a security exception if run undera security manager, if the permissions are not set up correctly. It is alsonot as efficient as testing explicitly.

        If the TestTransients parameter is set to true, transientmembers will be tested, otherwise they are ignored, as they are likelyderived 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

      • reflectionEquals

         static boolean reflectionEquals(Object lhs, Object rhs, boolean testTransients, Class<out Object> reflectUpToClass, Array<String> excludeFields)

        This method uses reflection to determine if the two Objectsare equal.

        It uses AccessibleObject.setAccessible to gain access to privatefields. This means that it will throw a security exception if run undera security manager, if the permissions are not set up correctly. It is alsonot as efficient as testing explicitly.

        If the testTransients parameter is set to true, transientmembers will be tested, otherwise they are ignored, as they are likelyderived fields, and not part of the value of the Object.

        Static fields will not be included. Superclass fields will be appendedup to and including the specified superclass. A null superclass is treatedas 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

      • appendSuper

         EqualsBuilder appendSuper(boolean superEquals)

        Adds the result of super.equals() to this builder.

        Parameters:
        superEquals - the result of calling super.equals()

      • append

         EqualsBuilder append(Object lhs, Object rhs)

        Test if two Objects are equal using theirequals method.

        Parameters:
        lhs - the left hand object
        rhs - the right hand object

      • append

         EqualsBuilder append(long lhs, long rhs)

        Test if two long s are equal.

        Parameters:
        lhs - the left hand long
        rhs - the right hand long

      • append

         EqualsBuilder append(int lhs, int rhs)

        Test if two ints are equal.

        Parameters:
        lhs - the left hand int
        rhs - the right hand int

      • append

         EqualsBuilder append(short lhs, short rhs)

        Test if two shorts are equal.

        Parameters:
        lhs - the left hand short
        rhs - the right hand short

      • append

         EqualsBuilder append(char lhs, char rhs)

        Test if two chars are equal.

        Parameters:
        lhs - the left hand char
        rhs - the right hand char

      • append

         EqualsBuilder append(byte lhs, byte rhs)

        Test if two bytes are equal.

        Parameters:
        lhs - the left hand byte
        rhs - the right hand byte

      • append

         EqualsBuilder append(double lhs, double rhs)

        Test if two doubles are equal by testing that thepattern of bits returned by doubleToLong are equal.

        This handles NaNs, Infinities, and -0.0.

        It is compatible with the hash code generated byHashCodeBuilder.

        Parameters:
        lhs - the left hand double
        rhs - the right hand double

      • append

         EqualsBuilder append(float lhs, float rhs)

        Test if two floats are equal byt testing that thepattern of bits returned by doubleToLong are equal.

        This handles NaNs, Infinities, and -0.0.

        It is compatible with the hash code generated byHashCodeBuilder.

        Parameters:
        lhs - the left hand float
        rhs - the right hand float

      • append

         EqualsBuilder append(boolean lhs, boolean rhs)

        Test if two booleanss are equal.

        Parameters:
        lhs - the left hand boolean
        rhs - the right hand boolean

      • append

         EqualsBuilder append(Array<Object> lhs, Array<Object> rhs)

        Performs a deep comparison of two Object arrays.

        This also will be called for the top level ofmulti-dimensional, ragged, and multi-typed arrays.

        Parameters:
        lhs - the left hand Object[]
        rhs - the right hand Object[]

      • append

         EqualsBuilder append(Array<long> lhs, Array<long> rhs)

        Deep comparison of array of long. Length and allvalues are compared.

        The method append is used.

        Parameters:
        lhs - the left hand long[]
        rhs - the right hand long[]

      • append

         EqualsBuilder append(Array<int> lhs, Array<int> rhs)

        Deep comparison of array of int. Length and allvalues are compared.

        The method append is used.

        Parameters:
        lhs - the left hand int[]
        rhs - the right hand int[]

      • append

         EqualsBuilder append(Array<short> lhs, Array<short> rhs)

        Deep comparison of array of short. Length and allvalues are compared.

        The method append is used.

        Parameters:
        lhs - the left hand short[]
        rhs - the right hand short[]

      • append

         EqualsBuilder append(Array<char> lhs, Array<char> rhs)

        Deep comparison of array of char. Length and allvalues are compared.

        The method append is used.

        Parameters:
        lhs - the left hand char[]
        rhs - the right hand char[]

      • append

         EqualsBuilder append(Array<byte> lhs, Array<byte> rhs)

        Deep comparison of array of byte. Length and allvalues are compared.

        The method append is used.

        Parameters:
        lhs - the left hand byte[]
        rhs - the right hand byte[]

      • append

         EqualsBuilder append(Array<double> lhs, Array<double> rhs)

        Deep comparison of array of double. Length and allvalues are compared.

        The method append is used.

        Parameters:
        lhs - the left hand double[]
        rhs - the right hand double[]

      • append

         EqualsBuilder append(Array<float> lhs, Array<float> rhs)

        Deep comparison of array of float. Length and allvalues are compared.

        The method append is used.

        Parameters:
        lhs - the left hand float[]
        rhs - the right hand float[]

      • append

         EqualsBuilder append(Array<boolean> lhs, Array<boolean> rhs)

        Deep comparison of array of boolean. Length and allvalues are compared.

        The method append is used.

        Parameters:
        lhs - the left hand boolean[]
        rhs - the right hand boolean[]

      • build

         Boolean build()

        Returns true if the fields that have been checkedare all equal.

      • reset

         void reset()

        Reset the EqualsBuilder so you can use the same object again