org.apache.commons.lang3.builder.CompareToBuilder Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-lang3 Show documentation
Show all versions of commons-lang3 Show documentation
Apache Commons Lang, a package of Java utility classes for the
classes that are in java.lang's hierarchy, or are considered to be so
standard as to justify existence in java.lang.
/*
* 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.lang.reflect.AccessibleObject;
import java.lang.reflect.Field;
import java.lang.reflect.Modifier;
import java.util.Collection;
import java.util.Comparator;
import java.util.Objects;
import org.apache.commons.lang3.ArrayUtils;
import org.apache.commons.lang3.ObjectUtils;
/**
* Assists in implementing {@link Comparable#compareTo(Object)} methods.
*
* It is consistent with {@code equals(Object)} and
* {@code hashCode()} built with {@link EqualsBuilder} and
* {@link HashCodeBuilder}.
*
* Two Objects that compare equal using {@code equals(Object)} should normally
* also compare equal using {@code compareTo(Object)}.
*
* All relevant fields should be included in the calculation of the
* comparison. Derived fields may be ignored. The same fields, in the same
* order, should be used in both {@code compareTo(Object)} and
* {@code equals(Object)}.
*
* To use this class write code as follows:
*
*
* public class MyClass {
* String field1;
* int field2;
* boolean field3;
*
* ...
*
* public int compareTo(Object o) {
* MyClass myClass = (MyClass) o;
* return new CompareToBuilder()
* .appendSuper(super.compareTo(o)
* .append(this.field1, myClass.field1)
* .append(this.field2, myClass.field2)
* .append(this.field3, myClass.field3)
* .toComparison();
* }
* }
*
*
* Values are compared in the order they are appended to the builder. If any comparison returns
* a non-zero result, then that value will be the result returned by {@code toComparison()} and all
* subsequent comparisons are skipped.
*
* Alternatively, there are {@link #reflectionCompare(Object, Object) reflectionCompare} methods that use
* reflection to determine the fields to append. Because fields can be private,
* {@code reflectionCompare} uses {@link java.lang.reflect.AccessibleObject#setAccessible(boolean)} to
* bypass normal access control checks. This will fail under a security manager,
* unless the appropriate permissions are set up correctly. It is also
* slower than appending explicitly.
*
* A typical implementation of {@code compareTo(Object)} using
* {@code reflectionCompare} looks like:
*
* public int compareTo(Object o) {
* return CompareToBuilder.reflectionCompare(this, o);
* }
*
*
* The reflective methods compare object fields in the order returned by
* {@link Class#getDeclaredFields()}. The fields of the class are compared first, followed by those
* of its parent classes (in order from the bottom to the top of the class hierarchy).
*
* @see Comparable
* @see Object#equals(Object)
* @see Object#hashCode()
* @see EqualsBuilder
* @see HashCodeBuilder
* @since 1.0
*/
public class CompareToBuilder implements Builder {
/**
* Appends to {@code builder} the comparison of {@code lhs}
* to {@code rhs} using the fields defined in {@code clazz}.
*
* @param lhs left-hand side object
* @param rhs right-hand side object
* @param clazz {@link Class} that defines fields to be compared
* @param builder {@link CompareToBuilder} to append to
* @param useTransients whether to compare transient fields
* @param excludeFields fields to exclude
*/
private static void reflectionAppend(
final Object lhs,
final Object rhs,
final Class clazz,
final CompareToBuilder builder,
final boolean useTransients,
final String[] excludeFields) {
final Field[] fields = clazz.getDeclaredFields();
AccessibleObject.setAccessible(fields, true);
for (int i = 0; i < fields.length && builder.comparison == 0; i++) {
final Field field = fields[i];
if (!ArrayUtils.contains(excludeFields, field.getName())
&& !field.getName().contains("$")
&& (useTransients || !Modifier.isTransient(field.getModifiers()))
&& !Modifier.isStatic(field.getModifiers())) {
// IllegalAccessException can't happen. Would get a Security exception instead.
// Throw a runtime exception in case the impossible happens.
builder.append(Reflection.getUnchecked(field, lhs), Reflection.getUnchecked(field, rhs));
}
}
}
/**
* Compares two {@link Object}s via reflection.
*
* Fields can be private, thus {@code AccessibleObject.setAccessible}
* is used to bypass normal access control checks. This will fail under a
* security manager unless the appropriate permissions are set.
*
*
* - Static fields will not be compared
* - Transient members will be not be compared, as they are likely derived
* fields
* - Superclass fields will be compared
*
*
* If both {@code lhs} and {@code rhs} are {@code null},
* they are considered equal.
*
* @param lhs left-hand side object
* @param rhs right-hand side object
* @return a negative integer, zero, or a positive integer as {@code lhs}
* is less than, equal to, or greater than {@code rhs}
* @throws NullPointerException if either (but not both) parameters are
* {@code null}
* @throws ClassCastException if {@code rhs} is not assignment-compatible
* with {@code lhs}
*/
public static int reflectionCompare(final Object lhs, final Object rhs) {
return reflectionCompare(lhs, rhs, false, null);
}
/**
* Compares two {@link Object}s via reflection.
*
* Fields can be private, thus {@code AccessibleObject.setAccessible}
* is used to bypass normal access control checks. This will fail under a
* security manager unless the appropriate permissions are set.
*
*
* - Static fields will not be compared
* - If {@code compareTransients} is {@code true},
* compares transient members. Otherwise ignores them, as they
* are likely derived fields.
* - Superclass fields will be compared
*
*
* If both {@code lhs} and {@code rhs} are {@code null},
* they are considered equal.
*
* @param lhs left-hand side object
* @param rhs right-hand side object
* @param compareTransients whether to compare transient fields
* @return a negative integer, zero, or a positive integer as {@code lhs}
* is less than, equal to, or greater than {@code rhs}
* @throws NullPointerException if either {@code lhs} or {@code rhs}
* (but not both) is {@code null}
* @throws ClassCastException if {@code rhs} is not assignment-compatible
* with {@code lhs}
*/
public static int reflectionCompare(final Object lhs, final Object rhs, final boolean compareTransients) {
return reflectionCompare(lhs, rhs, compareTransients, null);
}
/**
* Compares two {@link Object}s via reflection.
*
* Fields can be private, thus {@code AccessibleObject.setAccessible}
* is used to bypass normal access control checks. This will fail under a
* security manager unless the appropriate permissions are set.
*
*
* - Static fields will not be compared
* - If the {@code compareTransients} is {@code true},
* compares transient members. Otherwise ignores them, as they
* are likely derived fields.
* - Compares superclass fields up to and including {@code reflectUpToClass}.
* If {@code reflectUpToClass} is {@code null}, compares all superclass fields.
*
*
* If both {@code lhs} and {@code rhs} are {@code null},
* they are considered equal.
*
* @param lhs left-hand side object
* @param rhs right-hand side object
* @param compareTransients whether to compare transient fields
* @param reflectUpToClass last superclass for which fields are compared
* @param excludeFields fields to exclude
* @return a negative integer, zero, or a positive integer as {@code lhs}
* is less than, equal to, or greater than {@code rhs}
* @throws NullPointerException if either {@code lhs} or {@code rhs}
* (but not both) is {@code null}
* @throws ClassCastException if {@code rhs} is not assignment-compatible
* with {@code lhs}
* @since 2.2 (2.0 as {@code reflectionCompare(Object, Object, boolean, Class)})
*/
public static int reflectionCompare(
final Object lhs,
final Object rhs,
final boolean compareTransients,
final Class reflectUpToClass,
final String... excludeFields) {
if (lhs == rhs) {
return 0;
}
Objects.requireNonNull(lhs, "lhs");
Objects.requireNonNull(rhs, "rhs");
Class lhsClazz = lhs.getClass();
if (!lhsClazz.isInstance(rhs)) {
throw new ClassCastException();
}
final CompareToBuilder compareToBuilder = new CompareToBuilder();
reflectionAppend(lhs, rhs, lhsClazz, compareToBuilder, compareTransients, excludeFields);
while (lhsClazz.getSuperclass() != null && lhsClazz != reflectUpToClass) {
lhsClazz = lhsClazz.getSuperclass();
reflectionAppend(lhs, rhs, lhsClazz, compareToBuilder, compareTransients, excludeFields);
}
return compareToBuilder.toComparison();
}
/**
* Compares two {@link Object}s via reflection.
*
* Fields can be private, thus {@code AccessibleObject.setAccessible}
* is used to bypass normal access control checks. This will fail under a
* security manager unless the appropriate permissions are set.
*
*
* - Static fields will not be compared
* - If {@code compareTransients} is {@code true},
* compares transient members. Otherwise ignores them, as they
* are likely derived fields.
* - Superclass fields will be compared
*
*
* If both {@code lhs} and {@code rhs} are {@code null},
* they are considered equal.
*
* @param lhs left-hand side object
* @param rhs right-hand side object
* @param excludeFields Collection of String fields to exclude
* @return a negative integer, zero, or a positive integer as {@code lhs}
* is less than, equal to, or greater than {@code rhs}
* @throws NullPointerException if either {@code lhs} or {@code rhs}
* (but not both) is {@code null}
* @throws ClassCastException if {@code rhs} is not assignment-compatible
* with {@code lhs}
* @since 2.2
*/
public static int reflectionCompare(final Object lhs, final Object rhs, final Collection excludeFields) {
return reflectionCompare(lhs, rhs, ReflectionToStringBuilder.toNoNullStringArray(excludeFields));
}
/**
* Compares two {@link Object}s via reflection.
*
* Fields can be private, thus {@code AccessibleObject.setAccessible}
* is used to bypass normal access control checks. This will fail under a
* security manager unless the appropriate permissions are set.
*
*
* - Static fields will not be compared
* - If {@code compareTransients} is {@code true},
* compares transient members. Otherwise ignores them, as they
* are likely derived fields.
* - Superclass fields will be compared
*
*
* If both {@code lhs} and {@code rhs} are {@code null},
* they are considered equal.
*
* @param lhs left-hand side object
* @param rhs right-hand side object
* @param excludeFields array of fields to exclude
* @return a negative integer, zero, or a positive integer as {@code lhs}
* is less than, equal to, or greater than {@code rhs}
* @throws NullPointerException if either {@code lhs} or {@code rhs}
* (but not both) is {@code null}
* @throws ClassCastException if {@code rhs} is not assignment-compatible
* with {@code lhs}
* @since 2.2
*/
public static int reflectionCompare(final Object lhs, final Object rhs, final String... excludeFields) {
return reflectionCompare(lhs, rhs, false, null, excludeFields);
}
/**
* Current state of the comparison as appended fields are checked.
*/
private int comparison;
/**
* Constructor for CompareToBuilder.
*
* Starts off assuming that the objects are equal. Multiple calls are
* then made to the various append methods, followed by a call to
* {@link #toComparison} to get the result.
*/
public CompareToBuilder() {
comparison = 0;
}
/**
* Appends to the {@code builder} the comparison of
* two {@code booleans}s.
*
* @param lhs left-hand side value
* @param rhs right-hand side value
* @return {@code this} instance.
*/
public CompareToBuilder append(final boolean lhs, final boolean rhs) {
if (comparison != 0) {
return this;
}
if (lhs == rhs) {
return this;
}
if (lhs) {
comparison = 1;
} else {
comparison = -1;
}
return this;
}
/**
* Appends to the {@code builder} the deep comparison of
* two {@code boolean} arrays.
*
*
* - Check if arrays are the same using {@code ==}
* - Check if for {@code null}, {@code null} is less than non-{@code null}
* - Check array length, a shorter length array is less than a longer length array
* - Check array contents element by element using {@link #append(boolean, boolean)}
*
*
* @param lhs left-hand side array
* @param rhs right-hand side array
* @return {@code this} instance.
*/
public CompareToBuilder append(final boolean[] lhs, final boolean[] rhs) {
if (comparison != 0) {
return this;
}
if (lhs == rhs) {
return this;
}
if (lhs == null) {
comparison = -1;
return this;
}
if (rhs == null) {
comparison = 1;
return this;
}
if (lhs.length != rhs.length) {
comparison = lhs.length < rhs.length ? -1 : 1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++) {
append(lhs[i], rhs[i]);
}
return this;
}
/**
* Appends to the {@code builder} the comparison of
* two {@code byte}s.
*
* @param lhs left-hand side value
* @param rhs right-hand side value
* @return {@code this} instance.
*/
public CompareToBuilder append(final byte lhs, final byte rhs) {
if (comparison != 0) {
return this;
}
comparison = Byte.compare(lhs, rhs);
return this;
}
/**
* Appends to the {@code builder} the deep comparison of
* two {@code byte} arrays.
*
*
* - Check if arrays are the same using {@code ==}
* - Check if for {@code null}, {@code null} is less than non-{@code null}
* - Check array length, a shorter length array is less than a longer length array
* - Check array contents element by element using {@link #append(byte, byte)}
*
*
* @param lhs left-hand side array
* @param rhs right-hand side array
* @return {@code this} instance.
*/
public CompareToBuilder append(final byte[] lhs, final byte[] rhs) {
if (comparison != 0) {
return this;
}
if (lhs == rhs) {
return this;
}
if (lhs == null) {
comparison = -1;
return this;
}
if (rhs == null) {
comparison = 1;
return this;
}
if (lhs.length != rhs.length) {
comparison = lhs.length < rhs.length ? -1 : 1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++) {
append(lhs[i], rhs[i]);
}
return this;
}
/**
* Appends to the {@code builder} the comparison of
* two {@code char}s.
*
* @param lhs left-hand side value
* @param rhs right-hand side value
* @return {@code this} instance.
*/
public CompareToBuilder append(final char lhs, final char rhs) {
if (comparison != 0) {
return this;
}
comparison = Character.compare(lhs, rhs);
return this;
}
/**
* Appends to the {@code builder} the deep comparison of
* two {@code char} arrays.
*
*
* - Check if arrays are the same using {@code ==}
* - Check if for {@code null}, {@code null} is less than non-{@code null}
* - Check array length, a shorter length array is less than a longer length array
* - Check array contents element by element using {@link #append(char, char)}
*
*
* @param lhs left-hand side array
* @param rhs right-hand side array
* @return {@code this} instance.
*/
public CompareToBuilder append(final char[] lhs, final char[] rhs) {
if (comparison != 0) {
return this;
}
if (lhs == rhs) {
return this;
}
if (lhs == null) {
comparison = -1;
return this;
}
if (rhs == null) {
comparison = 1;
return this;
}
if (lhs.length != rhs.length) {
comparison = lhs.length < rhs.length ? -1 : 1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++) {
append(lhs[i], rhs[i]);
}
return this;
}
/**
* Appends to the {@code builder} the comparison of
* two {@code double}s.
*
* This handles NaNs, Infinities, and {@code -0.0}.
*
* It is compatible with the hash code generated by
* {@link HashCodeBuilder}.
*
* @param lhs left-hand side value
* @param rhs right-hand side value
* @return {@code this} instance.
*/
public CompareToBuilder append(final double lhs, final double rhs) {
if (comparison != 0) {
return this;
}
comparison = Double.compare(lhs, rhs);
return this;
}
/**
* Appends to the {@code builder} the deep comparison of
* two {@code double} arrays.
*
*
* - Check if arrays are the same using {@code ==}
* - Check if for {@code null}, {@code null} is less than non-{@code null}
* - Check array length, a shorter length array is less than a longer length array
* - Check array contents element by element using {@link #append(double, double)}
*
*
* @param lhs left-hand side array
* @param rhs right-hand side array
* @return {@code this} instance.
*/
public CompareToBuilder append(final double[] lhs, final double[] rhs) {
if (comparison != 0) {
return this;
}
if (lhs == rhs) {
return this;
}
if (lhs == null) {
comparison = -1;
return this;
}
if (rhs == null) {
comparison = 1;
return this;
}
if (lhs.length != rhs.length) {
comparison = lhs.length < rhs.length ? -1 : 1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++) {
append(lhs[i], rhs[i]);
}
return this;
}
/**
* Appends to the {@code builder} the comparison of
* two {@code float}s.
*
* This handles NaNs, Infinities, and {@code -0.0}.
*
* It is compatible with the hash code generated by
* {@link HashCodeBuilder}.
*
* @param lhs left-hand side value
* @param rhs right-hand side value
* @return {@code this} instance.
*/
public CompareToBuilder append(final float lhs, final float rhs) {
if (comparison != 0) {
return this;
}
comparison = Float.compare(lhs, rhs);
return this;
}
/**
* Appends to the {@code builder} the deep comparison of
* two {@code float} arrays.
*
*
* - Check if arrays are the same using {@code ==}
* - Check if for {@code null}, {@code null} is less than non-{@code null}
* - Check array length, a shorter length array is less than a longer length array
* - Check array contents element by element using {@link #append(float, float)}
*
*
* @param lhs left-hand side array
* @param rhs right-hand side array
* @return {@code this} instance.
*/
public CompareToBuilder append(final float[] lhs, final float[] rhs) {
if (comparison != 0) {
return this;
}
if (lhs == rhs) {
return this;
}
if (lhs == null) {
comparison = -1;
return this;
}
if (rhs == null) {
comparison = 1;
return this;
}
if (lhs.length != rhs.length) {
comparison = lhs.length < rhs.length ? -1 : 1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++) {
append(lhs[i], rhs[i]);
}
return this;
}
/**
* Appends to the {@code builder} the comparison of
* two {@code int}s.
*
* @param lhs left-hand side value
* @param rhs right-hand side value
* @return {@code this} instance.
*/
public CompareToBuilder append(final int lhs, final int rhs) {
if (comparison != 0) {
return this;
}
comparison = Integer.compare(lhs, rhs);
return this;
}
/**
* Appends to the {@code builder} the deep comparison of
* two {@code int} arrays.
*
*
* - Check if arrays are the same using {@code ==}
* - Check if for {@code null}, {@code null} is less than non-{@code null}
* - Check array length, a shorter length array is less than a longer length array
* - Check array contents element by element using {@link #append(int, int)}
*
*
* @param lhs left-hand side array
* @param rhs right-hand side array
* @return {@code this} instance.
*/
public CompareToBuilder append(final int[] lhs, final int[] rhs) {
if (comparison != 0) {
return this;
}
if (lhs == rhs) {
return this;
}
if (lhs == null) {
comparison = -1;
return this;
}
if (rhs == null) {
comparison = 1;
return this;
}
if (lhs.length != rhs.length) {
comparison = lhs.length < rhs.length ? -1 : 1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++) {
append(lhs[i], rhs[i]);
}
return this;
}
/**
* Appends to the {@code builder} the comparison of
* two {@code long}s.
*
* @param lhs left-hand side value
* @param rhs right-hand side value
* @return {@code this} instance.
*/
public CompareToBuilder append(final long lhs, final long rhs) {
if (comparison != 0) {
return this;
}
comparison = Long.compare(lhs, rhs);
return this;
}
/**
* Appends to the {@code builder} the deep comparison of
* two {@code long} arrays.
*
*
* - Check if arrays are the same using {@code ==}
* - Check if for {@code null}, {@code null} is less than non-{@code null}
* - Check array length, a shorter length array is less than a longer length array
* - Check array contents element by element using {@link #append(long, long)}
*
*
* @param lhs left-hand side array
* @param rhs right-hand side array
* @return {@code this} instance.
*/
public CompareToBuilder append(final long[] lhs, final long[] rhs) {
if (comparison != 0) {
return this;
}
if (lhs == rhs) {
return this;
}
if (lhs == null) {
comparison = -1;
return this;
}
if (rhs == null) {
comparison = 1;
return this;
}
if (lhs.length != rhs.length) {
comparison = lhs.length < rhs.length ? -1 : 1;
return this;
}
for (int i = 0; i < lhs.length && comparison == 0; i++) {
append(lhs[i], rhs[i]);
}
return this;
}
/**
* Appends to the {@code builder} the comparison of
* two {@link Object}s.
*
*
* - Check if {@code lhs == rhs}
* - Check if either {@code lhs} or {@code rhs} is {@code null},
* a {@code null} object is less than a non-{@code null} object
* - Check the object contents
*
*
* {@code lhs} must either be an array or implement {@link Comparable}.
*
* @param lhs left-hand side object
* @param rhs right-hand side object
* @return {@code this} instance.
* @throws ClassCastException if {@code rhs} is not assignment-compatible
* with {@code lhs}
*/
public CompareToBuilder append(final Object lhs, final Object rhs) {
return append(lhs, rhs, null);
}
/**
* Appends to the {@code builder} the comparison of
* two {@link Object}s.
*
*
* - Check if {@code lhs == rhs}
* - Check if either {@code lhs} or {@code rhs} is {@code null},
* a {@code null} object is less than a non-{@code null} object
* - Check the object contents
*
*
* If {@code lhs} is an array, array comparison methods will be used.
* Otherwise {@code comparator} will be used to compare the objects.
* If {@code comparator} is {@code null}, {@code lhs} must
* implement {@link Comparable} instead.
*
* @param lhs left-hand side object
* @param rhs right-hand side object
* @param comparator {@link Comparator} used to compare the objects,
* {@code null} means treat lhs as {@link Comparable}
* @return {@code this} instance.
* @throws ClassCastException if {@code rhs} is not assignment-compatible
* with {@code lhs}
* @since 2.0
*/
public CompareToBuilder append(final Object lhs, final Object rhs, final Comparator comparator) {
if (comparison != 0) {
return this;
}
if (lhs == rhs) {
return this;
}
if (lhs == null) {
comparison = -1;
return this;
}
if (rhs == null) {
comparison = 1;
return this;
}
if (ObjectUtils.isArray(lhs)) {
// factor out array case in order to keep method small enough to be inlined
appendArray(lhs, rhs, comparator);
} else // the simple case, not an array, just test the element
if (comparator == null) {
@SuppressWarnings("unchecked") // assume this can be done; if not throw CCE as per Javadoc
final Comparable