All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.apache.commons.lang3.builder.DiffResult Maven / Gradle / Ivy

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

import java.util.Collections;
import java.util.Iterator;
import java.util.List;

import org.apache.commons.lang3.Validate;

/**
 * 

* A {@code DiffResult} contains a collection of the differences between two * {@link Diffable} objects. Typically these differences are displayed using * {@link #toString()} method, which returns a string describing the fields that * differ between the objects. *

*

* Use a {@link DiffBuilder} to build a {@code DiffResult} comparing two objects. *

* @param type of the left and right object. * * @since 3.3 */ public class DiffResult implements Iterable> { /** *

* The {@code String} returned when the objects have no differences: * {@value} *

*/ public static final String OBJECTS_SAME_STRING = ""; private static final String DIFFERS_STRING = "differs from"; private final List> diffList; private final T lhs; private final T rhs; private final ToStringStyle style; /** *

* Creates a {@link DiffResult} containing the differences between two * objects. *

* * @param lhs * the left hand object * @param rhs * the right hand object * @param diffList * the list of differences, may be empty * @param style * the style to use for the {@link #toString()} method. May be * {@code null}, in which case * {@link ToStringStyle#DEFAULT_STYLE} is used * @throws NullPointerException if {@code lhs}, {@code rhs} or {@code diffs} is {@code null} */ DiffResult(final T lhs, final T rhs, final List> diffList, final ToStringStyle style) { Validate.notNull(lhs, "lhs"); Validate.notNull(rhs, "rhs"); Validate.notNull(diffList, "diffList"); this.diffList = diffList; this.lhs = lhs; this.rhs = rhs; if (style == null) { this.style = ToStringStyle.DEFAULT_STYLE; } else { this.style = style; } } /** *

Returns the object the right object has been compared to.

* * @return the left object of the diff * @since 3.10 */ public T getLeft() { return this.lhs; } /** *

Returns the object the left object has been compared to.

* * @return the right object of the diff * @since 3.10 */ public T getRight() { return this.rhs; } /** *

* Returns an unmodifiable list of {@code Diff}s. The list may be empty if * there were no differences between the objects. *

* * @return an unmodifiable list of {@code Diff}s */ public List> getDiffs() { return Collections.unmodifiableList(diffList); } /** *

* Returns the number of differences between the two objects. *

* * @return the number of differences */ public int getNumberOfDiffs() { return diffList.size(); } /** *

* Returns the style used by the {@link #toString()} method. *

* * @return the style */ public ToStringStyle getToStringStyle() { return style; } /** *

* Builds a {@code String} description of the differences contained within * this {@code DiffResult}. A {@link ToStringBuilder} is used for each object * and the style of the output is governed by the {@code ToStringStyle} * passed to the constructor. *

* *

* If there are no differences stored in this list, the method will return * {@link #OBJECTS_SAME_STRING}. Otherwise, using the example given in * {@link Diffable} and {@link ToStringStyle#SHORT_PREFIX_STYLE}, an output * might be: *

* *
     * Person[name=John Doe,age=32] differs from Person[name=Joe Bloggs,age=26]
     * 
* *

* This indicates that the objects differ in name and age, but not in * smoking status. *

* *

* To use a different {@code ToStringStyle} for an instance of this class, * use {@link #toString(ToStringStyle)}. *

* * @return a {@code String} description of the differences. */ @Override public String toString() { return toString(style); } /** *

* Builds a {@code String} description of the differences contained within * this {@code DiffResult}, using the supplied {@code ToStringStyle}. *

* * @param style * the {@code ToStringStyle} to use when outputting the objects * * @return a {@code String} description of the differences. */ public String toString(final ToStringStyle style) { if (diffList.isEmpty()) { return OBJECTS_SAME_STRING; } final ToStringBuilder lhsBuilder = new ToStringBuilder(lhs, style); final ToStringBuilder rhsBuilder = new ToStringBuilder(rhs, style); for (final Diff diff : diffList) { lhsBuilder.append(diff.getFieldName(), diff.getLeft()); rhsBuilder.append(diff.getFieldName(), diff.getRight()); } return String.format("%s %s %s", lhsBuilder.build(), DIFFERS_STRING, rhsBuilder.build()); } /** *

* Returns an iterator over the {@code Diff} objects contained in this list. *

* * @return the iterator */ @Override public Iterator> iterator() { return diffList.iterator(); } }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy