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

Go to download
/*
 * 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 org.apache.commons.lang3.ArrayUtils;

/**
 * Assists in implementing {@link java.lang.Comparable#compareTo(Object)} methods.
 *
 * It is consistent with equals(Object) and
 * hashcode() built with {@link EqualsBuilder} and
 * {@link HashCodeBuilder}.
 *
 * Two Objects that compare equal using equals(Object) should normally
 * also compare equal using 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 compareTo(Object) and
 * 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,
 * 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 compareTo(Object) using
 * 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 java.lang.Comparable
 * @see java.lang.Object#equals(Object)
 * @see java.lang.Object#hashCode()
 * @see EqualsBuilder
 * @see HashCodeBuilder
 * @since 1.0
 */
public class CompareToBuilder implements Builder {

    /**
     * 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() {
        super();
        comparison = 0;
    }

    //-----------------------------------------------------------------------
    /**
     * Compares two Objects via reflection.
     *
     * Fields can be private, thus 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 lhs and rhs are null,
     * they are considered equal.
     *
     * @param lhs  left-hand object
     * @param rhs  right-hand object
     * @return a negative integer, zero, or a positive integer as lhs
     *  is less than, equal to, or greater than rhs
     * @throws NullPointerException  if either (but not both) parameters are
     *  null
     * @throws ClassCastException  if rhs is not assignment-compatible
     *  with lhs
     */
    public static int reflectionCompare(final Object lhs, final Object rhs) {
        return reflectionCompare(lhs, rhs, false, null);
    }

    /**
     * Compares two Objects via reflection.
     *
     * Fields can be private, thus 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 compareTransients is true,
     *     compares transient members.  Otherwise ignores them, as they
     *     are likely derived fields.
     * Superclass fields will be compared
     * 
     *
     * If both lhs and rhs are null,
     * they are considered equal.
     *
     * @param lhs  left-hand object
     * @param rhs  right-hand object
     * @param compareTransients  whether to compare transient fields
     * @return a negative integer, zero, or a positive integer as lhs
     *  is less than, equal to, or greater than rhs
     * @throws NullPointerException  if either lhs or rhs
     *  (but not both) is null
     * @throws ClassCastException  if rhs is not assignment-compatible
     *  with lhs
     */
    public static int reflectionCompare(final Object lhs, final Object rhs, final boolean compareTransients) {
        return reflectionCompare(lhs, rhs, compareTransients, null);
    }

    /**
     * Compares two Objects via reflection.
     *
     * Fields can be private, thus 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 compareTransients is true,
     *     compares transient members.  Otherwise ignores them, as they
     *     are likely derived fields.
     * Superclass fields will be compared
     * 
     *
     * If both lhs and rhs are null,
     * they are considered equal.
     *
     * @param lhs  left-hand object
     * @param rhs  right-hand object
     * @param excludeFields  Collection of String fields to exclude
     * @return a negative integer, zero, or a positive integer as lhs
     *  is less than, equal to, or greater than rhs
     * @throws NullPointerException  if either lhs or rhs
     *  (but not both) is null
     * @throws ClassCastException  if rhs is not assignment-compatible
     *  with 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 Objects via reflection.
     *
     * Fields can be private, thus 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 compareTransients is true,
     *     compares transient members.  Otherwise ignores them, as they
     *     are likely derived fields.
     * Superclass fields will be compared
     * 
     *
     * If both lhs and rhs are null,
     * they are considered equal.
     *
     * @param lhs  left-hand object
     * @param rhs  right-hand object
     * @param excludeFields  array of fields to exclude
     * @return a negative integer, zero, or a positive integer as lhs
     *  is less than, equal to, or greater than rhs
     * @throws NullPointerException  if either lhs or rhs
     *  (but not both) is null
     * @throws ClassCastException  if rhs is not assignment-compatible
     *  with lhs
     * @since 2.2
     */
    public static int reflectionCompare(final Object lhs, final Object rhs, final String... excludeFields) {
        return reflectionCompare(lhs, rhs, false, null, excludeFields);
    }

    /**
     * Compares two Objects via reflection.
     *
     * Fields can be private, thus 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 compareTransients is true,
     *     compares transient members.  Otherwise ignores them, as they
     *     are likely derived fields.
     * Compares superclass fields up to and including reflectUpToClass.
     *     If reflectUpToClass is null, compares all superclass fields.
     * 
     *
     * If both lhs and rhs are null,
     * they are considered equal.
     *
     * @param lhs  left-hand object
     * @param rhs  right-hand 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 lhs
     *  is less than, equal to, or greater than rhs
     * @throws NullPointerException  if either lhs or rhs
     *  (but not both) is null
     * @throws ClassCastException  if rhs is not assignment-compatible
     *  with lhs
     * @since 2.2 (2.0 as 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;
        }
        if (lhs == null || rhs == null) {
            throw new NullPointerException();
        }
        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();
    }

    /**
     * Appends to builder the comparison of lhs
     * to rhs using the fields defined in clazz.
     *
     * @param lhs  left-hand object
     * @param rhs  right-hand object
     * @param clazz  Class that defines fields to be compared
     * @param builder  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 f = fields[i];
            if (!ArrayUtils.contains(excludeFields, f.getName())
                && !f.getName().contains("$")
                && (useTransients || !Modifier.isTransient(f.getModifiers()))
                && !Modifier.isStatic(f.getModifiers())) {
                try {
                    builder.append(f.get(lhs), f.get(rhs));
                } catch (final IllegalAccessException e) {
                    // This can't happen. Would get a Security exception instead.
                    // Throw a runtime exception in case the impossible happens.
                    throw new InternalError("Unexpected IllegalAccessException");
                }
            }
        }
    }

    //-----------------------------------------------------------------------
    /**
     * Appends to the builder the compareTo(Object)
     * result of the superclass.
     *
     * @param superCompareTo  result of calling super.compareTo(Object)
     * @return this - used to chain append calls
     * @since 2.0
     */
    public CompareToBuilder appendSuper(final int superCompareTo) {
        if (comparison != 0) {
            return this;
        }
        comparison = superCompareTo;
        return this;
    }

    //-----------------------------------------------------------------------
    /**
     * Appends to the builder the comparison of
     * two Objects.
     *
     * 
     * Check if lhs == rhs
     * Check if either lhs or rhs is null,
     *     a null object is less than a non-null object
     * Check the object contents
     * 
     *
     * lhs must either be an array or implement {@link Comparable}.
     *
     * @param lhs  left-hand object
     * @param rhs  right-hand object
     * @return this - used to chain append calls
     * @throws ClassCastException  if rhs is not assignment-compatible
     *  with lhs
     */
    public CompareToBuilder append(final Object lhs, final Object rhs) {
        return append(lhs, rhs, null);
    }

    /**
     * Appends to the builder the comparison of
     * two Objects.
     *
     * 
     * Check if lhs == rhs
     * Check if either lhs or rhs is null,
     *     a null object is less than a non-null object
     * Check the object contents
     * 
     *
     * If lhs is an array, array comparison methods will be used.
     * Otherwise comparator will be used to compare the objects.
     * If comparator is null, lhs must
     * implement {@link Comparable} instead.
     *
     * @param lhs  left-hand object
     * @param rhs  right-hand object
     * @param comparator  Comparator used to compare the objects,
     *  null means treat lhs as Comparable
     * @return this - used to chain append calls
     * @throws ClassCastException  if rhs is not assignment-compatible
     *  with 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 (lhs.getClass().isArray()) {
            // 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