DiffBuilder
Date: 2017-02-08

org.apache.commons.lang3.builder

## Class DiffBuilder

- java.lang.Object
- - org.apache.commons.lang3.builder.DiffBuilder

- All Implemented Interfaces:
    Builder<DiffResult>

      public class DiffBuilder
      extends java.lang.Object
      implements Builder<DiffResult>

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

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

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `DiffBuilder` | `append(java.lang.String fieldName, boolean[] lhs, boolean[] rhs)` Test if two `boolean[]`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, boolean lhs, boolean rhs)` Test if two `boolean`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, byte[] lhs, byte[] rhs)` Test if two `byte[]`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, byte lhs, byte rhs)` Test if two `byte`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, char[] lhs, char[] rhs)` Test if two `char[]`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, char lhs, char rhs)` Test if two `char`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, DiffResult diffResult)` Append diffs from another `DiffResult`.
    `DiffBuilder` | `append(java.lang.String fieldName, double[] lhs, double[] rhs)` Test if two `double[]`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, double lhs, double rhs)` Test if two `double`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, float[] lhs, float[] rhs)` Test if two `float[]`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, float lhs, float rhs)` Test if two `float`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, int[] lhs, int[] rhs)` Test if two `int[]`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, int lhs, int rhs)` Test if two `int`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, long[] lhs, long[] rhs)` Test if two `long[]`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, long lhs, long rhs)` Test if two `long`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, java.lang.Object[] lhs, java.lang.Object[] rhs)` Test if two `Object[]`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, java.lang.Object lhs, java.lang.Object rhs)` Test if two `Objects`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, short[] lhs, short[] rhs)` Test if two `short[]`s are equal.
    `DiffBuilder` | `append(java.lang.String fieldName, short lhs, short rhs)` Test if two `short`s are equal.
    `DiffResult` | `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(java.lang.Object lhs,
                     java.lang.Object 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:
        `java.lang.IllegalArgumentException` - if `lhs` or `rhs` is `null`
      Since:
        3.4

    - #### DiffBuilder

          public DiffBuilder(java.lang.Object lhs,
                     java.lang.Object 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:
        `java.lang.IllegalArgumentException` - if `lhs` or `rhs` is `null`

  - ### Method Detail

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.String fieldName,
                           java.lang.Object lhs,
                           java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.String fieldName,
                           java.lang.Object[] lhs,
                           java.lang.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:
        `java.lang.IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder append(java.lang.String fieldName,
                           DiffResult 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:
        `java.lang.IllegalArgumentException` - if field name is `null`
      Since:
        3.5

    - #### build

          public DiffResult build()

      Builds a `DiffResult` based on the differences appended to this builder.

      Specified by:
        `build` in interface `Builder<DiffResult>`
      Returns:
        a `DiffResult` containing the differences between the two objects.