org.jtrim2.collections.EqualityComparator Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of jtrim-collections Show documentation

JTrim Collections

There is a newer version: 2.0.7

package org.jtrim2.collections;

/**
 * Defines an equality comparison between two objects. This interface might be
 * used instead of a {@code java.util.Comparator} if no ordering is needed and
 * the natural comparison isn't adequate.
 * 
 * For standard implementations, see the {@link Equality} class.
 *
 * 
Thread safety
 * Implementations of this interface are required to be safely usable by
 * multiple threads concurrently; with the assumption that reading properties of
 * the compared objects are thread-safe.
 *
 * Synchronization transparency
 * Implementations of this interface are required to be
 * synchronization transparent.
 *
 * @param  the type of the objects to be compared
 *
 * @see Equality
 */
public interface EqualityComparator {
    /**
     * Returns {@code true} if the specified objects are to be considered
     * equivalent, {@code false} if not.
     * 
     * The equality comparison must have the same properties as defined for
     * the {@link Object#equals(Object)} method: reflexive, symmetric,
     * transitive and consistent.
     * 

     * Special case for {@code null} references:
     * 

     *  
     *   If both references are {@code null}, this method must return
     *   {@code true}.
     *  
     *  
     *   If only one of the references are {@code null}, this method must return
     *   {@code false}.
     *  
     * 
     *
     * @param obj1 the first object to be compared. This argument is allowed to
     *   be {@code null}.
     * @param obj2 the second object to be compared. This argument is allowed to
     *   be {@code null}.
     * @return {@code true} if the specified objects are to be considered
     *   equivalent, {@code false} if not
     */
    public boolean equals(T obj1, T obj2);
}