    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.lang.reflect.Type;
    020import java.util.Objects;
    021
    022import org.apache.commons.lang3.ObjectUtils;
    023import org.apache.commons.lang3.reflect.TypeUtils;
    024import org.apache.commons.lang3.tuple.Pair;
    025
    026/**
    027 * A {@link Diff} contains the differences between two {@link Diffable} class fields.
    028 *
    029 * <p>
    030 * Typically, {@link Diff}s are retrieved by using a {@link DiffBuilder} to produce a {@link DiffResult}, containing the differences between two objects.
    031 * </p>
    032 *
    033 * @param <T> The type of object contained within this {@link Diff}. Differences between primitive objects are stored as their Object wrapper equivalent.
    034 * @since 3.3
    035 */
    036public abstract class Diff<T> extends Pair<T, T> {
    037
    038    private static final long serialVersionUID = 1L;
    039
    040    /** The field type. */
    041    private final Type type;
    042
    043    /** The field name. */
    044    private final String fieldName;
    045
    046    /**
    047     * Constructs a new {@link Diff} for the given field name.
    048     *
    049     * @param fieldName
    050     *            the field name.
    051     */
    052    protected Diff(final String fieldName) {
    053        this.fieldName = Objects.requireNonNull(fieldName);
    054        this.type = ObjectUtils.getIfNull(TypeUtils.getTypeArguments(getClass(), Diff.class).get(Diff.class.getTypeParameters()[0]), Object.class);
    055    }
    056
    057    Diff(final String fieldName, final Type type) {
    058        this.fieldName = Objects.requireNonNull(fieldName);
    059        this.type = Objects.requireNonNull(type);
    060    }
    061
    062    /**
    063     * Gets the name of the field.
    064     *
    065     * @return the field name.
    066     */
    067    public final String getFieldName() {
    068        return fieldName;
    069    }
    070
    071    /**
    072     * Gets the type of the field.
    073     *
    074     * @return the field type.
    075     * @deprecated Unused, will be removed in 4.0.0.
    076     */
    077    @Deprecated
    078    public final Type getType() {
    079        return type;
    080    }
    081
    082    /**
    083     * Throws {@link UnsupportedOperationException}.
    084     *
    085     * @param value
    086     *            ignored.
    087     * @return Throws {@link UnsupportedOperationException}.
    088     */
    089    @Override
    090    public final T setValue(final T value) {
    091        throw new UnsupportedOperationException("Cannot alter Diff object.");
    092    }
    093
    094    /**
    095     * Returns a {@link String} representation of the {@link Diff}, with the
    096     * following format:
    097     *
    098     * <pre>
    099     * [fieldname: left-value, right-value]
    100     * </pre>
    101     *
    102     * @return the string representation.
    103     */
    104    @Override
    105    public final String toString() {
    106        return String.format("[%s: %s, %s]", fieldName, getLeft(), getRight());
    107    }
    108}