Class ReflectionDiffBuilder<T>

java.lang.Object
org.apache.commons.lang3.builder.AbstractReflection
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 AbstractReflection 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:
  • Field Details

    • REGISTRY

      private static final ThreadLocal<Set<Pair<IDKey,IDKey>>> REGISTRY
      A registry of objects to detect cyclical object references, avoid infinite loops, and stack overflows.
    • diffBuilder

      private final DiffBuilder<T> diffBuilder
    • excludeFieldNames

      private String[] excludeFieldNames
      Field names to exclude from output. Intended for fields like "password" or "lastModificationDate".
  • Constructor Details

    • ReflectionDiffBuilder

      private ReflectionDiffBuilder(ReflectionDiffBuilder.Builder<T> builder)
      Constructs a new instance.
      Parameters:
      builder - A non-null Builder.
      Throws:
      NullPointerException - Thrown on null input.
    • ReflectionDiffBuilder

      private ReflectionDiffBuilder(DiffBuilder<T> diffBuilder, String[] excludeFieldNames)
      Constructs a new instance.
      Parameters:
      diffBuilder - A non-null DiffBuilder.
      excludeFieldNames - A non-null String array.
      Throws:
      NullPointerException - Thrown on null input.
    • ReflectionDiffBuilder

      @Deprecated public ReflectionDiffBuilder(T left, T right, ToStringStyle style)
      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 - Thrown if left or right is null.
  • Method Details

    • builder

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

      static Set<Pair<IDKey,IDKey>> getRegistry()
      Gets the registry of object pairs being traversed by the reflection methods in the current thread.
      Returns:
      Set the registry of objects being traversed
    • isRegistered

      static boolean isRegistered(Object lhs, Object rhs)
      Tests whether the registry contains the given object pair.

      Used by the reflection methods to avoid infinite loops. Objects might be swapped therefore a check is needed if the object pair is registered in the given or swapped order.

      Parameters:
      lhs - this object to lookup in registry
      rhs - The other object to lookup on registry
      Returns:
      boolean true if the registry contains the given object.
    • register

      static void register(Object lhs, Object rhs)
      Registers the given object pair. Used by the reflection methods to avoid infinite loops.
      Parameters:
      lhs - this object to register
      rhs - the other object to register
    • toExcludeFieldNames

      private static String[] toExcludeFieldNames(String[] excludeFieldNames)
    • unregister

      static void unregister(Object lhs, Object rhs)
      Unregisters the given object pair.

      Used by the reflection methods to avoid infinite loops.

      Parameters:
      lhs - this object to unregister
      rhs - the other object to unregister
    • accept

      private boolean accept(Field field)
    • appendFields

      private void appendFields(Class<?> clazz)
      Appends fields using reflection.
      Throws:
      SecurityException - Thrown if an underlying accessible object's method denies the request.
      See Also:
    • 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 - Thrown if an underlying accessible object's method denies the request.
      See Also:
    • getExcludeFieldNames

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

      private T getLeft()
    • getRight

      private T getRight()
    • setExcludeFieldNames

      @Deprecated public ReflectionDiffBuilder<T> setExcludeFieldNames(String... excludeFieldNames)
      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