org.apache.commons.lang3.builder

## Class DiffBuilder<T>

- java.lang.Object
- - org.apache.commons.lang3.builder.DiffBuilder<T>

- Type Parameters:
    `T` - type of the left and right object.
  All Implemented Interfaces:
    Builder<DiffResult<T>>

      public class DiffBuilder<T>
      extends Object
      implements Builder<DiffResult<T>>

  Assists in implementing `Diffable.diff(Object)` methods.

  To use this class, write code as follows:

       public class Person implements Diffable<Person> {
         String name;
         int age;
         boolean smoker;

         ...

         public DiffResult diff(Person obj) {
           // No need for null check, as NullPointerException correct if obj is null
           return new DiffBuilder(this, obj, ToStringStyle.SHORT_PREFIX_STYLE)
             .append("name", this.name, obj.name)
             .append("age", this.age, obj.age)
             .append("smoker", this.smoker, obj.smoker)
             .build();
         }
       }

  The `ToStringStyle` passed to the constructor is embedded in the returned `DiffResult` and influences the style of the `DiffResult.toString()` method. This style choice can be overridden by calling `DiffResult.toString(ToStringStyle)`.

  See `ReflectionDiffBuilder` for a reflection based version of this class.

  Since:
    3.3
  See Also:
    `Diffable`, `Diff`, `DiffResult`, `ToStringStyle`, `ReflectionDiffBuilder`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DiffBuilder(T lhs, T rhs, ToStringStyle style)` Constructs a builder for the specified objects with the specified style.
    `DiffBuilder(T lhs, T rhs, ToStringStyle style, boolean testTriviallyEqual)` Constructs a builder for the specified objects with the specified style.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `DiffBuilder<T>` | `append(String fieldName, boolean[] lhs, boolean[] rhs)` Test if two `boolean[]`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, boolean lhs, boolean rhs)` Test if two `boolean`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, byte[] lhs, byte[] rhs)` Test if two `byte[]`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, byte lhs, byte rhs)` Test if two `byte`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, char[] lhs, char[] rhs)` Test if two `char[]`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, char lhs, char rhs)` Test if two `char`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, DiffResult<T> diffResult)` Append diffs from another `DiffResult`.
    `DiffBuilder<T>` | `append(String fieldName, double[] lhs, double[] rhs)` Test if two `double[]`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, double lhs, double rhs)` Test if two `double`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, float[] lhs, float[] rhs)` Test if two `float[]`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, float lhs, float rhs)` Test if two `float`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, int[] lhs, int[] rhs)` Test if two `int[]`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, int lhs, int rhs)` Test if two `int`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, long[] lhs, long[] rhs)` Test if two `long[]`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, long lhs, long rhs)` Test if two `long`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, Object[] lhs, Object[] rhs)` Test if two `Object[]`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, Object lhs, Object rhs)` Test if two `Objects`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, short[] lhs, short[] rhs)` Test if two `short[]`s are equal.
    `DiffBuilder<T>` | `append(String fieldName, short lhs, short rhs)` Test if two `short`s are equal.
    `DiffResult<T>` | `build()` Builds a `DiffResult` based on the differences appended to this builder.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### DiffBuilder

          public DiffBuilder(T lhs,
                             T rhs,
                             ToStringStyle style,
                             boolean testTriviallyEqual)

      Constructs a builder for the specified objects with the specified style.

      If `lhs == rhs` or `lhs.equals(rhs)` then the builder will not evaluate any calls to `append(...)` and will return an empty `DiffResult` when `build()` is executed.

      Parameters:
        `lhs` - `this` object
        `rhs` - the object to diff against
        `style` - the style will use when outputting the objects, `null` uses the default
        `testTriviallyEqual` - If true, this will test if lhs and rhs are the same or equal. All of the append(fieldName, lhs, rhs) methods will abort without creating a field `Diff` if the trivially equal test is enabled and returns true. The result of this test is never changed throughout the life of this `DiffBuilder`.
      Throws:
        `NullPointerException` - if `lhs` or `rhs` is `null`
      Since:
        3.4

    - #### DiffBuilder

          public DiffBuilder(T lhs,
                             T rhs,
                             ToStringStyle style)

      Constructs a builder for the specified objects with the specified style.

      If `lhs == rhs` or `lhs.equals(rhs)` then the builder will not evaluate any calls to `append(...)` and will return an empty `DiffResult` when `build()` is executed.

      This delegates to `DiffBuilder(Object, Object, ToStringStyle, boolean)` with the testTriviallyEqual flag enabled.

      Parameters:
        `lhs` - `this` object
        `rhs` - the object to diff against
        `style` - the style will use when outputting the objects, `null` uses the default
      Throws:
        `NullPointerException` - if `lhs` or `rhs` is `null`

  - ### Method Detail

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       boolean lhs,
                                       boolean rhs)

      Test if two `boolean`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `boolean`
        `rhs` - the right-hand `boolean`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       boolean[] lhs,
                                       boolean[] rhs)

      Test if two `boolean[]`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `boolean[]`
        `rhs` - the right-hand `boolean[]`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       byte lhs,
                                       byte rhs)

      Test if two `byte`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `byte`
        `rhs` - the right-hand `byte`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       byte[] lhs,
                                       byte[] rhs)

      Test if two `byte[]`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `byte[]`
        `rhs` - the right-hand `byte[]`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       char lhs,
                                       char rhs)

      Test if two `char`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `char`
        `rhs` - the right-hand `char`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       char[] lhs,
                                       char[] rhs)

      Test if two `char[]`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `char[]`
        `rhs` - the right-hand `char[]`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       double lhs,
                                       double rhs)

      Test if two `double`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `double`
        `rhs` - the right-hand `double`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       double[] lhs,
                                       double[] rhs)

      Test if two `double[]`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `double[]`
        `rhs` - the right-hand `double[]`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       float lhs,
                                       float rhs)

      Test if two `float`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `float`
        `rhs` - the right-hand `float`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       float[] lhs,
                                       float[] rhs)

      Test if two `float[]`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `float[]`
        `rhs` - the right-hand `float[]`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       int lhs,
                                       int rhs)

      Test if two `int`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `int`
        `rhs` - the right-hand `int`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       int[] lhs,
                                       int[] rhs)

      Test if two `int[]`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `int[]`
        `rhs` - the right-hand `int[]`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       long lhs,
                                       long rhs)

      Test if two `long`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `long`
        `rhs` - the right-hand `long`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       long[] lhs,
                                       long[] rhs)

      Test if two `long[]`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `long[]`
        `rhs` - the right-hand `long[]`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       short lhs,
                                       short rhs)

      Test if two `short`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `short`
        `rhs` - the right-hand `short`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       short[] lhs,
                                       short[] rhs)

      Test if two `short[]`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `short[]`
        `rhs` - the right-hand `short[]`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       Object lhs,
                                       Object rhs)

      Test if two `Objects`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `Object`
        `rhs` - the right-hand `Object`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       Object[] lhs,
                                       Object[] rhs)

      Test if two `Object[]`s are equal.
      Parameters:
        `fieldName` - the field name
        `lhs` - the left-hand `Object[]`
        `rhs` - the right-hand `Object[]`
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null`

    - #### append

          public DiffBuilder<T> append(String fieldName,
                                       DiffResult<T> diffResult)

      Append diffs from another `DiffResult`.

      This method is useful if you want to compare properties which are themselves Diffable and would like to know which specific part of it is different.

           public class Person implements Diffable<Person> {
             String name;
             Address address; // implements Diffable<Address>

             ...

             public DiffResult diff(Person obj) {
               return new DiffBuilder(this, obj, ToStringStyle.SHORT_PREFIX_STYLE)
                 .append("name", this.name, obj.name)
                 .append("address", this.address.diff(obj.address))
                 .build();
             }
           }

      Parameters:
        `fieldName` - the field name
        `diffResult` - the `DiffResult` to append
      Returns:
        this
      Throws:
        `NullPointerException` - if field name is `null` or diffResult is `null`
      Since:
        3.5

    - #### build

          public DiffResult<T> build()

      Builds a `DiffResult` based on the differences appended to this builder.
      Specified by:
        `build` in interface `Builder<DiffResult<T>>`
      Returns:
        a `DiffResult` containing the differences between the two objects.

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