Top Description Inners Fields Constructors Methods
org.apache.commons.lang3.builder

public Class DiffBuilder<T>

extends Object
implements Builder<DiffResult<T>>
Class Inheritance
All Implemented Interfaces
org.apache.commons.lang3.builder.Builder
Type Parameters
<T>
type of the left and right object.
Imports
java.io.Serializable, java.util.ArrayList, .Arrays, .List, .Objects, java.util.function.Supplier, org.apache.commons.lang3.ArrayUtils, .ObjectUtils
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 and Inner Type Summary

Modifier and TypeClass and Description
public static class
DiffBuilder.Builder<
type of the left and right object.
T>

Constructs a new instance.

private static class
DiffBuilder.SDiff<T>

private static interface
DiffBuilder.SerializableSupplier<
the type of results supplied by this supplier.
T>

Private interface while we still have to support serialization.

Field Summary

Modifier and TypeField and Description
private final List<Diff<?>>
diffs

private final boolean
equals

private final T
left

private final T
right

private final ToStringStyle
style

pack-priv static final String
TO_STRING_FORMAT

private final String
toStringFormat

Constructor Summary

AccessConstructor and Description
public
DiffBuilder(final T
this object.
left, final T
the object to diff against.
right, final ToStringStyle
the style to use when outputting the objects, null uses the default.
style)
Deprecated Use Builder.

Constructs a builder for the specified objects with the specified style.

public
DiffBuilder(final T
this object.
left, final T
the object to diff against.
right, final ToStringStyle
the style to use when outputting the objects, null uses the default.
style, final boolean
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.
testObjectsEquals)
Deprecated Use Builder.

Constructs a builder for the specified objects with the specified style.

private
DiffBuilder(final T left, final T right, final ToStringStyle style, final boolean testObjectsEquals, final String toStringFormat)

Method Summary

Modifier and TypeMethod and Description
private <F> DiffBuilder<T>
add(final String fieldName, final DiffBuilder.SerializableSupplier<F> left, final DiffBuilder.SerializableSupplier<F> right, final Class<F> type)

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final boolean
the left-hand side boolean.
lhs, final boolean
the right-hand side boolean.
rhs)

Tests if two booleans are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final boolean[]
the left-hand side boolean[].
lhs, final boolean[]
the right-hand side boolean[].
rhs)

Tests if two boolean[]s are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final byte
the left-hand side byte.
lhs, final byte
the right-hand side byte.
rhs)

Tests if two bytes are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final byte[]
the left-hand side byte[].
lhs, final byte[]
the right-hand side byte[].
rhs)

Tests if two byte[]s are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final char
the left-hand side char.
lhs, final char
the right-hand side char.
rhs)

Tests if two chars are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final char[]
the left-hand side char[].
lhs, final char[]
the right-hand side char[].
rhs)

Tests if two char[]s are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final DiffResult<?>
the DiffResult to append.
diffResult)

Appends diffs from another DiffResult.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final double
the left-hand side double.
lhs, final double
the right-hand side double.
rhs)

Tests if two doubles are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final double[]
the left-hand side double[].
lhs, final double[]
the right-hand side double[].
rhs)

Tests if two double[]s are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final float
the left-hand side float.
lhs, final float
the right-hand side float.
rhs)

Test if two floats are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final float[]
the left-hand side float[].
lhs, final float[]
the right-hand side float[].
rhs)

Tests if two float[]s are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final int
the left-hand side int.
lhs, final int
the right-hand side int.
rhs)

Tests if two ints are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final int[]
the left-hand side int[].
lhs, final int[]
the right-hand side int[].
rhs)

Tests if two int[]s are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final long
the left-hand side long.
lhs, final long
the right-hand side long.
rhs)

Tests if two longs are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final long[]
the left-hand side long[].
lhs, final long[]
the right-hand side long[].
rhs)

Tests if two long[]s are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final Object
the left-hand side Object.
lhs, final Object
the right-hand side Object.
rhs)

Tests if two Objectss are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final Object[]
the left-hand side Object[].
lhs, final Object[]
the right-hand side Object[].
rhs)

Tests if two Object[]s are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final short
the left-hand side short.
lhs, final short
the right-hand side short.
rhs)

Tests if two shorts are equal.

public DiffBuilder<T>

Returns:

this instance.
append(final String
the field name.
fieldName, final short[]
the left-hand side short[].
lhs, final short[]
the right-hand side short[].
rhs)

Tests if two short[]s are equal.

public DiffResult<T>

Returns:

a DiffResult containing the differences between the two objects.
build()

Implements org.apache.commons.lang3.builder.Builder.build.

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

public static <
type of the left and right object.
T> DiffBuilder.Builder<T>

Returns:

a new Builder.
builder()

Constructs a new Builder.

pack-priv T

Returns:

the left object.
getLeft()

Gets the left object.

pack-priv T

Returns:

the right object.
getRight()

Gets the right object.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

diffsback to summary
private final List<Diff<?>> diffs
equalsback to summary
private final boolean equals
leftback to summary
private final T left
styleback to summary
private final ToStringStyle style
TO_STRING_FORMATback to summary
pack-priv static final String TO_STRING_FORMAT
toStringFormatback to summary
private final String toStringFormat

Constructor Detail

DiffBuilderback to summary
public DiffBuilder(final T left, final T right, final ToStringStyle style)

Deprecated

Use 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:T

this object.

right:T

the object to diff against.

style:ToStringStyle

the style to use when outputting the objects, null uses the default.

Annotations
@Deprecated
Exceptions
NullPointerException:
if lhs or rhs is null.
DiffBuilderback to summary
public DiffBuilder(final T left, final T right, final ToStringStyle style, final boolean testObjectsEquals)

Deprecated

Use 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:T

this object.

right:T

the object to diff against.

style:ToStringStyle

the style to use when outputting the objects, null uses the default.

testObjectsEquals:boolean

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.

Annotations
@Deprecated
Exceptions
NullPointerException:
if lhs or rhs is null.
Since
3.4
DiffBuilderback to summary
private DiffBuilder(final T left, final T right, final ToStringStyle style, final boolean testObjectsEquals, final String toStringFormat)

Method Detail

addback to summary
private <F> DiffBuilder<T> add(final String fieldName, final DiffBuilder.SerializableSupplier<F> left, final DiffBuilder.SerializableSupplier<F> right, final Class<F> type)
appendback to summary
public DiffBuilder<T> append(final String fieldName, final boolean lhs, final boolean rhs)

Tests if two booleans are equal.

Parameters
fieldName:String

the field name.

lhs:boolean

the left-hand side boolean.

rhs:boolean

the right-hand side boolean.

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final boolean[] lhs, final boolean[] rhs)

Tests if two boolean[]s are equal.

Parameters
fieldName:String

the field name.

lhs:boolean[]

the left-hand side boolean[].

rhs:boolean[]

the right-hand side boolean[].

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final byte lhs, final byte rhs)

Tests if two bytes are equal.

Parameters
fieldName:String

the field name.

lhs:byte

the left-hand side byte.

rhs:byte

the right-hand side byte.

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final byte[] lhs, final byte[] rhs)

Tests if two byte[]s are equal.

Parameters
fieldName:String

the field name.

lhs:byte[]

the left-hand side byte[].

rhs:byte[]

the right-hand side byte[].

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final char lhs, final char rhs)

Tests if two chars are equal.

Parameters
fieldName:String

the field name.

lhs:char

the left-hand side char.

rhs:char

the right-hand side char.

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final char[] lhs, final char[] rhs)

Tests if two char[]s are equal.

Parameters
fieldName:String

the field name.

lhs:char[]

the left-hand side char[].

rhs:char[]

the right-hand side char[].

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final 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:String

the field name.

diffResult:DiffResult<?>

the DiffResult to append.

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null or diffResult is null.
Since
3.5
appendback to summary
public DiffBuilder<T> append(final String fieldName, final double lhs, final double rhs)

Tests if two doubles are equal.

Parameters
fieldName:String

the field name.

lhs:double

the left-hand side double.

rhs:double

the right-hand side double.

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final double[] lhs, final double[] rhs)

Tests if two double[]s are equal.

Parameters
fieldName:String

the field name.

lhs:double[]

the left-hand side double[].

rhs:double[]

the right-hand side double[].

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final float lhs, final float rhs)

Test if two floats are equal.

Parameters
fieldName:String

the field name.

lhs:float

the left-hand side float.

rhs:float

the right-hand side float.

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final float[] lhs, final float[] rhs)

Tests if two float[]s are equal.

Parameters
fieldName:String

the field name.

lhs:float[]

the left-hand side float[].

rhs:float[]

the right-hand side float[].

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final int lhs, final int rhs)

Tests if two ints are equal.

Parameters
fieldName:String

the field name.

lhs:int

the left-hand side int.

rhs:int

the right-hand side int.

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final int[] lhs, final int[] rhs)

Tests if two int[]s are equal.

Parameters
fieldName:String

the field name.

lhs:int[]

the left-hand side int[].

rhs:int[]

the right-hand side int[].

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final long lhs, final long rhs)

Tests if two longs are equal.

Parameters
fieldName:String

the field name.

lhs:long

the left-hand side long.

rhs:long

the right-hand side long.

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final long[] lhs, final long[] rhs)

Tests if two long[]s are equal.

Parameters
fieldName:String

the field name.

lhs:long[]

the left-hand side long[].

rhs:long[]

the right-hand side long[].

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final Object lhs, final Object rhs)

Tests if two Objectss are equal.

Parameters
fieldName:String

the field name.

lhs:Object

the left-hand side Object.

rhs:Object

the right-hand side Object.

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final Object[] lhs, final Object[] rhs)

Tests if two Object[]s are equal.

Parameters
fieldName:String

the field name.

lhs:Object[]

the left-hand side Object[].

rhs:Object[]

the right-hand side Object[].

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final short lhs, final short rhs)

Tests if two shorts are equal.

Parameters
fieldName:String

the field name.

lhs:short

the left-hand side short.

rhs:short

the right-hand side short.

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
appendback to summary
public DiffBuilder<T> append(final String fieldName, final short[] lhs, final short[] rhs)

Tests if two short[]s are equal.

Parameters
fieldName:String

the field name.

lhs:short[]

the left-hand side short[].

rhs:short[]

the right-hand side short[].

Returns:DiffBuilder<T>

this instance.

Exceptions
NullPointerException:
if field name is null.
buildback to summary
public DiffResult<T> build()

Implements org.apache.commons.lang3.builder.Builder.build.

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

Returns:DiffResult<T>

a DiffResult containing the differences between the two objects.

Annotations
@Override
builderback to summary
public static <T> DiffBuilder.Builder<T> builder()

Constructs a new Builder.

Parameters
<T>
type of the left and right object.
Returns:DiffBuilder.Builder<T>

a new Builder.

Since
3.15.0
getLeftback to summary
pack-priv T getLeft()

Gets the left object.

Returns:T

the left object.

getRightback to summary
pack-priv T getRight()

Gets the right object.

Returns:T

the right object.

org.apache.commons.lang3.builder back to summary

public final Class DiffBuilder.Builder<T>

extends Object
Class Inheritance
Type Parameters
<T>
type of the left and right object.
Constructs a new instance.
Since
3.15.0

Field Summary

Modifier and TypeField and Description
private T
left

private T
right

private ToStringStyle
style

private boolean
testObjectsEquals

private String
toStringFormat

Constructor Summary

AccessConstructor and Description
public
Builder()

Constructs a new instance.

Method Summary

Modifier and TypeMethod and Description
public DiffBuilder<T>

Returns:

a new configured DiffBuilder.
build()

Builds a new configured DiffBuilder.

public DiffBuilder.Builder<T>

Returns:

this instance.
setLeft(final T
the left object.
left)

Sets the left object.

public DiffBuilder.Builder<T>

Returns:

this instance.
setRight(final T
the left object.
right)

Sets the right object.

public DiffBuilder.Builder<T>

Returns:

this instance.
setStyle(final ToStringStyle
the style to use when outputting the objects, null uses the default.
style)

Sets the style will to use when outputting the objects, null uses the default.

public DiffBuilder.Builder<T>

Returns:

this instance.
setTestObjectsEquals(final boolean
If true, this will test if lhs and rhs are the same or equal. All of the append(fieldName, left, right) 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.
testObjectsEquals)

Sets whether to test if left and right are the same or equal.

public DiffBuilder.Builder<T>

Returns:

this instance.
setToStringFormat(final String
null uses the default.
toStringFormat)

Sets the two-argument format string for String#format(String, Object...), for example "%s differs from %s".

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

leftback to summary
private T left
rightback to summary
private T right
styleback to summary
private ToStringStyle style
testObjectsEqualsback to summary
private boolean testObjectsEquals
toStringFormatback to summary
private String toStringFormat

Constructor Detail

Builderback to summary
public Builder()

Constructs a new instance.

Method Detail

buildback to summary
public DiffBuilder<T> build()

Builds a new configured DiffBuilder.

Returns:DiffBuilder<T>

a new configured DiffBuilder.

setLeftback to summary
public DiffBuilder.Builder<T> setLeft(final T left)

Sets the left object.

Parameters
left:T

the left object.

Returns:DiffBuilder.Builder<T>

this instance.

setRightback to summary
public DiffBuilder.Builder<T> setRight(final T right)

Sets the right object.

Parameters
right:T

the left object.

Returns:DiffBuilder.Builder<T>

this instance.

setStyleback to summary
public DiffBuilder.Builder<T> setStyle(final ToStringStyle style)

Sets the style will to use when outputting the objects, null uses the default.

Parameters
style:ToStringStyle

the style to use when outputting the objects, null uses the default.

Returns:DiffBuilder.Builder<T>

this instance.

setTestObjectsEqualsback to summary
public DiffBuilder.Builder<T> setTestObjectsEquals(final boolean testObjectsEquals)

Sets whether to test if left and right are the same or equal. All of the append(fieldName, left, right) 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.

Parameters
testObjectsEquals:boolean

If true, this will test if lhs and rhs are the same or equal. All of the append(fieldName, left, right) 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.

Returns:DiffBuilder.Builder<T>

this instance.

setToStringFormatback to summary
public DiffBuilder.Builder<T> setToStringFormat(final String toStringFormat)

Sets the two-argument format string for String#format(String, Object...), for example "%s differs from %s".

Parameters
toStringFormat:String

null uses the default.

Returns:DiffBuilder.Builder<T>

this instance.

org.apache.commons.lang3.builder back to summary

private final Class DiffBuilder.SDiff<T>

extends Diff<T>
Class Inheritance

Field Summary

Modifier and TypeField and Description
private final DiffBuilder.SerializableSupplier<T>
leftSupplier

private final DiffBuilder.SerializableSupplier<T>
rightSupplier

private static final long
serialVersionUID

Hides org.apache.commons.lang3.builder.Diff.serialVersionUID.

Constructor Summary

AccessConstructor and Description
private
SDiff(final String fieldName, final DiffBuilder.SerializableSupplier<T> leftSupplier, final DiffBuilder.SerializableSupplier<T> rightSupplier, final Class<T> type)

Method Summary

Modifier and TypeMethod and Description
public T
getLeft()

Implements abstract org.apache.commons.lang3.tuple.Pair.getLeft.

Gets the left element from this pair.

public T
getRight()

Implements abstract org.apache.commons.lang3.tuple.Pair.getRight.

Gets the right element from this pair.

Inherited from org.apache.commons.lang3.builder.Diff:
getFieldNamegetTypesetValuetoString

Field Detail

leftSupplierback to summary
private final DiffBuilder.SerializableSupplier<T> leftSupplier
rightSupplierback to summary
private final DiffBuilder.SerializableSupplier<T> rightSupplier
serialVersionUIDback to summary
private static final long serialVersionUID

Hides org.apache.commons.lang3.builder.Diff.serialVersionUID.

Constructor Detail

SDiffback to summary
private SDiff(final String fieldName, final DiffBuilder.SerializableSupplier<T> leftSupplier, final DiffBuilder.SerializableSupplier<T> rightSupplier, final Class<T> type)

Method Detail

getLeftback to summary
public T getLeft()

Implements abstract org.apache.commons.lang3.tuple.Pair.getLeft.

Doc from org.apache.commons.lang3.tuple.Pair.getLeft.

Gets the left element from this pair.

When treated as a key-value pair, this is the key.

Annotations
@Override
getRightback to summary
public T getRight()

Implements abstract org.apache.commons.lang3.tuple.Pair.getRight.

Doc from org.apache.commons.lang3.tuple.Pair.getRight.

Gets the right element from this pair.

When treated as a key-value pair, this is the value.

Annotations
@Override
org.apache.commons.lang3.builder back to summary

private Interface DiffBuilder.SerializableSupplier<T>

extends Supplier<T>, Serializable
Type Parameters
<T>
the type of results supplied by this supplier.
Private interface while we still have to support serialization.

Method Summary

Inherited from java.util.function.Supplier:
get