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; 18 19 import java.util.Collections; 20 import java.util.Iterator; 21 import java.util.List; 22 import java.util.Objects; 23 24 /** 25 * A {@link DiffResult} contains a collection of the differences between two 26 * {@link Diffable} objects. Typically these differences are displayed using 27 * {@link #toString()} method, which returns a string describing the fields that 28 * differ between the objects. 29 * 30 * <p> 31 * Use a {@link DiffBuilder} to build a {@link DiffResult} comparing two objects. 32 * </p> 33 * @param <T> type of the left and right object. 34 * 35 * @since 3.3 36 */ 37 public class DiffResult<T> implements Iterable<Diff<?>> { 38 39 /** 40 * The {@link String} returned when the objects have no differences: 41 * {@value} 42 * 43 */ 44 public static final String OBJECTS_SAME_STRING = ""; 45 46 private static final String DIFFERS_STRING = "differs from"; 47 48 private final List<Diff<?>> diffList; 49 private final T lhs; 50 private final T rhs; 51 private final ToStringStyle style; 52 53 /** 54 * Creates a {@link DiffResult} containing the differences between two 55 * objects. 56 * 57 * @param lhs 58 * the left-hand object 59 * @param rhs 60 * the right-hand object 61 * @param diffList 62 * the list of differences, may be empty 63 * @param style 64 * the style to use for the {@link #toString()} method. May be 65 * {@code null}, in which case 66 * {@link ToStringStyle#DEFAULT_STYLE} is used 67 * @throws NullPointerException if {@code lhs}, {@code rhs} or {@code diffs} is {@code null} 68 */ 69 DiffResult(final T lhs, final T rhs, final List<Diff<?>> diffList, 70 final ToStringStyle style) { 71 Objects.requireNonNull(lhs, "lhs"); 72 Objects.requireNonNull(rhs, "rhs"); 73 Objects.requireNonNull(diffList, "diffList"); 74 75 this.diffList = diffList; 76 this.lhs = lhs; 77 this.rhs = rhs; 78 79 if (style == null) { 80 this.style = ToStringStyle.DEFAULT_STYLE; 81 } else { 82 this.style = style; 83 } 84 } 85 86 /** 87 * Returns an unmodifiable list of {@link Diff}s. The list may be empty if 88 * there were no differences between the objects. 89 * 90 * @return an unmodifiable list of {@link Diff}s 91 */ 92 public List<Diff<?>> getDiffs() { 93 return Collections.unmodifiableList(diffList); 94 } 95 96 /** 97 * Returns the object the right object has been compared to. 98 * 99 * @return the left object of the diff 100 * @since 3.10 101 */ 102 public T getLeft() { 103 return this.lhs; 104 } 105 106 /** 107 * Returns the number of differences between the two objects. 108 * 109 * @return the number of differences 110 */ 111 public int getNumberOfDiffs() { 112 return diffList.size(); 113 } 114 115 /** 116 * Returns the object the left object has been compared to. 117 * 118 * @return the right object of the diff 119 * @since 3.10 120 */ 121 public T getRight() { 122 return this.rhs; 123 } 124 125 /** 126 * Returns the style used by the {@link #toString()} method. 127 * 128 * @return the style 129 */ 130 public ToStringStyle getToStringStyle() { 131 return style; 132 } 133 134 /** 135 * Returns an iterator over the {@link Diff} objects contained in this list. 136 * 137 * @return the iterator 138 */ 139 @Override 140 public Iterator<Diff<?>> iterator() { 141 return diffList.iterator(); 142 } 143 144 /** 145 * Builds a {@link String} description of the differences contained within 146 * this {@link DiffResult}. A {@link ToStringBuilder} is used for each object 147 * and the style of the output is governed by the {@link ToStringStyle} 148 * passed to the constructor. 149 * 150 * <p> 151 * If there are no differences stored in this list, the method will return 152 * {@link #OBJECTS_SAME_STRING}. Otherwise, using the example given in 153 * {@link Diffable} and {@link ToStringStyle#SHORT_PREFIX_STYLE}, an output 154 * might be: 155 * </p> 156 * 157 * <pre> 158 * Person[name=John Doe,age=32] differs from Person[name=Joe Bloggs,age=26] 159 * </pre> 160 * 161 * <p> 162 * This indicates that the objects differ in name and age, but not in 163 * smoking status. 164 * </p> 165 * 166 * <p> 167 * To use a different {@link ToStringStyle} for an instance of this class, 168 * use {@link #toString(ToStringStyle)}. 169 * </p> 170 * 171 * @return a {@link String} description of the differences. 172 */ 173 @Override 174 public String toString() { 175 return toString(style); 176 } 177 178 /** 179 * Builds a {@link String} description of the differences contained within 180 * this {@link DiffResult}, using the supplied {@link ToStringStyle}. 181 * 182 * @param style 183 * the {@link ToStringStyle} to use when outputting the objects 184 * 185 * @return a {@link String} description of the differences. 186 */ 187 public String toString(final ToStringStyle style) { 188 if (diffList.isEmpty()) { 189 return OBJECTS_SAME_STRING; 190 } 191 192 final ToStringBuilder lhsBuilder = new ToStringBuilder(lhs, style); 193 final ToStringBuilder rhsBuilder = new ToStringBuilder(rhs, style); 194 195 diffList.forEach(diff -> { 196 lhsBuilder.append(diff.getFieldName(), diff.getLeft()); 197 rhsBuilder.append(diff.getFieldName(), diff.getRight()); 198 }); 199 200 return String.format("%s %s %s", lhsBuilder.build(), DIFFERS_STRING, rhsBuilder.build()); 201 } 202 }