Package org.apache.commons.lang3.builder

Class DiffBuilder<T>

  • Type Parameters:
    T - type of the left and right object.
    All Implemented Interfaces:
    Builder<DiffResult<T>>
    public class DiffBuilder<T>
extends java.lang.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<Person> diff(Person obj) {
     // No need for null check, as NullPointerException correct if obj is null
     return 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 class  DiffBuilder.Builder<T>
      Constructs a new instance.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      DiffBuilder<T> append​(java.lang.String fieldName, boolean[] lhs, boolean[] rhs)
      Tests if two boolean[]s are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, boolean lhs, boolean rhs)
      Tests if two booleans are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, byte[] lhs, byte[] rhs)
      Tests if two byte[]s are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, byte lhs, byte rhs)
      Tests if two bytes are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, char[] lhs, char[] rhs)
      Tests if two char[]s are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, char lhs, char rhs)
      Tests if two chars are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, double[] lhs, double[] rhs)
      Tests if two double[]s are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, double lhs, double rhs)
      Tests if two doubles are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, float[] lhs, float[] rhs)
      Tests if two float[]s are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, float lhs, float rhs)
      Test if two floats are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, int[] lhs, int[] rhs)
      Tests if two int[]s are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, int lhs, int rhs)
      Tests if two ints are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, long[] lhs, long[] rhs)
      Tests if two long[]s are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, long lhs, long rhs)
      Tests if two longs are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, short[] lhs, short[] rhs)
      Tests if two short[]s are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, short lhs, short rhs)
      Tests if two shorts are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, java.lang.Object[] lhs, java.lang.Object[] rhs)
      Tests if two Object[]s are equal.
      DiffBuilder<T> append​(java.lang.String fieldName, java.lang.Object lhs, java.lang.Object rhs)
      Tests if two Objectss are equal.
      DiffBuilder<T> append​(java.lang.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 Detail

      • 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:
        java.lang.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:
        java.lang.NullPointerException - if lhs or rhs is null.
        Since:
        3.4

    • Method Detail

      • append

        public DiffBuilder<T> append​(java.lang.String fieldName,
                             boolean lhs,
                             boolean rhs)
        Tests if two booleans are equal.
        Parameters:
        fieldName - the field name.
        lhs - the left-hand side boolean.
        rhs - the right-hand side boolean.
        Returns:
        this instance.
        Throws:
        java.lang.NullPointerException - if field name is null.

      • append

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

      • append

        public DiffBuilder<T> append​(java.lang.String fieldName,
                             byte lhs,
                             byte rhs)
        Tests if two bytes are equal.
        Parameters:
        fieldName - the field name.
        lhs - the left-hand side byte.
        rhs - the right-hand side byte.
        Returns:
        this instance.
        Throws:
        java.lang.NullPointerException - if field name is null.

      • append

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

      • append

        public DiffBuilder<T> append​(java.lang.String fieldName,
                             char lhs,
                             char rhs)
        Tests if two chars are equal.
        Parameters:
        fieldName - the field name.
        lhs - the left-hand side char.
        rhs - the right-hand side char.
        Returns:
        this instance.
        Throws:
        java.lang.NullPointerException - if field name is null.

      • append

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

      • append

        public DiffBuilder<T> append​(java.lang.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:
        java.lang.NullPointerException - if field name is null or diffResult is null.
        Since:
        3.5

      • append

        public DiffBuilder<T> append​(java.lang.String fieldName,
                             double lhs,
                             double rhs)
        Tests if two doubles are equal.
        Parameters:
        fieldName - the field name.
        lhs - the left-hand side double.
        rhs - the right-hand side double.
        Returns:
        this instance.
        Throws:
        java.lang.NullPointerException - if field name is null.

      • append

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

      • append

        public DiffBuilder<T> append​(java.lang.String fieldName,
                             float lhs,
                             float rhs)
        Test if two floats are equal.
        Parameters:
        fieldName - the field name.
        lhs - the left-hand side float.
        rhs - the right-hand side float.
        Returns:
        this instance.
        Throws:
        java.lang.NullPointerException - if field name is null.

      • append

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

      • append

        public DiffBuilder<T> append​(java.lang.String fieldName,
                             int lhs,
                             int rhs)
        Tests if two ints are equal.
        Parameters:
        fieldName - the field name.
        lhs - the left-hand side int.
        rhs - the right-hand side int.
        Returns:
        this instance.
        Throws:
        java.lang.NullPointerException - if field name is null.

      • append

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

      • append

        public DiffBuilder<T> append​(java.lang.String fieldName,
                             long lhs,
                             long rhs)
        Tests if two longs are equal.
        Parameters:
        fieldName - the field name.
        lhs - the left-hand side long.
        rhs - the right-hand side long.
        Returns:
        this instance.
        Throws:
        java.lang.NullPointerException - if field name is null.

      • append

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

      • append

        public DiffBuilder<T> append​(java.lang.String fieldName,
                             java.lang.Object lhs,
                             java.lang.Object rhs)
        Tests if two Objectss are equal.
        Parameters:
        fieldName - the field name.
        lhs - the left-hand side Object.
        rhs - the right-hand side Object.
        Returns:
        this instance.
        Throws:
        java.lang.NullPointerException - if field name is null.

      • append

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

      • append

        public DiffBuilder<T> append​(java.lang.String fieldName,
                             short lhs,
                             short rhs)
        Tests if two shorts are equal.
        Parameters:
        fieldName - the field name.
        lhs - the left-hand side short.
        rhs - the right-hand side short.
        Returns:
        this instance.
        Throws:
        java.lang.NullPointerException - if field name is null.

      • append

        public DiffBuilder<T> append​(java.lang.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:
        java.lang.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.