Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.lang.builder
Class EqualsBuilder

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

public class EqualsBuilder
extends java.lang.Object

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.

Method Summary
`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 byt 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(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 `Object`s are equal using their `equals` method.
`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` | `isEquals()` Returns `true` if the fields that have been checked are all equal.
`static boolean` | `reflectionEquals(java.lang.Object lhs, java.lang.Object rhs)` This method uses reflection to determine if the two `Object`s are equal.
`static boolean` | `reflectionEquals(java.lang.Object lhs, java.lang.Object rhs, boolean testTransients)` This method uses reflection to determine if the two `Object`s are equal.
`static boolean` | `reflectionEquals(java.lang.Object lhs, java.lang.Object rhs, boolean testTransients, java.lang.Class reflectUpToClass)` This method uses reflection to determine if the two `Object`s 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 `Object`s are equal.
`static boolean` | `reflectionEquals(java.lang.Object lhs, java.lang.Object rhs, java.util.Collection excludeFields)` This method uses reflection to determine if the two `Object`s 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 `Object`s are equal.
`protected void` | `setEquals(boolean isEquals)` Sets the `isEquals` value.

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

### reflectionEquals

    public static boolean reflectionEquals(java.lang.Object lhs,
                                           java.lang.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. 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.

  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
  Returns:
    `true` if the two Objects have tested equals.

### reflectionEquals

    public static boolean reflectionEquals(java.lang.Object lhs,
                                           java.lang.Object rhs,
                                           java.util.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. 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.

  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.

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

  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.

### reflectionEquals

    public static boolean reflectionEquals(java.lang.Object lhs,
                                           java.lang.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.

  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.

### reflectionEquals

    public static boolean reflectionEquals(java.lang.Object lhs,
                                           java.lang.Object rhs,
                                           boolean testTransients,
                                           java.lang.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. 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.

  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`
  Returns:
    `true` if the two Objects have tested equals.
  Since:
    2.0

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

  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

### appendSuper

    public EqualsBuilder appendSuper(boolean superEquals)

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

  Parameters:
    `superEquals` - the result of calling `super.equals()`
  Returns:
    EqualsBuilder - used to chain calls.
  Since:
    2.0

### append

    public EqualsBuilder append(java.lang.Object lhs,
                                java.lang.Object rhs)

  Test if two `Object`s are equal using their `equals` method.

  Parameters:
    `lhs` - the left hand object
    `rhs` - the right hand object
  Returns:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

### append

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

  Parameters:
    `lhs` - the left hand `float`
    `rhs` - the right hand `float`
  Returns:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

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

  Parameters:
    `lhs` - the left hand `Object[]`
    `rhs` - the right hand `Object[]`
  Returns:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

### 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:
    EqualsBuilder - used to chain calls.

### isEquals

    public boolean isEquals()

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

  Returns:
    boolean

### setEquals

    protected void setEquals(boolean isEquals)

  Sets the `isEquals` value.

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2008 The Apache Software Foundation. All Rights Reserved.