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 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
  Version:
    $Id: DiffBuilder.java 1669782 2015-03-28 15:05:04Z britter $
  See Also:
    `Diffable`, `Diff`, `DiffResult`, `ToStringStyle`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DiffBuilder(Object lhs, Object rhs, ToStringStyle style)` Constructs a builder for the specified objects with the specified style.
    `DiffBuilder(Object lhs, 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(String fieldName, boolean[] lhs, boolean[] rhs)` Test if two `boolean[]`s are equal.
    `DiffBuilder` | `append(String fieldName, boolean lhs, boolean rhs)` Test if two `boolean`s are equal.
    `DiffBuilder` | `append(String fieldName, byte[] lhs, byte[] rhs)` Test if two `byte[]`s are equal.
    `DiffBuilder` | `append(String fieldName, byte lhs, byte rhs)` Test if two `byte`s are equal.
    `DiffBuilder` | `append(String fieldName, char[] lhs, char[] rhs)` Test if two `char[]`s are equal.
    `DiffBuilder` | `append(String fieldName, char lhs, char rhs)` Test if two `char`s are equal.
    `DiffBuilder` | `append(String fieldName, double[] lhs, double[] rhs)` Test if two `double[]`s are equal.
    `DiffBuilder` | `append(String fieldName, double lhs, double rhs)` Test if two `double`s are equal.
    `DiffBuilder` | `append(String fieldName, float[] lhs, float[] rhs)` Test if two `float[]`s are equal.
    `DiffBuilder` | `append(String fieldName, float lhs, float rhs)` Test if two `float`s are equal.
    `DiffBuilder` | `append(String fieldName, int[] lhs, int[] rhs)` Test if two `int[]`s are equal.
    `DiffBuilder` | `append(String fieldName, int lhs, int rhs)` Test if two `int`s are equal.
    `DiffBuilder` | `append(String fieldName, long[] lhs, long[] rhs)` Test if two `long[]`s are equal.
    `DiffBuilder` | `append(String fieldName, long lhs, long rhs)` Test if two `long`s are equal.
    `DiffBuilder` | `append(String fieldName, Object[] lhs, Object[] rhs)` Test if two `Object[]`s are equal.
    `DiffBuilder` | `append(String fieldName, Object lhs, Object rhs)` Test if two `Objects`s are equal.
    `DiffBuilder` | `append(String fieldName, short[] lhs, short[] rhs)` Test if two `short[]`s are equal.
    `DiffBuilder` | `append(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(Object lhs,
                     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:
        `IllegalArgumentException` - if `lhs` or `rhs` is `null`
      Since:
        3.4

    - #### DiffBuilder

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

  - ### Method Detail

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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:
        `IllegalArgumentException` - if field name is `null`

    - #### append

          public DiffBuilder 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

    - #### append

          public DiffBuilder 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

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

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