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}