org.divxdede.commons.Objects Maven / Gradle / Ivy

Go to download
/*
 * Copyright (c) 2010 ANDRE S?bastien (divxdede).  All rights reserved.
 * Objects.java is a part of this Commons library
 * ====================================================================
 *
 * Commons library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, either version 3 of the License,
 * or any later version.
 *
 * This is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, see .
 */
package org.divxdede.commons;

import java.util.Comparator;

/**
 * Help class for manipulating general objects.
 *
 * @author Andr? S?bastien (divxdede)
 */
public abstract class Objects {
    
    /** Give the native toString representation of an object even if the method has been overrided.
     *  @param o Object to give the native toString() representation
     *  @return the Native toString
     */
    public static String toNativeString( Object o ) {
        if( o == null ) return String.valueOf(o);
        return o.getClass().getName() + "@" + Integer.toHexString( System.identityHashCode(o) );
    }

    /** Compare 2 comparables objects in a safe way allowing null instances without throw any NullPointerException.
     *  
     *  This method is usefull when you implement a compareTo of an object using comparison of attributes members that can be nullable.
     *  
     *      ...
     *      // Compare Exemple Objects by their color and if color are equals by it's title.
     *      // Theses attributes (Color and Title) may be null
     *      public int compareTo(Exemple other  ) {
     *         int result = Objects.compare( this.getColor() , other.getColor() );
     *         if( result != 0 ) return result;
     *         return Objects.compare( this.getTitle() , other.getTitle() );
     *      }
     *  
     *  
     *  If the first argument is null and the second is not. this method will call a compareTo on the second argument passing it a null value.

     *  That means, you must handle in your compareTo implementation the case of receivine a null value in parameter.
     * 
     *  @param a the first object to be compared.
     *  @param b the second object to be compared.
     *  @return a negative integer, zero, or a positive integer as the
     * 	        first argument is less than, equal to, or greater than the
     *	        second.
     *  @throws ClassCastException if the arguments' types prevent them from
     * 	        being compared by this comparator.
     *  @since 0.2
     */
    public static int compare( Comparable a , Comparable b ) {
        if( a == b ) return 0;
        if( a == null ) return b.compareTo(a) * -1;
        return a.compareTo(b);
    }

    /** Create a Natural comparator (using the Comparable logic of an object) in a safe way allowing  null instances.

     *  This comparator delegate all comparison to the {@link #compare(java.lang.Comparable, java.lang.Comparable)} method
     *
     * @param  Object type to be able to compare.
     * @param type Object class of objects to compare
     * @return A Natural safe comparator
     * @since 0.2
     */
    public static  Comparator createNaturalComparator( Class type ) {
        return new Comparator() {
            public int compare(T o1, T o2) {
                return Objects.compare(o1, o1);
            }
        };
    }

    /** Create a safely comparator that handle null instances before delegate the comparison logic to the specified comparator.

     *  This method allow to write a comparator without writing any null case in it's comparison logic and wrap it by a safe comparator that will do it.
     *  
     *  This method requires a nullOrder describing how a null value must be ordered with non-null values
     *
     * @param  Type of objects to compare by the comparator to create
     * @param unsafe Unsafe comparator that can't handle null values in it's comparison logic.
     * @param nullOrder A negativetmeans that a null value is lesser than a non-null value.  A positive value means that a null value is greater than a non-null value.
     * @return Safe comparator that can handle null values
     * @since 0.2
     */
    public static  Comparator createSafeComparator( final Comparator unsafe , final int nullOrder ) {
        return new Comparator() {
            public int compare(T o1, T o2) {
                if( o1 == o2 ) return 0;
                if( o1 == null ) return nullOrder;
                if( o2 == null ) return nullOrder * -1;
                return unsafe.compare(o1,o2);
            }
        };
    }

    /**
     * Standard equals comparison with null instances checking.

     * This method return true if both parameters are null.
     *
     * @param o1 First object to test
     * @param o2 Second object to test
     * @return true if theses parameters are equals accordingly to theses equals methods.
     */
    public static boolean areEquals(Object o1, Object o2) {
        if (o1 == null && o2 == null) {
            return true;
        }
        if (o1 != null) {
            if( o1 == o2 )   return true;
            if( o2 == null ) return false;
            return o1.equals(o2);
        }
        return false;
    }
}