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 * https://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 024import org.apache.commons.lang3.StringUtils; 025 026/** 027 * A {@link DiffResult} contains a collection of the differences between two 028 * {@link Diffable} objects. Typically these differences are displayed using 029 * {@link #toString()} method, which returns a string describing the fields that 030 * differ between the objects. 031 * 032 * <p> 033 * Use a {@link DiffBuilder} to build a {@link DiffResult} comparing two objects. 034 * </p> 035 * @param <T> type of the left and right object. 036 * @since 3.3 037 */ 038public class DiffResult<T> implements Iterable<Diff<?>> { 039 040 /** 041 * The {@link String} returned when the objects have no differences: 042 * {@value} 043 */ 044 public static final String OBJECTS_SAME_STRING = StringUtils.EMPTY; 045 046 private final List<Diff<?>> diffList; 047 private final T lhs; 048 private final T rhs; 049 private final ToStringStyle style; 050 private final String toStringFormat; 051 052 /** 053 * Creates a {@link DiffResult} containing the differences between two 054 * objects. 055 * 056 * @param lhs 057 * the left-hand side object 058 * @param rhs 059 * the right-hand side object 060 * @param diffList 061 * the list of differences, may be empty 062 * @param style 063 * the style to use for the {@link #toString()} method. May be 064 * {@code null}, in which case 065 * {@link ToStringStyle#DEFAULT_STYLE} is used 066 * @param toStringFormat 067 * Two-argument format string for {@link String#format(String, Object...)}, for example {@code "%s differs from %s"}. 068 * @throws NullPointerException if {@code lhs}, {@code rhs} or {@code diffs} are {@code null}. 069 */ 070 DiffResult(final T lhs, final T rhs, final List<Diff<?>> diffList, final ToStringStyle style, final String toStringFormat) { 071 this.diffList = Objects.requireNonNull(diffList, "diffList"); 072 this.lhs = Objects.requireNonNull(lhs, "lhs"); 073 this.rhs = Objects.requireNonNull(rhs, "rhs"); 074 this.style = Objects.requireNonNull(style, "style"); 075 this.toStringFormat = Objects.requireNonNull(toStringFormat, "toStringFormat"); 076 } 077 078 /** 079 * Gets an unmodifiable list of {@link Diff}s. The list may be empty if 080 * there were no differences between the objects. 081 * 082 * @return an unmodifiable list of {@link Diff}s 083 */ 084 public List<Diff<?>> getDiffs() { 085 return Collections.unmodifiableList(diffList); 086 } 087 088 /** 089 * Gets the object the right object has been compared to. 090 * 091 * @return the left object of the diff 092 * @since 3.10 093 */ 094 public T getLeft() { 095 return this.lhs; 096 } 097 098 /** 099 * Gets the number of differences between the two objects. 100 * 101 * @return the number of differences 102 */ 103 public int getNumberOfDiffs() { 104 return diffList.size(); 105 } 106 107 /** 108 * Gets the object the left object has been compared to. 109 * 110 * @return the right object of the diff 111 * @since 3.10 112 */ 113 public T getRight() { 114 return this.rhs; 115 } 116 117 /** 118 * Gets the style used by the {@link #toString()} method. 119 * 120 * @return the style 121 */ 122 public ToStringStyle getToStringStyle() { 123 return style; 124 } 125 126 /** 127 * Returns an iterator over the {@link Diff} objects contained in this list. 128 * 129 * @return the iterator 130 */ 131 @Override 132 public Iterator<Diff<?>> iterator() { 133 return diffList.iterator(); 134 } 135 136 /** 137 * Builds a {@link String} description of the differences contained within 138 * this {@link DiffResult}. A {@link ToStringBuilder} is used for each object 139 * and the style of the output is governed by the {@link ToStringStyle} 140 * passed to the constructor. 141 * 142 * <p> 143 * If there are no differences stored in this list, the method will return 144 * {@link #OBJECTS_SAME_STRING}. Otherwise, using the example given in 145 * {@link Diffable} and {@link ToStringStyle#SHORT_PREFIX_STYLE}, an output 146 * might be: 147 * </p> 148 * 149 * <pre> 150 * Person[name=John Doe,age=32] differs from Person[name=Joe Bloggs,age=26] 151 * </pre> 152 * 153 * <p> 154 * This indicates that the objects differ in name and age, but not in 155 * smoking status. 156 * </p> 157 * 158 * <p> 159 * To use a different {@link ToStringStyle} for an instance of this class, 160 * use {@link #toString(ToStringStyle)}. 161 * </p> 162 * 163 * @return a {@link String} description of the differences. 164 */ 165 @Override 166 public String toString() { 167 return toString(style); 168 } 169 170 /** 171 * Builds a {@link String} description of the differences contained within 172 * this {@link DiffResult}, using the supplied {@link ToStringStyle}. 173 * 174 * @param style 175 * the {@link ToStringStyle} to use when outputting the objects 176 * 177 * @return a {@link String} description of the differences. 178 */ 179 public String toString(final ToStringStyle style) { 180 if (diffList.isEmpty()) { 181 return OBJECTS_SAME_STRING; 182 } 183 184 final ToStringBuilder lhsBuilder = new ToStringBuilder(lhs, style); 185 final ToStringBuilder rhsBuilder = new ToStringBuilder(rhs, style); 186 187 diffList.forEach(diff -> { 188 lhsBuilder.append(diff.getFieldName(), diff.getLeft()); 189 rhsBuilder.append(diff.getFieldName(), diff.getRight()); 190 }); 191 192 return String.format(toStringFormat, lhsBuilder.build(), rhsBuilder.build()); 193 } 194}