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

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.<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 java.lang.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.