001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.lang3.builder; 018 019import java.util.Collections; 020import java.util.Iterator; 021import java.util.List; 022import java.util.Objects; 023 024/** 025 * A {@link DiffResult} contains a collection of the differences between two 026 * {@link Diffable} objects. Typically these differences are displayed using 027 * {@link #toString()} method, which returns a string describing the fields that 028 * differ between the objects. 029 * 030 * <p> 031 * Use a {@link DiffBuilder} to build a {@link DiffResult} comparing two objects. 032 * </p> 033 * @param <T> type of the left and right object. 034 * 035 * @since 3.3 036 */ 037public class DiffResult<T> implements Iterable<Diff<?>> { 038 039 /** 040 * The {@link String} returned when the objects have no differences: 041 * {@value} 042 * 043 */ 044 public static final String OBJECTS_SAME_STRING = ""; 045 046 private static final String DIFFERS_STRING = "differs from"; 047 048 private final List<Diff<?>> diffList; 049 private final T lhs; 050 private final T rhs; 051 private final ToStringStyle style; 052 053 /** 054 * Creates a {@link DiffResult} containing the differences between two 055 * objects. 056 * 057 * @param lhs 058 * the left-hand object 059 * @param rhs 060 * the right-hand object 061 * @param diffList 062 * the list of differences, may be empty 063 * @param style 064 * the style to use for the {@link #toString()} method. May be 065 * {@code null}, in which case 066 * {@link ToStringStyle#DEFAULT_STYLE} is used 067 * @throws NullPointerException if {@code lhs}, {@code rhs} or {@code diffs} is {@code null} 068 */ 069 DiffResult(final T lhs, final T rhs, final List<Diff<?>> diffList, 070 final ToStringStyle style) { 071 Objects.requireNonNull(lhs, "lhs"); 072 Objects.requireNonNull(rhs, "rhs"); 073 Objects.requireNonNull(diffList, "diffList"); 074 075 this.diffList = diffList; 076 this.lhs = lhs; 077 this.rhs = rhs; 078 079 if (style == null) { 080 this.style = ToStringStyle.DEFAULT_STYLE; 081 } else { 082 this.style = style; 083 } 084 } 085 086 /** 087 * Returns the object the right object has been compared to. 088 * 089 * @return the left object of the diff 090 * @since 3.10 091 */ 092 public T getLeft() { 093 return this.lhs; 094 } 095 096 /** 097 * Returns the object the left object has been compared to. 098 * 099 * @return the right object of the diff 100 * @since 3.10 101 */ 102 public T getRight() { 103 return this.rhs; 104 } 105 106 /** 107 * Returns an unmodifiable list of {@link Diff}s. The list may be empty if 108 * there were no differences between the objects. 109 * 110 * @return an unmodifiable list of {@link Diff}s 111 */ 112 public List<Diff<?>> getDiffs() { 113 return Collections.unmodifiableList(diffList); 114 } 115 116 /** 117 * Returns the number of differences between the two objects. 118 * 119 * @return the number of differences 120 */ 121 public int getNumberOfDiffs() { 122 return diffList.size(); 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 * Builds a {@link String} description of the differences contained within 136 * this {@link DiffResult}. A {@link ToStringBuilder} is used for each object 137 * and the style of the output is governed by the {@link ToStringStyle} 138 * passed to the constructor. 139 * 140 * <p> 141 * If there are no differences stored in this list, the method will return 142 * {@link #OBJECTS_SAME_STRING}. Otherwise, using the example given in 143 * {@link Diffable} and {@link ToStringStyle#SHORT_PREFIX_STYLE}, an output 144 * might be: 145 * </p> 146 * 147 * <pre> 148 * Person[name=John Doe,age=32] differs from Person[name=Joe Bloggs,age=26] 149 * </pre> 150 * 151 * <p> 152 * This indicates that the objects differ in name and age, but not in 153 * smoking status. 154 * </p> 155 * 156 * <p> 157 * To use a different {@link ToStringStyle} for an instance of this class, 158 * use {@link #toString(ToStringStyle)}. 159 * </p> 160 * 161 * @return a {@link String} description of the differences. 162 */ 163 @Override 164 public String toString() { 165 return toString(style); 166 } 167 168 /** 169 * Builds a {@link String} description of the differences contained within 170 * this {@link DiffResult}, using the supplied {@link ToStringStyle}. 171 * 172 * @param style 173 * the {@link ToStringStyle} to use when outputting the objects 174 * 175 * @return a {@link String} description of the differences. 176 */ 177 public String toString(final ToStringStyle style) { 178 if (diffList.isEmpty()) { 179 return OBJECTS_SAME_STRING; 180 } 181 182 final ToStringBuilder lhsBuilder = new ToStringBuilder(lhs, style); 183 final ToStringBuilder rhsBuilder = new ToStringBuilder(rhs, style); 184 185 diffList.forEach(diff -> { 186 lhsBuilder.append(diff.getFieldName(), diff.getLeft()); 187 rhsBuilder.append(diff.getFieldName(), diff.getRight()); 188 }); 189 190 return String.format("%s %s %s", lhsBuilder.build(), DIFFERS_STRING, rhsBuilder.build()); 191 } 192 193 /** 194 * Returns an iterator over the {@link Diff} objects contained in this list. 195 * 196 * @return the iterator 197 */ 198 @Override 199 public Iterator<Diff<?>> iterator() { 200 return diffList.iterator(); 201 } 202}