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

# Class ReflectionDiffBuilder<T>

java.lang.Object
org.apache.commons.lang3.builder.ReflectionDiffBuilder<T>

Type Parameters:
  `T` - type of the left and right object to diff.

All Implemented Interfaces:
  `Builder<DiffResult<T>>`

public class ReflectionDiffBuilder<T> extends Object implements Builder<DiffResult<T>>
Assists in implementing `Diffable.diff(Object)` methods.

All non-static, non-transient fields (including inherited fields) of the objects to diff are discovered using reflection and compared for differences.

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 ReflectionDiffBuilder.<Person>builder()
          .setDiffBuilder(DiffBuilder.<Person>builder()
              .setLeft(this)
              .setRight(obj)
              .setStyle(ToStringStyle.SHORT_PREFIX_STYLE)
              .build())
          .setExcludeFieldNames("userName", "password")
          .build()  // -> ReflectionDiffBuilder
          .build(); // -> DiffResult
      }
    }

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 `DiffBuilder` for a non-reflection based version of this class.

Since:
  3.6
See Also:
  - `Diffable`
  - `Diff`
  - `DiffResult`
  - `ToStringStyle`
  - `DiffBuilder`

- ## Nested Class Summary

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

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DiffResult<T>`
  `build()`
  Returns a reference to the object being constructed or result being calculated by the builder.
  `static <T> ReflectionDiffBuilder.Builder<T>`
  `builder()`
  Constructs a new `ReflectionDiffBuilder.Builder`.
  `String[]`
  `getExcludeFieldNames()`
  Gets the field names that should be excluded from the diff.
  `ReflectionDiffBuilder<T>`
  `setExcludeFieldNames(String... excludeFieldNames)`
  Deprecated.
  Use `ReflectionDiffBuilder.Builder.setExcludeFieldNames(String[])`.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### ReflectionDiffBuilder

    @Deprecated public ReflectionDiffBuilder(T left, T right, ToStringStyle style)
    Deprecated.
    Use `ReflectionDiffBuilder.Builder`.
    Constructs a builder for the specified objects with the specified style.

    If `left == right` or `left.equals(right)` 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 will use when outputting the objects, `null` uses the default
    Throws:
      `IllegalArgumentException` - if `left` or `right` is `null`.

- ## Method Details

  - ### builder

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

  - ### build

    public DiffResult<T> build()
    Returns a reference to the object being constructed or result being calculated by the builder.
    Specified by:
      `build` in interface `Builder<T>`
    Returns:
      the object constructed or result calculated by the builder.
    Throws:
      `SecurityException` - if an underlying accessible object's method denies the request.
    See Also:
      - `SecurityManager.checkPermission(Permission)`

  - ### getExcludeFieldNames

    public String[] getExcludeFieldNames()
    Gets the field names that should be excluded from the diff.
    Returns:
      the excludeFieldNames.
    Since:
      3.13.0

  - ### setExcludeFieldNames

    @Deprecated public ReflectionDiffBuilder<T> setExcludeFieldNames(String... excludeFieldNames)
    Deprecated.
    Use `ReflectionDiffBuilder.Builder.setExcludeFieldNames(String[])`.
    Sets the field names to exclude.
    Parameters:
      `excludeFieldNames` - The field names to exclude from the diff or `null`.
    Returns:
      `this` instance.
    Since:
      3.13.0