ReflectionDiffBuilder.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.lang3.builder;

  19. import java.lang.reflect.Field;
  20. import java.lang.reflect.Modifier;
  21. import java.util.Arrays;

  23. import org.apache.commons.lang3.ArraySorter;
  24. import org.apache.commons.lang3.ArrayUtils;
  25. import org.apache.commons.lang3.ClassUtils;
  26. import org.apache.commons.lang3.reflect.FieldUtils;

  28. /**
  29.  * Assists in implementing {@link Diffable#diff(Object)} methods.
  30.  *
  31.  * <p>
  32.  * All non-static, non-transient fields (including inherited fields) of the objects to diff are discovered using reflection and compared for differences.
  33.  * </p>
  34.  *
  35.  * <p>
  36.  * To use this class, write code as follows:
  37.  * </p>
  38.  *
  39.  * <pre>{@code
  40.  * public class Person implements Diffable<Person> {
  41.  *   String name;
  42.  *   int age;
  43.  *   boolean smoker;
  44.  *   ...
  45.  *
  46.  *   public DiffResult diff(Person obj) {
  47.  *     // No need for null check, as NullPointerException correct if obj is null
  48.  *     return new ReflectionDiffBuilder.<Person>builder()
  49.  *       .setDiffBuilder(DiffBuilder.<Person>builder()
  50.  *           .setLeft(this)
  51.  *           .setRight(obj)
  52.  *           .setStyle(ToStringStyle.SHORT_PREFIX_STYLE)
  53.  *           .build())
  54.  *       .setExcludeFieldNames("userName", "password")
  55.  *       .build();
  56.  *   }
  57.  * }
  58.  * }</pre>
  59.  *
  60.  * <p>
  61.  * The {@link ToStringStyle} passed to the constructor is embedded in the returned {@link DiffResult} and influences the style of the
  62.  * {@code DiffResult.toString()} method. This style choice can be overridden by calling {@link DiffResult#toString(ToStringStyle)}.
  63.  * </p>
  64.  * <p>
  65.  * See {@link DiffBuilder} for a non-reflection based version of this class.
  66.  * </p>
  67.  *
  68.  * @param <T> type of the left and right object to diff.
  69.  * @see Diffable
  70.  * @see Diff
  71.  * @see DiffResult
  72.  * @see ToStringStyle
  73.  * @see DiffBuilder
  74.  * @since 3.6
  75.  */
  76. public class ReflectionDiffBuilder<T> implements Builder<DiffResult<T>> {

  78.     /**
  79.      * Constructs a new instance.
  80.      *
  81.      * @param <T> type of the left and right object.
  82.      * @since 3.15.0
  83.      */
  84.     public static final class Builder<T> {

  86.         private String[] excludeFieldNames = ArrayUtils.EMPTY_STRING_ARRAY;
  87.         private DiffBuilder<T> diffBuilder;

  89.         /**
  90.          * Constructs a new instance.
  91.          */
  92.         public Builder() {
  93.             // empty
  94.         }

  96.         /**
  97.          * Builds a new configured {@link ReflectionDiffBuilder}.
  98.          *
  99.          * @return a new configured {@link ReflectionDiffBuilder}.
  100.          */
  101.         public ReflectionDiffBuilder<T> build() {
  102.             return new ReflectionDiffBuilder<>(diffBuilder, excludeFieldNames);
  103.         }

  105.         /**
  106.          * Sets the DiffBuilder.
  107.          *
  108.          * @param diffBuilder the DiffBuilder.
  109.          * @return {@code this} instance.
  110.          */
  111.         public Builder<T> setDiffBuilder(final DiffBuilder<T> diffBuilder) {
  112.             this.diffBuilder = diffBuilder;
  113.             return this;
  114.         }

  116.         /**
  117.          * Sets field names to exclude from output. Intended for fields like {@code "password"} or {@code "lastModificationDate"}.
  118.          *
  119.          * @param excludeFieldNames field names to exclude.
  120.          * @return {@code this} instance.
  121.          */
  122.         public Builder<T> setExcludeFieldNames(final String... excludeFieldNames) {
  123.             this.excludeFieldNames = toExcludeFieldNames(excludeFieldNames);
  124.             return this;
  125.         }

  127.     }

  129.     /**
  130.      * Constructs a new {@link Builder}.
  131.      *
  132.      * @param <T> type of the left and right object.
  133.      * @return a new {@link Builder}.
  134.      * @since 3.15.0
  135.      */
  136.     public static <T> Builder<T> builder() {
  137.         return new Builder<>();
  138.     }

  140.     private static String[] toExcludeFieldNames(final String[] excludeFieldNames) {
  141.         if (excludeFieldNames == null) {
  142.             return ArrayUtils.EMPTY_STRING_ARRAY;
  143.         }
  144.         // clone and remove nulls
  145.         return ArraySorter.sort(ReflectionToStringBuilder.toNoNullStringArray(excludeFieldNames));
  146.     }

  148.     private final DiffBuilder<T> diffBuilder;

  150.     /**
  151.      * Field names to exclude from output. Intended for fields like {@code "password"} or {@code "lastModificationDate"}.
  152.      */
  153.     private String[] excludeFieldNames;

  155.     private ReflectionDiffBuilder(final DiffBuilder<T> diffBuilder, final String[] excludeFieldNames) {
  156.         this.diffBuilder = diffBuilder;
  157.         this.excludeFieldNames = excludeFieldNames;
  158.     }

  160.     /**
  161.      * Constructs a builder for the specified objects with the specified style.
  162.      *
  163.      * <p>
  164.      * If {@code left == right} or {@code left.equals(right)} then the builder will not evaluate any calls to {@code append(...)} and will return an empty
  165.      * {@link DiffResult} when {@link #build()} is executed.
  166.      * </p>
  167.      *
  168.      * @param left  {@code this} object.
  169.      * @param right the object to diff against.
  170.      * @param style the style will use when outputting the objects, {@code null} uses the default
  171.      * @throws IllegalArgumentException if {@code left} or {@code right} is {@code null}.
  172.      * @deprecated Use {@link Builder}.
  173.      */
  174.     @Deprecated
  175.     public ReflectionDiffBuilder(final T left, final T right, final ToStringStyle style) {
  176.         this(DiffBuilder.<T>builder().setLeft(left).setRight(right).setStyle(style).build(), null);
  177.     }

  179.     private boolean accept(final Field field) {
  180.         if (field.getName().indexOf(ClassUtils.INNER_CLASS_SEPARATOR_CHAR) != -1) {
  181.             return false;
  182.         }
  183.         if (Modifier.isTransient(field.getModifiers())) {
  184.             return false;
  185.         }
  186.         if (Modifier.isStatic(field.getModifiers())) {
  187.             return false;
  188.         }
  189.         if (this.excludeFieldNames != null && Arrays.binarySearch(this.excludeFieldNames, field.getName()) >= 0) {
  190.             // Reject fields from the getExcludeFieldNames list.
  191.             return false;
  192.         }
  193.         return !field.isAnnotationPresent(DiffExclude.class);
  194.     }

  196.     private void appendFields(final Class<?> clazz) {
  197.         for (final Field field : FieldUtils.getAllFields(clazz)) {
  198.             if (accept(field)) {
  199.                 try {
  200.                     diffBuilder.append(field.getName(), readField(field, getLeft()), readField(field, getRight()));
  201.                 } catch (final IllegalAccessException e) {
  202.                     // this can't happen. Would get a Security exception instead
  203.                     // throw a runtime exception in case the impossible happens.
  204.                     throw new IllegalArgumentException("Unexpected IllegalAccessException: " + e.getMessage(), e);
  205.                 }
  206.             }
  207.         }
  208.     }

  210.     @Override
  211.     public DiffResult<T> build() {
  212.         if (getLeft().equals(getRight())) {
  213.             return diffBuilder.build();
  214.         }

  216.         appendFields(getLeft().getClass());
  217.         return diffBuilder.build();
  218.     }

  220.     /**
  221.      * Gets the field names that should be excluded from the diff.
  222.      *
  223.      * @return Returns the excludeFieldNames.
  224.      * @since 3.13.0
  225.      */
  226.     public String[] getExcludeFieldNames() {
  227.         return this.excludeFieldNames.clone();
  228.     }

  230.     private T getLeft() {
  231.         return diffBuilder.getLeft();
  232.     }

  234.     private T getRight() {
  235.         return diffBuilder.getRight();
  236.     }

  238.     private Object readField(final Field field, final Object target) throws IllegalAccessException {
  239.         return FieldUtils.readField(field, target, true);
  240.     }

  242.     /**
  243.      * Sets the field names to exclude.
  244.      *
  245.      * @param excludeFieldNames The field names to exclude from the diff or {@code null}.
  246.      * @return {@code this}
  247.      * @since 3.13.0
  248.      * @deprecated Use {@link Builder#setExcludeFieldNames(String[])}.
  249.      */
  250.     @Deprecated
  251.     public ReflectionDiffBuilder<T> setExcludeFieldNames(final String... excludeFieldNames) {
  252.         this.excludeFieldNames = toExcludeFieldNames(excludeFieldNames);
  253.         return this;
  254.     }

  256. }
Created with JaCoCo 0.8.12.202403310830