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.juneau.marshall.utils;
018
019import static org.apache.juneau.commons.utils.CollectionUtils.*;
020import static org.apache.juneau.commons.utils.Shorts.*;
021
022import java.util.*;
023
024import org.apache.juneau.commons.collections.*;
025import org.apache.juneau.marshall.*;
026import org.apache.juneau.marshall.collections.*;
027
028/**
029 * Utility class for comparing two versions of a POJO.
030 *
031 *
032 * <p class='bjava'>
033 *    <jc>// Two beans to compare.</jc>
034 *    MyBean <jv>bean1</jv>, <jv>bean2</jv>;
035 *
036 * <jc>// Get differences.</jc>
037 *    BeanDiff <jv>beanDiff</jv> = BeanDiff.<jsm>create</jsm>(<jv>bean1</jv>, <jv>bean2</jv>).exclude(<js>"fooProperty"</js>).build();
038 *
039 *    <jc>// Check for differences.</jc>
040 *    <jk>boolean</jk> <jv>hasDiff</jv> = <jv>beanDiff</jv>.hasDiffs();
041 *
042 *    JsonMap <jv>v1Diffs</jv> = <jv>beanDiff</jv>.getV1();  <jc>// Get version 1 differences.</jc>
043 *    JsonMap <jv>v2Diffs</jv> = <jv>beanDiff</jv>.getV2();  <jc>// Get version 2 differences.</jc>
044 *
045 *    <jc>// Display differences.</jc>
046 *    System.<jsf>err</jsf>.println(<jv>beanDiff</jv>);
047 * </p>
048 *
049 */
050@SuppressWarnings({
051   "java:S1192" // Duplicated literals (argument/property names) read more clearly inline than as constants
052})
053public class BeanDiff {
054
055   /**
056    * Builder class.
057    *
058    * @param <T> The bean type.
059    */
060   public static class Builder<T> {
061      T first;
062      T second;
063      MarshallingContext marshallingContext = MarshallingContext.DEFAULT;
064      Set<String> include;
065      Set<String> exclude;
066
067      /**
068       * Specifies the bean context to use for introspecting beans.
069       *
070       * <p>
071       * If not specified, uses {@link MarshallingContext#DEFAULT}.
072       *
073       * @param value The bean context to use for introspecting beans.
074       * @return This object.
075       */
076      public Builder<T> marshallingContext(MarshallingContext value) {
077         marshallingContext = value;
078         return this;
079      }
080
081      /**
082       * Build the differences.
083       *
084       * @return A new {@link BeanDiff} object.
085       */
086      public BeanDiff build() {
087         return new BeanDiff(marshallingContext, first, second, include, exclude);
088      }
089
090      /**
091       * Specifies the properties to exclude from the comparison.
092       *
093       * @param properties The properties to exclude from the comparison.
094       * @return This object.
095       */
096      public Builder<T> exclude(Set<String> properties) {
097         exclude = properties;
098         return this;
099      }
100
101      /**
102       * Specifies the properties to exclude from the comparison.
103       *
104       * @param properties The properties to exclude from the comparison.
105       * @return This object.
106       */
107      public Builder<T> exclude(String...properties) {
108         exclude = set(properties);
109         return this;
110      }
111
112      /**
113       * Specifies the first bean to compare.
114       *
115       * @param value The first bean to compare.
116       * @return This object.
117       */
118      public Builder<T> first(T value) {
119         first = value;
120         return this;
121      }
122
123      /**
124       * Specifies the properties to include in the comparison.
125       *
126       * <p>
127       * If not specified, compares all properties.
128       *
129       * @param properties The properties to include in the comparison.
130       * @return This object.
131       */
132      public Builder<T> include(Set<String> properties) {
133         include = properties;
134         return this;
135      }
136
137      /**
138       * Specifies the properties to include in the comparison.
139       *
140       * <p>
141       * If not specified, compares all properties.
142       *
143       * @param properties The properties to include in the comparison.
144       * @return This object.
145       */
146      public Builder<T> include(String...properties) {
147         include = set(properties);
148         return this;
149      }
150
151      /**
152       * Specifies the second bean to compare.
153       *
154       * @param value The first bean to compare.
155       * @return This object.
156       */
157      public Builder<T> second(T value) {
158         second = value;
159         return this;
160      }
161   }
162
163   /**
164    * Create a new builder for this class.
165    *
166    * @param <T> The bean types.
167    * @param first The first bean to compare.
168    * @param second The second bean to compare.
169    * @return A new builder.
170    */
171   public static <T> Builder<T> create(T first, T second) {
172      return new Builder<T>().first(first).second(second);
173   }
174
175   private final JsonMap v1 = new JsonMap();
176   private final JsonMap v2 = new JsonMap();
177
178   /**
179    * Constructor.
180    *
181    * @param <T> The bean types.
182    * @param bc The bean context to use for comparing beans.
183    * @param first The first bean to compare.  Can be <jk>null</jk> (treated as an empty bean with no properties).
184    * @param second The second bean to compare.  Can be <jk>null</jk> (treated as an empty bean with no properties).
185    * @param include
186    *    Optional properties to include in the comparison.
187    *    <br>If <jk>null</jk>, all properties are included.
188    * @param exclude
189    *    Optional properties to exclude in the comparison.
190    *    <br>If <jk>null</jk>, no properties are excluded.
191    */
192   @SuppressWarnings({
193      "java:S3776", // Cognitive complexity acceptable for this specific logic
194      "null" // Null handling verified by context or framework
195   })
196   public <T> BeanDiff(MarshallingContext bc, T first, T second, Set<String> include, Set<String> exclude) {
197      if (first == null && second == null)
198         return;
199      var bm1 = first == null ? null : bc.toBeanMap(first);
200      var bm2 = second == null ? null : bc.toBeanMap(second);
201      var keys = nn(bm1) ? bm1.keySet() : bm2.keySet();
202      keys.forEach(k -> {
203         if ((include == null || include.contains(k)) && (exclude == null || ! exclude.contains(k))) {
204            var o1 = bm1 == null ? null : bm1.get(k);
205            var o2 = bm2 == null ? null : bm2.get(k);
206            if (neq(o1, o2)) {
207               if (nn(o1))
208                  v1.put(k, o1);
209               if (nn(o2))
210                  v2.put(k, o2);
211            }
212         }
213      });
214   }
215
216   /**
217    * Returns the differences in the first bean.
218    *
219    * @return The differences in the first bean.
220    */
221   public JsonMap getV1() { return v1; }
222
223   /**
224    * Returns the differences in the second bean.
225    *
226    * @return The differences in the second bean.
227    */
228   public JsonMap getV2() { return v2; }
229
230   /**
231    * Returns <jk>true</jk> if the beans had differences.
232    *
233    * @return <jk>true</jk> if the beans had differences.
234    */
235   public boolean hasDiffs() {
236      return v1.size() > 0 || v2.size() > 0;
237   }
238
239   protected FluentMap<String,Object> properties() {
240      // @formatter:off
241      return mapb_so().buildFluent()
242         .a("v1", v1)
243         .a("v2", v2);
244      // @formatter:on
245   }
246
247   @Override
248   public String toString() {
249      return r(properties());
250   }
251}