Package 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
  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

  Modifier and Type
  Method
  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, 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, 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.
  `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, DiffResult<T> diffResult)`
  Append diffs from another `DiffResult`.
  `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 Details

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

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

- ## Method Details

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

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

  - ### build

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