DiffBuilder.java
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.lang3.builder;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Objects;
import java.util.function.Supplier;
import org.apache.commons.lang3.ArrayUtils;
import org.apache.commons.lang3.ObjectUtils;
/**
* Assists in implementing {@link Diffable#diff(Object)} methods.
*
* <p>
* To use this class, write code as follows:
* </p>
*
* <pre>{@code
* 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.<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();
* }
* }
* }</pre>
*
* <p>
* The {@link ToStringStyle} passed to the constructor is embedded in the returned {@link DiffResult} and influences the style of the
* {@code DiffResult.toString()} method. This style choice can be overridden by calling {@link DiffResult#toString(ToStringStyle)}.
* </p>
* <p>
* See {@link ReflectionDiffBuilder} for a reflection based version of this class.
* </p>
*
* @param <T> type of the left and right object.
* @see Diffable
* @see Diff
* @see DiffResult
* @see ToStringStyle
* @see ReflectionDiffBuilder
* @since 3.3
*/
public class DiffBuilder<T> implements Builder<DiffResult<T>> {
/**
* Constructs a new instance.
*
* @param <T> type of the left and right object.
* @since 3.15.0
*/
public static final class Builder<T> {
private T left;
private T right;
private ToStringStyle style;
private boolean testObjectsEquals = true;
private String toStringFormat = TO_STRING_FORMAT;
/**
* Constructs a new instance.
*/
public Builder() {
// empty
}
/**
* Builds a new configured {@link DiffBuilder}.
*
* @return a new configured {@link DiffBuilder}.
*/
public DiffBuilder<T> build() {
return new DiffBuilder<>(left, right, style, testObjectsEquals, toStringFormat);
}
/**
* Sets the left object.
*
* @param left the left object.
* @return {@code this} instance.
*/
public Builder<T> setLeft(final T left) {
this.left = left;
return this;
}
/**
* Sets the right object.
*
* @param right the left object.
* @return {@code this} instance.
*/
public Builder<T> setRight(final T right) {
this.right = right;
return this;
}
/**
* Sets the style will to use when outputting the objects, {@code null} uses the default.
*
* @param style the style to use when outputting the objects, {@code null} uses the default.
* @return {@code this} instance.
*/
public Builder<T> setStyle(final ToStringStyle style) {
this.style = style != null ? style : ToStringStyle.DEFAULT_STYLE;
return this;
}
/**
* 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
* {@link Diff} if the trivially equal test is enabled and returns true. The result of this test is never changed throughout the life of this
* {@link DiffBuilder}.
*
* @param testObjectsEquals 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 {@link Diff} if the trivially equal test is enabled and returns true. The result of this test is
* never changed throughout the life of this {@link DiffBuilder}.
* @return {@code this} instance.
*/
public Builder<T> setTestObjectsEquals(final boolean testObjectsEquals) {
this.testObjectsEquals = testObjectsEquals;
return this;
}
/**
* Sets the two-argument format string for {@link String#format(String, Object...)}, for example {@code "%s differs from %s"}.
*
* @param toStringFormat {@code null} uses the default.
* @return {@code this} instance.
*/
public Builder<T> setToStringFormat(final String toStringFormat) {
this.toStringFormat = toStringFormat != null ? toStringFormat : TO_STRING_FORMAT;
return this;
}
}
private static final class SDiff<T> extends Diff<T> {
private static final long serialVersionUID = 1L;
private final transient Supplier<T> leftSupplier;
private final transient Supplier<T> rightSupplier;
private SDiff(final String fieldName, final Supplier<T> leftSupplier, final Supplier<T> rightSupplier, final Class<T> type) {
super(fieldName, type);
this.leftSupplier = Objects.requireNonNull(leftSupplier);
this.rightSupplier = Objects.requireNonNull(rightSupplier);
}
@Override
public T getLeft() {
return leftSupplier.get();
}
@Override
public T getRight() {
return rightSupplier.get();
}
}
static final String TO_STRING_FORMAT = "%s differs from %s";
/**
* Constructs a new {@link Builder}.
*
* @param <T> type of the left and right object.
* @return a new {@link Builder}.
* @since 3.15.0
*/
public static <T> Builder<T> builder() {
return new Builder<>();
}
private final List<Diff<?>> diffs;
private final boolean equals;
private final T left;
private final T right;
private final ToStringStyle style;
private final String toStringFormat;
/**
* Constructs a builder for the specified objects with the specified style.
*
* <p>
* If {@code lhs == rhs} or {@code lhs.equals(rhs)} then the builder will not evaluate any calls to {@code append(...)} and will return an empty
* {@link DiffResult} when {@link #build()} is executed.
* </p>
*
* <p>
* This delegates to {@link #DiffBuilder(Object, Object, ToStringStyle, boolean)} with the testTriviallyEqual flag enabled.
* </p>
*
* @param left {@code this} object
* @param right the object to diff against
* @param style the style to use when outputting the objects, {@code null} uses the default
* @throws NullPointerException if {@code lhs} or {@code rhs} is {@code null}
* @deprecated Use {@link Builder}.
*/
@Deprecated
public DiffBuilder(final T left, final T right, final ToStringStyle style) {
this(left, right, style, true);
}
/**
* Constructs a builder for the specified objects with the specified style.
*
* <p>
* If {@code lhs == rhs} or {@code lhs.equals(rhs)} then the builder will not evaluate any calls to {@code append(...)} and will return an empty
* {@link DiffResult} when {@link #build()} is executed.
* </p>
*
* @param left {@code this} object
* @param right the object to diff against
* @param style the style to use when outputting the objects, {@code null} uses the default
* @param 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 {@link Diff} if the trivially equal test is enabled and returns true. The result of this test is never changed
* throughout the life of this {@link DiffBuilder}.
* @throws NullPointerException if {@code lhs} or {@code rhs} is {@code null}
* @since 3.4
* @deprecated Use {@link Builder}.
*/
@Deprecated
public DiffBuilder(final T left, final T right, final ToStringStyle style, final boolean testObjectsEquals) {
this(left, right, style, testObjectsEquals, TO_STRING_FORMAT);
}
private DiffBuilder(final T left, final T right, final ToStringStyle style, final boolean testObjectsEquals, final String toStringFormat) {
this.left = Objects.requireNonNull(left, "left");
this.right = Objects.requireNonNull(right, "right");
this.diffs = new ArrayList<>();
this.toStringFormat = toStringFormat;
this.style = style != null ? style : ToStringStyle.DEFAULT_STYLE;
// Don't compare any fields if objects equal
this.equals = testObjectsEquals && Objects.equals(left, right);
}
private <F> DiffBuilder<T> add(final String fieldName, final Supplier<F> left, final Supplier<F> right, final Class<F> type) {
diffs.add(new SDiff<>(fieldName, left, right, type));
return this;
}
/**
* Tests if two {@code boolean}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code boolean}
* @param rhs the right-hand side {@code boolean}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final boolean lhs, final boolean rhs) {
return equals || lhs == rhs ? this : add(fieldName, () -> Boolean.valueOf(lhs), () -> Boolean.valueOf(rhs), Boolean.class);
}
/**
* Tests if two {@code boolean[]}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code boolean[]}
* @param rhs the right-hand side {@code boolean[]}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final boolean[] lhs, final boolean[] rhs) {
return equals || Arrays.equals(lhs, rhs) ? this : add(fieldName, () -> ArrayUtils.toObject(lhs), () -> ArrayUtils.toObject(rhs), Boolean[].class);
}
/**
* Tests if two {@code byte}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code byte}
* @param rhs the right-hand side {@code byte}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final byte lhs, final byte rhs) {
return equals || lhs == rhs ? this : add(fieldName, () -> Byte.valueOf(lhs), () -> Byte.valueOf(rhs), Byte.class);
}
/**
* Tests if two {@code byte[]}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code byte[]}
* @param rhs the right-hand side {@code byte[]}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final byte[] lhs, final byte[] rhs) {
return equals || Arrays.equals(lhs, rhs) ? this : add(fieldName, () -> ArrayUtils.toObject(lhs), () -> ArrayUtils.toObject(rhs), Byte[].class);
}
/**
* Tests if two {@code char}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code char}
* @param rhs the right-hand side {@code char}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final char lhs, final char rhs) {
return equals || lhs == rhs ? this : add(fieldName, () -> Character.valueOf(lhs), () -> Character.valueOf(rhs), Character.class);
}
/**
* Tests if two {@code char[]}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code char[]}
* @param rhs the right-hand side {@code char[]}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final char[] lhs, final char[] rhs) {
return equals || Arrays.equals(lhs, rhs) ? this : add(fieldName, () -> ArrayUtils.toObject(lhs), () -> ArrayUtils.toObject(rhs), Character[].class);
}
/**
* Appends diffs from another {@link DiffResult}.
*
* <p>
* Useful this method to compare properties which are themselves Diffable and would like to know which specific part of it is different.
* </p>
*
* <pre>{@code
* 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();
* }
* }
* }
* </pre>
*
* @param fieldName the field name
* @param diffResult the {@link DiffResult} to append
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null} or diffResult is {@code null}
* @since 3.5
*/
public DiffBuilder<T> append(final String fieldName, final DiffResult<?> diffResult) {
Objects.requireNonNull(diffResult, "diffResult");
if (equals) {
return this;
}
diffResult.getDiffs().forEach(diff -> append(fieldName + "." + diff.getFieldName(), diff.getLeft(), diff.getRight()));
return this;
}
/**
* Tests if two {@code double}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code double}
* @param rhs the right-hand side {@code double}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final double lhs, final double rhs) {
return equals || Double.doubleToLongBits(lhs) == Double.doubleToLongBits(rhs) ? this
: add(fieldName, () -> Double.valueOf(lhs), () -> Double.valueOf(rhs), Double.class);
}
/**
* Tests if two {@code double[]}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code double[]}
* @param rhs the right-hand side {@code double[]}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final double[] lhs, final double[] rhs) {
return equals || Arrays.equals(lhs, rhs) ? this : add(fieldName, () -> ArrayUtils.toObject(lhs), () -> ArrayUtils.toObject(rhs), Double[].class);
}
/**
* Test if two {@code float}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code float}
* @param rhs the right-hand side {@code float}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final float lhs, final float rhs) {
return equals || Float.floatToIntBits(lhs) == Float.floatToIntBits(rhs) ? this
: add(fieldName, () -> Float.valueOf(lhs), () -> Float.valueOf(rhs), Float.class);
}
/**
* Tests if two {@code float[]}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code float[]}
* @param rhs the right-hand side {@code float[]}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final float[] lhs, final float[] rhs) {
return equals || Arrays.equals(lhs, rhs) ? this : add(fieldName, () -> ArrayUtils.toObject(lhs), () -> ArrayUtils.toObject(rhs), Float[].class);
}
/**
* Tests if two {@code int}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code int}
* @param rhs the right-hand side {@code int}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final int lhs, final int rhs) {
return equals || lhs == rhs ? this : add(fieldName, () -> Integer.valueOf(lhs), () -> Integer.valueOf(rhs), Integer.class);
}
/**
* Tests if two {@code int[]}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code int[]}
* @param rhs the right-hand side {@code int[]}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final int[] lhs, final int[] rhs) {
return equals || Arrays.equals(lhs, rhs) ? this : add(fieldName, () -> ArrayUtils.toObject(lhs), () -> ArrayUtils.toObject(rhs), Integer[].class);
}
/**
* Tests if two {@code long}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code long}
* @param rhs the right-hand side {@code long}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final long lhs, final long rhs) {
return equals || lhs == rhs ? this : add(fieldName, () -> Long.valueOf(lhs), () -> Long.valueOf(rhs), Long.class);
}
/**
* Tests if two {@code long[]}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code long[]}
* @param rhs the right-hand side {@code long[]}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final long[] lhs, final long[] rhs) {
return equals || Arrays.equals(lhs, rhs) ? this : add(fieldName, () -> ArrayUtils.toObject(lhs), () -> ArrayUtils.toObject(rhs), Long[].class);
}
/**
* Tests if two {@link Objects}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@link Object}
* @param rhs the right-hand side {@link Object}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final Object lhs, final Object rhs) {
if (equals || lhs == rhs) {
return this;
}
// rhs cannot be null, as lhs != rhs
final Object test = lhs != null ? lhs : rhs;
if (ObjectUtils.isArray(test)) {
if (test instanceof boolean[]) {
return append(fieldName, (boolean[]) lhs, (boolean[]) rhs);
}
if (test instanceof byte[]) {
return append(fieldName, (byte[]) lhs, (byte[]) rhs);
}
if (test instanceof char[]) {
return append(fieldName, (char[]) lhs, (char[]) rhs);
}
if (test instanceof double[]) {
return append(fieldName, (double[]) lhs, (double[]) rhs);
}
if (test instanceof float[]) {
return append(fieldName, (float[]) lhs, (float[]) rhs);
}
if (test instanceof int[]) {
return append(fieldName, (int[]) lhs, (int[]) rhs);
}
if (test instanceof long[]) {
return append(fieldName, (long[]) lhs, (long[]) rhs);
}
if (test instanceof short[]) {
return append(fieldName, (short[]) lhs, (short[]) rhs);
}
return append(fieldName, (Object[]) lhs, (Object[]) rhs);
}
// Not array type
return Objects.equals(lhs, rhs) ? this : add(fieldName, () -> lhs, () -> rhs, Object.class);
}
/**
* Tests if two {@code Object[]}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code Object[]}
* @param rhs the right-hand side {@code Object[]}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final Object[] lhs, final Object[] rhs) {
return equals || Arrays.equals(lhs, rhs) ? this : add(fieldName, () -> lhs, () -> rhs, Object[].class);
}
/**
* Tests if two {@code short}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code short}
* @param rhs the right-hand side {@code short}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final short lhs, final short rhs) {
return equals || lhs == rhs ? this : add(fieldName, () -> Short.valueOf(lhs), () -> Short.valueOf(rhs), Short.class);
}
/**
* Tests if two {@code short[]}s are equal.
*
* @param fieldName the field name
* @param lhs the left-hand side {@code short[]}
* @param rhs the right-hand side {@code short[]}
* @return {@code this} instance.
* @throws NullPointerException if field name is {@code null}
*/
public DiffBuilder<T> append(final String fieldName, final short[] lhs, final short[] rhs) {
return equals || Arrays.equals(lhs, rhs) ? this : add(fieldName, () -> ArrayUtils.toObject(lhs), () -> ArrayUtils.toObject(rhs), Short[].class);
}
/**
* Builds a {@link DiffResult} based on the differences appended to this builder.
*
* @return a {@link DiffResult} containing the differences between the two objects.
*/
@Override
public DiffResult<T> build() {
return new DiffResult<>(left, right, diffs, style, toStringFormat);
}
/**
* Gets the left object.
*
* @return the left object.
*/
T getLeft() {
return left;
}
/**
* Gets the right object.
*
* @return the right object.
*/
T getRight() {
return right;
}
}