    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 *      http://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 */
    017
    018package org.apache.commons.beanutils;
    019
    020import java.io.Serializable;
    021import java.lang.reflect.InvocationTargetException;
    022import java.util.Comparator;
    023
    024import org.apache.commons.collections.comparators.ComparableComparator;
    025
    026/**
    027 * <p>
    028 * This comparator compares two beans by the specified bean property.
    029 * It is also possible to compare beans based on nested, indexed,
    030 * combined, mapped bean properties. Please see the {@link PropertyUtilsBean}
    031 * documentation for all property name possibilities.
    032 *
    033 * </p><p>
    034 * <strong>Note:</strong> The BeanComparator passes the values of the specified
    035 * bean property to a ComparableComparator, if no comparator is
    036 * specified in the constructor. If you are comparing two beans based
    037 * on a property that could contain "null" values, a suitable <code>Comparator</code>
    038 * or <code>ComparatorChain</code> should be supplied in the constructor.
    039 * Note that the passed in {@code Comparator} must be able to handle the
    040 * passed in objects. Because the type of the property to be compared is not
    041 * known at compile time no type checks can be performed by the compiler.
    042 * Thus {@code ClassCastException} exceptions can be thrown if unexpected
    043 * property values occur.
    044 * </p>
    045 *
    046 * @param <T> the type of beans to be compared by this {@code Comparator}
    047 */
    048public class BeanComparator<T> implements Comparator<T>, Serializable {
    049
    050    private static final long serialVersionUID = 1L;
    051
    052    /**
    053     * Method name to call to compare.
    054     */
    055    private String property;
    056
    057    /**
    058     * BeanComparator will pass the values of the specified bean property to this Comparator. If your bean property is not a comparable or contains null values,
    059     * a suitable comparator may be supplied in this constructor.
    060     */
    061    private final Comparator<?> comparator;
    062
    063    /**
    064     * <p>Constructs a Bean Comparator without a property set.
    065     * </p><p>
    066     * <strong>Note</strong> that this is intended to be used
    067     * only in bean-centric environments.
    068     * </p><p>
    069     * Until {@link #setProperty} is called with a non-null value.
    070     * this comparator will compare the Objects only.
    071     * </p>
    072     */
    073    public BeanComparator() {
    074        this(null);
    075    }
    076
    077    /**
    078     * <p>Constructs a property-based comparator for beans.
    079     * This compares two beans by the property
    080     * specified in the property parameter. This constructor creates
    081     * a <code>BeanComparator</code> that uses a <code>ComparableComparator</code>
    082     * to compare the property values.
    083     * </p>
    084     *
    085     * <p>Passing "null" to this constructor will cause the BeanComparator
    086     * to compare objects based on natural order, that is
    087     * <code>java.lang.Comparable</code>.
    088     * </p>
    089     *
    090     * @param property String Name of a bean property, which may contain the
    091     * name of a simple, nested, indexed, mapped, or combined
    092     * property. See {@link PropertyUtilsBean} for property query language syntax.
    093     * If the property passed in is null then the actual objects will be compared
    094     */
    095    public BeanComparator(final String property) {
    096        this(property, ComparableComparator.getInstance());
    097    }
    098
    099    /**
    100     * Constructs a property-based comparator for beans.
    101     * This constructor creates
    102     * a BeanComparator that uses the supplied Comparator to compare
    103     * the property values.
    104     *
    105     * @param property Name of a bean property, can contain the name
    106     * of a simple, nested, indexed, mapped, or combined
    107     * property. See {@link PropertyUtilsBean} for property query language
    108     * syntax.
    109     * @param comparator BeanComparator will pass the values of the
    110     * specified bean property to this Comparator.
    111     * If your bean property is not a comparable or
    112     * contains null values, a suitable comparator
    113     * may be supplied in this constructor.
    114     */
    115    public BeanComparator(final String property, final Comparator<?> comparator) {
    116        setProperty(property);
    117        if (comparator != null) {
    118            this.comparator = comparator;
    119        } else {
    120            this.comparator = ComparableComparator.getInstance();
    121        }
    122    }
    123
    124    /**
    125     * Compare two JavaBeans by their shared property.
    126     * If {@link #getProperty} is null then the actual objects will be compared.
    127     *
    128     * @param  o1 Object The first bean to get data from to compare against
    129     * @param  o2 Object The second bean to get data from to compare
    130     * @return int negative or positive based on order
    131     */
    132    @Override
    133    public int compare(final T o1, final T o2) {
    134
    135        if (property == null) {
    136            // compare the actual objects
    137            return internalCompare(o1, o2);
    138        }
    139
    140        try {
    141            final Object value1 = PropertyUtils.getProperty(o1, property);
    142            final Object value2 = PropertyUtils.getProperty(o2, property);
    143            return internalCompare(value1, value2);
    144        } catch (final IllegalAccessException iae) {
    145            throw new RuntimeException("IllegalAccessException: " + iae.toString());
    146        } catch (final InvocationTargetException ite) {
    147            throw new RuntimeException("InvocationTargetException: " + ite.toString());
    148        } catch (final NoSuchMethodException nsme) {
    149            throw new RuntimeException("NoSuchMethodException: " + nsme.toString());
    150        }
    151    }
    152
    153    /**
    154     * Two <code>BeanComparator</code>'s are equals if and only if
    155     * the wrapped comparators and the property names to be compared
    156     * are equal.
    157     * @param  o Comparator to compare to
    158     * @return whether the the comparators are equal or not
    159     */
    160    @Override
    161    public boolean equals(final Object o) {
    162        if (this == o) {
    163            return true;
    164        }
    165        if (!(o instanceof BeanComparator)) {
    166            return false;
    167        }
    168
    169        final BeanComparator<?> beanComparator = (BeanComparator<?>) o;
    170
    171        if (!comparator.equals(beanComparator.comparator)) {
    172            return false;
    173        }
    174        if (property == null) {
    175            return beanComparator.property == null;
    176        }
    177        if (!property.equals(beanComparator.property)) {
    178            return false;
    179        }
    180
    181        return true;
    182    }
    183
    184    /**
    185     * Gets the Comparator being used to compare beans.
    186     *
    187     * @return the Comparator being used to compare beans
    188     */
    189    public Comparator<?> getComparator() {
    190        return comparator;
    191    }
    192
    193    /**
    194     * Gets the property attribute of the BeanComparator
    195     *
    196     * @return String method name to call to compare.
    197     * A null value indicates that the actual objects will be compared
    198     */
    199    public String getProperty() {
    200        return property;
    201    }
    202
    203    /**
    204     * Hash code compatible with equals.
    205     * @return the hash code for this comparator
    206     */
    207    @Override
    208    public int hashCode() {
    209        return comparator.hashCode();
    210    }
    211
    212    /**
    213     * Compares the given values using the internal {@code Comparator}.
    214     * <em>Note</em>: This comparison cannot be performed in a type-safe way; so
    215     * {@code ClassCastException} exceptions may be thrown.
    216     *
    217     * @param val1 the first value to be compared
    218     * @param val2 the second value to be compared
    219     * @return the result of the comparison
    220     */
    221    private int internalCompare(final Object val1, final Object val2) {
    222        @SuppressWarnings("rawtypes")
    223        final
    224        // to make the compiler happy
    225        Comparator c = comparator;
    226        return c.compare(val1, val2);
    227    }
    228
    229    /**
    230     * Sets the method to be called to compare two JavaBeans
    231     *
    232     * @param property String method name to call to compare
    233     * If the property passed in is null then the actual objects will be compared
    234     */
    235    public void setProperty(final String property) {
    236        this.property = property;
    237    }
    238}