DiffBuilder (Apache Commons Lang 3.20.0 API)
Description: declaration: package: org.apache.commons.lang3.builder, class: DiffBuilder

# 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<Person> diff(Person obj) {
        // No need for null check, as NullPointerException correct if obj is null
        return DiffBuilder.<Person>builder()
            .setLeft(this)
            .setRight(obj)
            .setStyle(ToStringStyle.SHORT_PREFIX_STYLE)
            .build()
          .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`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `DiffBuilder.Builder<T>`
  Constructs a new instance.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DiffBuilder(T left, T right, ToStringStyle style)`
  Deprecated.
  Use `DiffBuilder.Builder`.
  `DiffBuilder(T left, T right, ToStringStyle style, boolean testObjectsEquals)`
  Deprecated.
  Use `DiffBuilder.Builder`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DiffBuilder<T>`
  `append(String fieldName, boolean[] lhs, boolean[] rhs)`
  Tests if two `boolean[]`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, boolean lhs, boolean rhs)`
  Tests if two `boolean`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, byte[] lhs, byte[] rhs)`
  Tests if two `byte[]`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, byte lhs, byte rhs)`
  Tests if two `byte`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, char[] lhs, char[] rhs)`
  Tests if two `char[]`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, char lhs, char rhs)`
  Tests if two `char`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, double[] lhs, double[] rhs)`
  Tests if two `double[]`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, double lhs, double rhs)`
  Tests if two `double`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, float[] lhs, float[] rhs)`
  Tests 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)`
  Tests if two `int[]`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, int lhs, int rhs)`
  Tests if two `int`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, long[] lhs, long[] rhs)`
  Tests if two `long[]`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, long lhs, long rhs)`
  Tests if two `long`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, short[] lhs, short[] rhs)`
  Tests if two `short[]`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, short lhs, short rhs)`
  Tests if two `short`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, Object[] lhs, Object[] rhs)`
  Tests if two `Object[]`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, Object lhs, Object rhs)`
  Tests if two `Objects`s are equal.
  `DiffBuilder<T>`
  `append(String fieldName, DiffResult<?> diffResult)`
  Appends diffs from another `DiffResult`.
  `DiffResult<T>`
  `build()`
  Builds a `DiffResult` based on the differences appended to this builder.
  `static <T> DiffBuilder.Builder<T>`
  `builder()`
  Constructs a new `DiffBuilder.Builder`.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### DiffBuilder

    @Deprecated public DiffBuilder(T left, T right, ToStringStyle style)
    Deprecated.
    Use `DiffBuilder.Builder`.
    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:
      `left` - `this` object.
      `right` - the object to diff against.
      `style` - the style to use when outputting the objects, `null` uses the default.
    Throws:
      `NullPointerException` - if `lhs` or `rhs` is `null`.

  - ### DiffBuilder

    @Deprecated public DiffBuilder(T left, T right, ToStringStyle style, boolean testObjectsEquals)
    Deprecated.
    Use `DiffBuilder.Builder`.
    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:
      `left` - `this` object.
      `right` - the object to diff against.
      `style` - the style to use when outputting the objects, `null` uses the default.
      `testObjectsEquals` - 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

  - ### builder

    public static <T> DiffBuilder.Builder<T> builder()
    Constructs a new `DiffBuilder.Builder`.
    Type Parameters:
      `T` - type of the left and right object.
    Returns:
      a new `DiffBuilder.Builder`.
    Since:
      3.15.0

  - ### append

    public DiffBuilder<T> append(String fieldName, boolean lhs, boolean rhs)
    Tests if two `boolean`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `boolean`.
      `rhs` - the right-hand side `boolean`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, boolean[] lhs, boolean[] rhs)
    Tests if two `boolean[]`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `boolean[]`.
      `rhs` - the right-hand side `boolean[]`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, byte lhs, byte rhs)
    Tests if two `byte`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `byte`.
      `rhs` - the right-hand side `byte`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, byte[] lhs, byte[] rhs)
    Tests if two `byte[]`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `byte[]`.
      `rhs` - the right-hand side `byte[]`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, char lhs, char rhs)
    Tests if two `char`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `char`.
      `rhs` - the right-hand side `char`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, char[] lhs, char[] rhs)
    Tests if two `char[]`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `char[]`.
      `rhs` - the right-hand side `char[]`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, DiffResult<?> diffResult)
    Appends diffs from another `DiffResult`.

    Useful this method 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` instance.
    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)
    Tests if two `double`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `double`.
      `rhs` - the right-hand side `double`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, double[] lhs, double[] rhs)
    Tests if two `double[]`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `double[]`.
      `rhs` - the right-hand side `double[]`.
    Returns:
      `this` instance.
    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 side `float`.
      `rhs` - the right-hand side `float`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, float[] lhs, float[] rhs)
    Tests if two `float[]`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `float[]`.
      `rhs` - the right-hand side `float[]`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, int lhs, int rhs)
    Tests if two `int`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `int`.
      `rhs` - the right-hand side `int`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, int[] lhs, int[] rhs)
    Tests if two `int[]`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `int[]`.
      `rhs` - the right-hand side `int[]`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, long lhs, long rhs)
    Tests if two `long`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `long`.
      `rhs` - the right-hand side `long`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, long[] lhs, long[] rhs)
    Tests if two `long[]`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `long[]`.
      `rhs` - the right-hand side `long[]`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, Object lhs, Object rhs)
    Tests if two `Objects`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `Object`.
      `rhs` - the right-hand side `Object`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, Object[] lhs, Object[] rhs)
    Tests if two `Object[]`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `Object[]`.
      `rhs` - the right-hand side `Object[]`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, short lhs, short rhs)
    Tests if two `short`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `short`.
      `rhs` - the right-hand side `short`.
    Returns:
      `this` instance.
    Throws:
      `NullPointerException` - if field name is `null`.

  - ### append

    public DiffBuilder<T> append(String fieldName, short[] lhs, short[] rhs)
    Tests if two `short[]`s are equal.
    Parameters:
      `fieldName` - the field name.
      `lhs` - the left-hand side `short[]`.
      `rhs` - the right-hand side `short[]`.
    Returns:
      `this` instance.
    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.