org.apache.commons.lang3.builder

Class DiffBuilder<T>

java.lang.Object

org.apache.commons.lang3.builder.DiffBuilder<T>

Type Parameters:

T - type of the left and right object.

All Implemented Interfaces:

Builder<DiffResult<T>>

public class DiffBuilder<T>
extends 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 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(T lhs, T rhs, ToStringStyle style) Constructs a builder for the specified objects with the specified style.
DiffBuilder(T lhs, T rhs, ToStringStyle style, boolean testTriviallyEqual) Constructs a builder for the specified objects with the specified style.

Method Summary

Modifier and Type	Method and Description
DiffBuilder<T>	append(String fieldName, boolean[] lhs, boolean[] rhs) Test if two boolean[]s are equal.
DiffBuilder<T>	append(String fieldName, boolean lhs, boolean rhs) Test if two booleans are equal.
DiffBuilder<T>	append(String fieldName, byte[] lhs, byte[] rhs) Test if two byte[]s are equal.
DiffBuilder<T>	append(String fieldName, byte lhs, byte rhs) Test if two bytes are equal.
DiffBuilder<T>	append(String fieldName, char[] lhs, char[] rhs) Test if two char[]s are equal.
DiffBuilder<T>	append(String fieldName, char lhs, char rhs) Test if two chars are equal.
DiffBuilder<T>	append(String fieldName, DiffResult<T> diffResult) Append diffs from another DiffResult.
DiffBuilder<T>	append(String fieldName, double[] lhs, double[] rhs) Test if two double[]s are equal.
DiffBuilder<T>	append(String fieldName, double lhs, double rhs) Test if two doubles are equal.
DiffBuilder<T>	append(String fieldName, float[] lhs, float[] rhs) Test if two float[]s are equal.
DiffBuilder<T>	append(String fieldName, float lhs, float rhs) Test if two floats are equal.
DiffBuilder<T>	append(String fieldName, int[] lhs, int[] rhs) Test if two int[]s are equal.
DiffBuilder<T>	append(String fieldName, int lhs, int rhs) Test if two ints are equal.
DiffBuilder<T>	append(String fieldName, long[] lhs, long[] rhs) Test if two long[]s are equal.
DiffBuilder<T>	append(String fieldName, long lhs, long rhs) Test if two longs are equal.
DiffBuilder<T>	append(String fieldName, Object[] lhs, Object[] rhs) Test if two Object[]s are equal.
DiffBuilder<T>	append(String fieldName, Object lhs, Object rhs) Test if two Objectss are equal.
DiffBuilder<T>	append(String fieldName, short[] lhs, short[] rhs) Test if two short[]s are equal.
DiffBuilder<T>	append(String fieldName, short lhs, short rhs) Test if two shorts are equal.
DiffResult<T>	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(T lhs,
                   T 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(T lhs,
                   T 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<T> append(String fieldName,
                             boolean lhs,
                             boolean rhs)

Test if two booleans 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<T> 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<T> append(String fieldName,
                             byte lhs,
                             byte rhs)

Test if two bytes 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<T> 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<T> append(String fieldName,
                             char lhs,
                             char rhs)

Test if two chars 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<T> 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<T> append(String fieldName,
                             double lhs,
                             double rhs)

Test if two doubles 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<T> 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<T> append(String fieldName,
                             float lhs,
                             float rhs)

Test if two floats 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<T> 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<T> append(String fieldName,
                             int lhs,
                             int rhs)

Test if two ints 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<T> 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<T> append(String fieldName,
                             long lhs,
                             long rhs)

Test if two longs 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<T> 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<T> append(String fieldName,
                             short lhs,
                             short rhs)

Test if two shorts 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<T> 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<T> append(String fieldName,
                             Object lhs,
                             Object rhs)

Test if two Objectss are equal.

Parameters:

fieldName - the field name

lhs - the left hand Object

rhs - the right hand Object

Returns:

this

Throws:

IllegalArgumentException - if field name is null

append

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

Throws:

IllegalArgumentException - if field name is null

append

public DiffBuilder<T> append(String fieldName,
                             DiffResult<T> 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:

IllegalArgumentException - if field name is null

Since:

3.5

build

public DiffResult<T> build()

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

Specified by:

build in interface Builder<DiffResult<T>>

Returns:

a DiffResult containing the differences between the two objects.