1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.lang3.builder;
18
19 import java.lang.reflect.Type;
20 import java.util.Objects;
21
22 import org.apache.commons.lang3.ObjectUtils;
23 import org.apache.commons.lang3.reflect.TypeUtils;
24 import org.apache.commons.lang3.tuple.Pair;
25
26 /**
27 * A {@link Diff} contains the differences between two {@link Diffable} class fields.
28 *
29 * <p>
30 * Typically, {@link Diff}s are retrieved by using a {@link DiffBuilder} to produce a {@link DiffResult}, containing the differences between two objects.
31 * </p>
32 *
33 * @param <T> The type of object contained within this {@link Diff}. Differences between primitive objects are stored as their Object wrapper equivalent.
34 * @since 3.3
35 */
36 public abstract class Diff<T> extends Pair<T, T> {
37
38 private static final long serialVersionUID = 1L;
39
40 /** The field type. */
41 private final Type type;
42
43 /** The field name. */
44 private final String fieldName;
45
46 /**
47 * Constructs a new {@link Diff} for the given field name.
48 *
49 * @param fieldName
50 * the field name.
51 */
52 protected Diff(final String fieldName) {
53 this.fieldName = Objects.requireNonNull(fieldName);
54 this.type = ObjectUtils.getIfNull(TypeUtils.getTypeArguments(getClass(), Diff.class).get(Diff.class.getTypeParameters()[0]), Object.class);
55 }
56
57 Diff(final String fieldName, final Type type) {
58 this.fieldName = Objects.requireNonNull(fieldName);
59 this.type = Objects.requireNonNull(type);
60 }
61
62 /**
63 * Gets the name of the field.
64 *
65 * @return the field name.
66 */
67 public final String getFieldName() {
68 return fieldName;
69 }
70
71 /**
72 * Gets the type of the field.
73 *
74 * @return the field type.
75 * @deprecated Unused, will be removed in 4.0.0.
76 */
77 @Deprecated
78 public final Type getType() {
79 return type;
80 }
81
82 /**
83 * Throws {@link UnsupportedOperationException}.
84 *
85 * @param value
86 * ignored.
87 * @return Throws {@link UnsupportedOperationException}.
88 */
89 @Override
90 public final T setValue(final T value) {
91 throw new UnsupportedOperationException("Cannot alter Diff object.");
92 }
93
94 /**
95 * Returns a {@link String} representation of the {@link Diff}, with the
96 * following format:
97 *
98 * <pre>
99 * [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 }