Coverage Report - org.apache.commons.lang3.ObjectUtils
 
Classes in this File Line Coverage Branch Coverage Complexity
ObjectUtils
96%
132/137
98%
87/88
2,73
ObjectUtils$Null
100%
3/3
N/A
2,73
 
 1  
 /*
 2  
  * Licensed to the Apache Software Foundation (ASF) under one or more
 3  
  * contributor license agreements.  See the NOTICE file distributed with
 4  
  * this work for additional information regarding copyright ownership.
 5  
  * The ASF licenses this file to You under the Apache License, Version 2.0
 6  
  * (the "License"); you may not use this file except in compliance with
 7  
  * the License.  You may obtain a copy of the License at
 8  
  *
 9  
  *      http://www.apache.org/licenses/LICENSE-2.0
 10  
  *
 11  
  * Unless required by applicable law or agreed to in writing, software
 12  
  * distributed under the License is distributed on an "AS IS" BASIS,
 13  
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 14  
  * See the License for the specific language governing permissions and
 15  
  * limitations under the License.
 16  
  */
 17  
 package org.apache.commons.lang3;
 18  
 
 19  
 import java.io.IOException;
 20  
 import java.io.Serializable;
 21  
 import java.lang.reflect.Array;
 22  
 import java.lang.reflect.InvocationTargetException;
 23  
 import java.lang.reflect.Method;
 24  
 import java.util.Collections;
 25  
 import java.util.Comparator;
 26  
 import java.util.HashMap;
 27  
 import java.util.Map;
 28  
 import java.util.TreeSet;
 29  
 
 30  
 import org.apache.commons.lang3.exception.CloneFailedException;
 31  
 import org.apache.commons.lang3.mutable.MutableInt;
 32  
 import org.apache.commons.lang3.text.StrBuilder;
 33  
 
 34  
 /**
 35  
  * <p>Operations on {@code Object}.</p>
 36  
  *
 37  
  * <p>This class tries to handle {@code null} input gracefully.
 38  
  * An exception will generally not be thrown for a {@code null} input.
 39  
  * Each method documents its behaviour in more detail.</p>
 40  
  *
 41  
  * <p>#ThreadSafe#</p>
 42  
  * @since 1.0
 43  
  * @version $Id: ObjectUtils.java 1583781 2014-04-01 20:54:53Z niallp $
 44  
  */
 45  
 //@Immutable
 46  
 public class ObjectUtils {
 47  
 
 48  
     /**
 49  
      * <p>Singleton used as a {@code null} placeholder where
 50  
      * {@code null} has another meaning.</p>
 51  
      *
 52  
      * <p>For example, in a {@code HashMap} the
 53  
      * {@link java.util.HashMap#get(java.lang.Object)} method returns
 54  
      * {@code null} if the {@code Map} contains {@code null} or if there
 55  
      * is no matching key. The {@code Null} placeholder can be used to
 56  
      * distinguish between these two cases.</p>
 57  
      *
 58  
      * <p>Another example is {@code Hashtable}, where {@code null}
 59  
      * cannot be stored.</p>
 60  
      *
 61  
      * <p>This instance is Serializable.</p>
 62  
      */
 63  1
     public static final Null NULL = new Null();
 64  
 
 65  
     /**
 66  
      * <p>{@code ObjectUtils} instances should NOT be constructed in
 67  
      * standard programming. Instead, the static methods on the class should
 68  
      * be used, such as {@code ObjectUtils.defaultIfNull("a","b");}.</p>
 69  
      *
 70  
      * <p>This constructor is public to permit tools that require a JavaBean
 71  
      * instance to operate.</p>
 72  
      */
 73  
     public ObjectUtils() {
 74  1
         super();
 75  1
     }
 76  
 
 77  
     // Defaulting
 78  
     //-----------------------------------------------------------------------
 79  
     /**
 80  
      * <p>Returns a default value if the object passed is {@code null}.</p>
 81  
      *
 82  
      * <pre>
 83  
      * ObjectUtils.defaultIfNull(null, null)      = null
 84  
      * ObjectUtils.defaultIfNull(null, "")        = ""
 85  
      * ObjectUtils.defaultIfNull(null, "zz")      = "zz"
 86  
      * ObjectUtils.defaultIfNull("abc", *)        = "abc"
 87  
      * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE
 88  
      * </pre>
 89  
      *
 90  
      * @param <T> the type of the object
 91  
      * @param object  the {@code Object} to test, may be {@code null}
 92  
      * @param defaultValue  the default value to return, may be {@code null}
 93  
      * @return {@code object} if it is not {@code null}, defaultValue otherwise
 94  
      */
 95  
     public static <T> T defaultIfNull(final T object, final T defaultValue) {
 96  64
         return object != null ? object : defaultValue;
 97  
     }
 98  
 
 99  
     /**
 100  
      * <p>Returns the first value in the array which is not {@code null}.
 101  
      * If all the values are {@code null} or the array is {@code null}
 102  
      * or empty then {@code null} is returned.</p>
 103  
      *
 104  
      * <pre>
 105  
      * ObjectUtils.firstNonNull(null, null)      = null
 106  
      * ObjectUtils.firstNonNull(null, "")        = ""
 107  
      * ObjectUtils.firstNonNull(null, null, "")  = ""
 108  
      * ObjectUtils.firstNonNull(null, "zz")      = "zz"
 109  
      * ObjectUtils.firstNonNull("abc", *)        = "abc"
 110  
      * ObjectUtils.firstNonNull(null, "xyz", *)  = "xyz"
 111  
      * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE
 112  
      * ObjectUtils.firstNonNull()                = null
 113  
      * </pre>
 114  
      *
 115  
      * @param <T> the component type of the array
 116  
      * @param values  the values to test, may be {@code null} or empty
 117  
      * @return the first value from {@code values} which is not {@code null},
 118  
      *  or {@code null} if there are no non-null values
 119  
      * @since 3.0
 120  
      */
 121  
     public static <T> T firstNonNull(final T... values) {
 122  8
         if (values != null) {
 123  13
             for (final T val : values) {
 124  10
                 if (val != null) {
 125  4
                     return val;
 126  
                 }
 127  
             }
 128  
         }
 129  4
         return null;
 130  
     }
 131  
 
 132  
     // Null-safe equals/hashCode
 133  
     //-----------------------------------------------------------------------
 134  
     /**
 135  
      * <p>Compares two objects for equality, where either one or both
 136  
      * objects may be {@code null}.</p>
 137  
      *
 138  
      * <pre>
 139  
      * ObjectUtils.equals(null, null)                  = true
 140  
      * ObjectUtils.equals(null, "")                    = false
 141  
      * ObjectUtils.equals("", null)                    = false
 142  
      * ObjectUtils.equals("", "")                      = true
 143  
      * ObjectUtils.equals(Boolean.TRUE, null)          = false
 144  
      * ObjectUtils.equals(Boolean.TRUE, "true")        = false
 145  
      * ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE)  = true
 146  
      * ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false
 147  
      * </pre>
 148  
      *
 149  
      * @param object1  the first object, may be {@code null}
 150  
      * @param object2  the second object, may be {@code null}
 151  
      * @return {@code true} if the values of both objects are the same
 152  
      * @deprecated this method has been replaced by {@code java.util.Objects.equals(Object, Object)} in Java 7 and will
 153  
      * be removed from future releases.
 154  
      */
 155  
     @Deprecated
 156  
     public static boolean equals(final Object object1, final Object object2) {
 157  810
         if (object1 == object2) {
 158  57
             return true;
 159  
         }
 160  753
         if (object1 == null || object2 == null) {
 161  10
             return false;
 162  
         }
 163  743
         return object1.equals(object2);
 164  
     }
 165  
 
 166  
     /**
 167  
      * <p>Compares two objects for inequality, where either one or both
 168  
      * objects may be {@code null}.</p>
 169  
      *
 170  
      * <pre>
 171  
      * ObjectUtils.notEqual(null, null)                  = false
 172  
      * ObjectUtils.notEqual(null, "")                    = true
 173  
      * ObjectUtils.notEqual("", null)                    = true
 174  
      * ObjectUtils.notEqual("", "")                      = false
 175  
      * ObjectUtils.notEqual(Boolean.TRUE, null)          = true
 176  
      * ObjectUtils.notEqual(Boolean.TRUE, "true")        = true
 177  
      * ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE)  = false
 178  
      * ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true
 179  
      * </pre>
 180  
      *
 181  
      * @param object1  the first object, may be {@code null}
 182  
      * @param object2  the second object, may be {@code null}
 183  
      * @return {@code false} if the values of both objects are the same
 184  
      */
 185  
     public static boolean notEqual(final Object object1, final Object object2) {
 186  8
         return ObjectUtils.equals(object1, object2) == false;
 187  
     }
 188  
 
 189  
     /**
 190  
      * <p>Gets the hash code of an object returning zero when the
 191  
      * object is {@code null}.</p>
 192  
      *
 193  
      * <pre>
 194  
      * ObjectUtils.hashCode(null)   = 0
 195  
      * ObjectUtils.hashCode(obj)    = obj.hashCode()
 196  
      * </pre>
 197  
      *
 198  
      * @param obj  the object to obtain the hash code of, may be {@code null}
 199  
      * @return the hash code of the object, or zero if null
 200  
      * @since 2.1
 201  
      * @deprecated this method has been replaced by {@code java.util.Objects.hashCode(Object)} in Java 7 and will be
 202  
      * removed in future releases
 203  
      */
 204  
     @Deprecated
 205  
     public static int hashCode(final Object obj) {
 206  
         // hashCode(Object) retained for performance, as hash code is often critical
 207  32
         return obj == null ? 0 : obj.hashCode();
 208  
     }
 209  
 
 210  
     @Override
 211  
     public String toString() {
 212  0
         return super.toString();
 213  
     }
 214  
 
 215  
     /**
 216  
      * <p>Gets the hash code for multiple objects.</p>
 217  
      * 
 218  
      * <p>This allows a hash code to be rapidly calculated for a number of objects.
 219  
      * The hash code for a single object is the <em>not</em> same as {@link #hashCode(Object)}.
 220  
      * The hash code for multiple objects is the same as that calculated by an
 221  
      * {@code ArrayList} containing the specified objects.</p>
 222  
      *
 223  
      * <pre>
 224  
      * ObjectUtils.hashCodeMulti()                 = 1
 225  
      * ObjectUtils.hashCodeMulti((Object[]) null)  = 1
 226  
      * ObjectUtils.hashCodeMulti(a)                = 31 + a.hashCode()
 227  
      * ObjectUtils.hashCodeMulti(a,b)              = (31 + a.hashCode()) * 31 + b.hashCode()
 228  
      * ObjectUtils.hashCodeMulti(a,b,c)            = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode()
 229  
      * </pre>
 230  
      *
 231  
      * @param objects  the objects to obtain the hash code of, may be {@code null}
 232  
      * @return the hash code of the objects, or zero if null
 233  
      * @since 3.0
 234  
      * @deprecated this method has been replaced by {@code java.util.Objects.hash(Object...)} in Java 7 an will be
 235  
      * removed in future releases.
 236  
      */
 237  
     @Deprecated
 238  
     public static int hashCodeMulti(final Object... objects) {
 239  6
         int hash = 1;
 240  6
         if (objects != null) {
 241  11
             for (final Object object : objects) {
 242  6
                 int tmpHash = ObjectUtils.hashCode(object);
 243  6
                 hash = hash * 31 + tmpHash;
 244  
             }
 245  
         }
 246  6
         return hash;
 247  
     }
 248  
 
 249  
     // Identity ToString
 250  
     //-----------------------------------------------------------------------
 251  
     /**
 252  
      * <p>Gets the toString that would be produced by {@code Object}
 253  
      * if a class did not override toString itself. {@code null}
 254  
      * will return {@code null}.</p>
 255  
      *
 256  
      * <pre>
 257  
      * ObjectUtils.identityToString(null)         = null
 258  
      * ObjectUtils.identityToString("")           = "java.lang.String@1e23"
 259  
      * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa"
 260  
      * </pre>
 261  
      *
 262  
      * @param object  the object to create a toString for, may be
 263  
      *  {@code null}
 264  
      * @return the default toString text, or {@code null} if
 265  
      *  {@code null} passed in
 266  
      */
 267  
     public static String identityToString(final Object object) {
 268  3
         if (object == null) {
 269  1
             return null;
 270  
         }
 271  2
         final StringBuilder builder = new StringBuilder();
 272  2
         identityToString(builder, object);
 273  2
         return builder.toString();
 274  
     }
 275  
 
 276  
     /**
 277  
      * <p>Appends the toString that would be produced by {@code Object}
 278  
      * if a class did not override toString itself. {@code null}
 279  
      * will throw a NullPointerException for either of the two parameters. </p>
 280  
      *
 281  
      * <pre>
 282  
      * ObjectUtils.identityToString(appendable, "")            = appendable.append("java.lang.String@1e23"
 283  
      * ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa"
 284  
      * ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa")
 285  
      * </pre>
 286  
      *
 287  
      * @param appendable  the appendable to append to
 288  
      * @param object  the object to create a toString for
 289  
      * @throws IOException if an I/O error occurs
 290  
      * @since 3.2
 291  
      */
 292  
     public static void identityToString(final Appendable appendable, final Object object) throws IOException {
 293  3
         if (object == null) {
 294  1
             throw new NullPointerException("Cannot get the toString of a null identity");
 295  
         }
 296  2
         appendable.append(object.getClass().getName())
 297  
               .append('@')
 298  
               .append(Integer.toHexString(System.identityHashCode(object)));
 299  1
     }
 300  
 
 301  
     /**
 302  
      * <p>Appends the toString that would be produced by {@code Object}
 303  
      * if a class did not override toString itself. {@code null}
 304  
      * will throw a NullPointerException for either of the two parameters. </p>
 305  
      *
 306  
      * <pre>
 307  
      * ObjectUtils.identityToString(builder, "")            = builder.append("java.lang.String@1e23"
 308  
      * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa"
 309  
      * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")
 310  
      * </pre>
 311  
      *
 312  
      * @param builder  the builder to append to
 313  
      * @param object  the object to create a toString for
 314  
      * @since 3.2
 315  
      */
 316  
     public static void identityToString(final StrBuilder builder, final Object object) {
 317  3
         if (object == null) {
 318  1
             throw new NullPointerException("Cannot get the toString of a null identity");
 319  
         }
 320  2
         builder.append(object.getClass().getName())
 321  
               .append('@')
 322  
               .append(Integer.toHexString(System.identityHashCode(object)));
 323  1
     }
 324  
 
 325  
     /**
 326  
      * <p>Appends the toString that would be produced by {@code Object}
 327  
      * if a class did not override toString itself. {@code null}
 328  
      * will throw a NullPointerException for either of the two parameters. </p>
 329  
      *
 330  
      * <pre>
 331  
      * ObjectUtils.identityToString(buf, "")            = buf.append("java.lang.String@1e23"
 332  
      * ObjectUtils.identityToString(buf, Boolean.TRUE)  = buf.append("java.lang.Boolean@7fa"
 333  
      * ObjectUtils.identityToString(buf, Boolean.TRUE)  = buf.append("java.lang.Boolean@7fa")
 334  
      * </pre>
 335  
      *
 336  
      * @param buffer  the buffer to append to
 337  
      * @param object  the object to create a toString for
 338  
      * @since 2.4
 339  
      */
 340  
     public static void identityToString(final StringBuffer buffer, final Object object) {
 341  17
         if (object == null) {
 342  1
             throw new NullPointerException("Cannot get the toString of a null identity");
 343  
         }
 344  16
         buffer.append(object.getClass().getName())
 345  
               .append('@')
 346  
               .append(Integer.toHexString(System.identityHashCode(object)));
 347  15
     }
 348  
 
 349  
     /**
 350  
      * <p>Appends the toString that would be produced by {@code Object}
 351  
      * if a class did not override toString itself. {@code null}
 352  
      * will throw a NullPointerException for either of the two parameters. </p>
 353  
      *
 354  
      * <pre>
 355  
      * ObjectUtils.identityToString(builder, "")            = builder.append("java.lang.String@1e23"
 356  
      * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa"
 357  
      * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")
 358  
      * </pre>
 359  
      *
 360  
      * @param builder  the builder to append to
 361  
      * @param object  the object to create a toString for
 362  
      * @since 3.2
 363  
      */
 364  
     public static void identityToString(final StringBuilder builder, final Object object) {
 365  5
         if (object == null) {
 366  1
             throw new NullPointerException("Cannot get the toString of a null identity");
 367  
         }
 368  4
         builder.append(object.getClass().getName())
 369  
               .append('@')
 370  
               .append(Integer.toHexString(System.identityHashCode(object)));
 371  3
     }
 372  
 
 373  
     // ToString
 374  
     //-----------------------------------------------------------------------
 375  
     /**
 376  
      * <p>Gets the {@code toString} of an {@code Object} returning
 377  
      * an empty string ("") if {@code null} input.</p>
 378  
      *
 379  
      * <pre>
 380  
      * ObjectUtils.toString(null)         = ""
 381  
      * ObjectUtils.toString("")           = ""
 382  
      * ObjectUtils.toString("bat")        = "bat"
 383  
      * ObjectUtils.toString(Boolean.TRUE) = "true"
 384  
      * </pre>
 385  
      *
 386  
      * @see StringUtils#defaultString(String)
 387  
      * @see String#valueOf(Object)
 388  
      * @param obj  the Object to {@code toString}, may be null
 389  
      * @return the passed in Object's toString, or {@code ""} if {@code null} input
 390  
      * @since 2.0
 391  
      * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object)} in Java 7 and will be
 392  
      * removed in future releases. Note however that said method will return "null" for null references, while this
 393  
      * method returns and empty String. To preserve behavior use {@code java.util.Objects.toString(myObject, "")}
 394  
      */
 395  
     @Deprecated
 396  
     public static String toString(final Object obj) {
 397  27
         return obj == null ? "" : obj.toString();
 398  
     }
 399  
 
 400  
     /**
 401  
      * <p>Gets the {@code toString} of an {@code Object} returning
 402  
      * a specified text if {@code null} input.</p>
 403  
      *
 404  
      * <pre>
 405  
      * ObjectUtils.toString(null, null)           = null
 406  
      * ObjectUtils.toString(null, "null")         = "null"
 407  
      * ObjectUtils.toString("", "null")           = ""
 408  
      * ObjectUtils.toString("bat", "null")        = "bat"
 409  
      * ObjectUtils.toString(Boolean.TRUE, "null") = "true"
 410  
      * </pre>
 411  
      *
 412  
      * @see StringUtils#defaultString(String,String)
 413  
      * @see String#valueOf(Object)
 414  
      * @param obj  the Object to {@code toString}, may be null
 415  
      * @param nullStr  the String to return if {@code null} input, may be null
 416  
      * @return the passed in Object's toString, or {@code nullStr} if {@code null} input
 417  
      * @since 2.0
 418  
      * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object, String)} in Java 7 and
 419  
      * will be removed in future releases.
 420  
      */
 421  
     @Deprecated
 422  
     public static String toString(final Object obj, final String nullStr) {
 423  2
         return obj == null ? nullStr : obj.toString();
 424  
     }
 425  
 
 426  
     // Comparable
 427  
     //-----------------------------------------------------------------------
 428  
     /**
 429  
      * <p>Null safe comparison of Comparables.</p>
 430  
      *
 431  
      * @param <T> type of the values processed by this method
 432  
      * @param values the set of comparable values, may be null
 433  
      * @return
 434  
      *  <ul>
 435  
      *   <li>If any objects are non-null and unequal, the lesser object.
 436  
      *   <li>If all objects are non-null and equal, the first.
 437  
      *   <li>If any of the comparables are null, the lesser of the non-null objects.
 438  
      *   <li>If all the comparables are null, null is returned.
 439  
      *  </ul>
 440  
      */
 441  
     public static <T extends Comparable<? super T>> T min(final T... values) {
 442  11
         T result = null;
 443  11
         if (values != null) {
 444  32
             for (final T value : values) {
 445  22
                 if (compare(value, result, true) < 0) {
 446  10
                     result = value;
 447  
                 }
 448  
             }
 449  
         }
 450  11
         return result;
 451  
     }
 452  
 
 453  
     /**
 454  
      * <p>Null safe comparison of Comparables.</p>
 455  
      *
 456  
      * @param <T> type of the values processed by this method
 457  
      * @param values the set of comparable values, may be null
 458  
      * @return
 459  
      *  <ul>
 460  
      *   <li>If any objects are non-null and unequal, the greater object.
 461  
      *   <li>If all objects are non-null and equal, the first.
 462  
      *   <li>If any of the comparables are null, the greater of the non-null objects.
 463  
      *   <li>If all the comparables are null, null is returned.
 464  
      *  </ul>
 465  
      */
 466  
     public static <T extends Comparable<? super T>> T max(final T... values) {
 467  11
         T result = null;
 468  11
         if (values != null) {
 469  32
             for (final T value : values) {
 470  22
                 if (compare(value, result, false) > 0) {
 471  10
                     result = value;
 472  
                 }
 473  
             }
 474  
         }
 475  11
         return result;
 476  
     }
 477  
 
 478  
     /**
 479  
      * <p>Null safe comparison of Comparables.
 480  
      * {@code null} is assumed to be less than a non-{@code null} value.</p>
 481  
      *
 482  
      * @param <T> type of the values processed by this method
 483  
      * @param c1  the first comparable, may be null
 484  
      * @param c2  the second comparable, may be null
 485  
      * @return a negative value if c1 &lt; c2, zero if c1 = c2
 486  
      *  and a positive value if c1 &gt; c2
 487  
      */
 488  
     public static <T extends Comparable<? super T>> int compare(final T c1, final T c2) {
 489  4
         return compare(c1, c2, false);
 490  
     }
 491  
 
 492  
     /**
 493  
      * <p>Null safe comparison of Comparables.</p>
 494  
      *
 495  
      * @param <T> type of the values processed by this method
 496  
      * @param c1  the first comparable, may be null
 497  
      * @param c2  the second comparable, may be null
 498  
      * @param nullGreater if true {@code null} is considered greater
 499  
      *  than a non-{@code null} value or if false {@code null} is
 500  
      *  considered less than a Non-{@code null} value
 501  
      * @return a negative value if c1 &lt; c2, zero if c1 = c2
 502  
      *  and a positive value if c1 &gt; c2
 503  
      * @see java.util.Comparator#compare(Object, Object)
 504  
      */
 505  
     public static <T extends Comparable<? super T>> int compare(final T c1, final T c2, final boolean nullGreater) {
 506  52
         if (c1 == c2) {
 507  14
             return 0;
 508  38
         } else if (c1 == null) {
 509  8
             return nullGreater ? 1 : -1;
 510  30
         } else if (c2 == null) {
 511  18
             return nullGreater ? -1 : 1;
 512  
         }
 513  12
         return c1.compareTo(c2);
 514  
     }
 515  
 
 516  
     /**
 517  
      * Find the "best guess" middle value among comparables. If there is an even
 518  
      * number of total values, the lower of the two middle values will be returned.
 519  
      * @param <T> type of values processed by this method
 520  
      * @param items to compare
 521  
      * @return T at middle position
 522  
      * @throws NullPointerException if items is {@code null}
 523  
      * @throws IllegalArgumentException if items is empty or contains {@code null} values
 524  
      * @since 3.0.1
 525  
      */
 526  
     public static <T extends Comparable<? super T>> T median(final T... items) {
 527  10
         Validate.notEmpty(items);
 528  8
         Validate.noNullElements(items);
 529  8
         final TreeSet<T> sort = new TreeSet<T>();
 530  8
         Collections.addAll(sort, items);
 531  
         @SuppressWarnings("unchecked") //we know all items added were T instances
 532  
         final
 533  8
         T result = (T) sort.toArray()[(sort.size() - 1) / 2];
 534  8
         return result;
 535  
     }
 536  
 
 537  
     /**
 538  
      * Find the "best guess" middle value among comparables. If there is an even
 539  
      * number of total values, the lower of the two middle values will be returned.
 540  
      * @param <T> type of values processed by this method
 541  
      * @param comparator to use for comparisons
 542  
      * @param items to compare
 543  
      * @return T at middle position
 544  
      * @throws NullPointerException if items or comparator is {@code null}
 545  
      * @throws IllegalArgumentException if items is empty or contains {@code null} values
 546  
      * @since 3.0.1
 547  
      */
 548  
     public static <T> T median(final Comparator<T> comparator, final T... items) {
 549  8
         Validate.notEmpty(items, "null/empty items");
 550  6
         Validate.noNullElements(items);
 551  6
         Validate.notNull(comparator, "null comparator");
 552  5
         final TreeSet<T> sort = new TreeSet<T>(comparator);
 553  5
         Collections.addAll(sort, items);
 554  
         @SuppressWarnings("unchecked") //we know all items added were T instances
 555  
         final
 556  5
         T result = (T) sort.toArray()[(sort.size() - 1) / 2];
 557  5
         return result;
 558  
     }
 559  
 
 560  
     // Mode
 561  
     //-----------------------------------------------------------------------
 562  
     /**
 563  
      * Find the most frequently occurring item.
 564  
      * 
 565  
      * @param <T> type of values processed by this method
 566  
      * @param items to check
 567  
      * @return most populous T, {@code null} if non-unique or no items supplied
 568  
      * @since 3.0.1
 569  
      */
 570  
     public static <T> T mode(final T... items) {
 571  6
         if (ArrayUtils.isNotEmpty(items)) {
 572  4
             final HashMap<T, MutableInt> occurrences = new HashMap<T, MutableInt>(items.length);
 573  22
             for (final T t : items) {
 574  18
                 final MutableInt count = occurrences.get(t);
 575  18
                 if (count == null) {
 576  14
                     occurrences.put(t, new MutableInt(1));
 577  
                 } else {
 578  4
                     count.increment();
 579  
                 }
 580  
             }
 581  4
             T result = null;
 582  4
             int max = 0;
 583  4
             for (final Map.Entry<T, MutableInt> e : occurrences.entrySet()) {
 584  14
                 final int cmp = e.getValue().intValue();
 585  14
                 if (cmp == max) {
 586  4
                     result = null;
 587  10
                 } else if (cmp > max) {
 588  5
                     max = cmp;
 589  5
                     result = e.getKey();
 590  
                 }
 591  14
             }
 592  4
             return result;
 593  
         }
 594  2
         return null;
 595  
     }
 596  
 
 597  
     // cloning
 598  
     //-----------------------------------------------------------------------
 599  
     /**
 600  
      * <p>Clone an object.</p>
 601  
      *
 602  
      * @param <T> the type of the object
 603  
      * @param obj  the object to clone, null returns null
 604  
      * @return the clone if the object implements {@link Cloneable} otherwise {@code null}
 605  
      * @throws CloneFailedException if the object is cloneable and the clone operation fails
 606  
      * @since 3.0
 607  
      */
 608  
     public static <T> T clone(final T obj) {
 609  8
         if (obj instanceof Cloneable) {
 610  
             final Object result;
 611  6
             if (obj.getClass().isArray()) {
 612  2
                 final Class<?> componentType = obj.getClass().getComponentType();
 613  2
                 if (!componentType.isPrimitive()) {
 614  1
                     result = ((Object[]) obj).clone();
 615  
                 } else {
 616  1
                     int length = Array.getLength(obj);
 617  1
                     result = Array.newInstance(componentType, length);
 618  2
                     while (length-- > 0) {
 619  1
                         Array.set(result, length, Array.get(obj, length));
 620  
                     }
 621  
                 }
 622  2
             } else {
 623  
                 try {
 624  4
                     final Method clone = obj.getClass().getMethod("clone");
 625  2
                     result = clone.invoke(obj);
 626  2
                 } catch (final NoSuchMethodException e) {
 627  2
                     throw new CloneFailedException("Cloneable type "
 628  
                         + obj.getClass().getName()
 629  
                         + " has no clone method", e);
 630  0
                 } catch (final IllegalAccessException e) {
 631  0
                     throw new CloneFailedException("Cannot clone Cloneable type "
 632  
                         + obj.getClass().getName(), e);
 633  0
                 } catch (final InvocationTargetException e) {
 634  0
                     throw new CloneFailedException("Exception cloning Cloneable type "
 635  
                         + obj.getClass().getName(), e.getCause());
 636  2
                 }
 637  
             }
 638  
             @SuppressWarnings("unchecked") // OK because input is of type T
 639  4
             final T checked = (T) result;
 640  4
             return checked;
 641  
         }
 642  
 
 643  2
         return null;
 644  
     }
 645  
 
 646  
     /**
 647  
      * <p>Clone an object if possible.</p>
 648  
      *
 649  
      * <p>This method is similar to {@link #clone(Object)}, but will return the provided
 650  
      * instance as the return value instead of {@code null} if the instance
 651  
      * is not cloneable. This is more convenient if the caller uses different
 652  
      * implementations (e.g. of a service) and some of the implementations do not allow concurrent
 653  
      * processing or have state. In such cases the implementation can simply provide a proper
 654  
      * clone implementation and the caller's code does not have to change.</p>
 655  
      *
 656  
      * @param <T> the type of the object
 657  
      * @param obj  the object to clone, null returns null
 658  
      * @return the clone if the object implements {@link Cloneable} otherwise the object itself
 659  
      * @throws CloneFailedException if the object is cloneable and the clone operation fails
 660  
      * @since 3.0
 661  
      */
 662  
     public static <T> T cloneIfPossible(final T obj) {
 663  3
         final T clone = clone(obj);
 664  2
         return clone == null ? obj : clone;
 665  
     }
 666  
 
 667  
     // Null
 668  
     //-----------------------------------------------------------------------
 669  
     /**
 670  
      * <p>Class used as a null placeholder where {@code null}
 671  
      * has another meaning.</p>
 672  
      *
 673  
      * <p>For example, in a {@code HashMap} the
 674  
      * {@link java.util.HashMap#get(java.lang.Object)} method returns
 675  
      * {@code null} if the {@code Map} contains {@code null} or if there is
 676  
      * no matching key. The {@code Null} placeholder can be used to distinguish
 677  
      * between these two cases.</p>
 678  
      *
 679  
      * <p>Another example is {@code Hashtable}, where {@code null}
 680  
      * cannot be stored.</p>
 681  
      */
 682  
     public static class Null implements Serializable {
 683  
         /**
 684  
          * Required for serialization support. Declare serialization compatibility with Commons Lang 1.0
 685  
          *
 686  
          * @see java.io.Serializable
 687  
          */
 688  
         private static final long serialVersionUID = 7092611880189329093L;
 689  
 
 690  
         /**
 691  
          * Restricted constructor - singleton.
 692  
          */
 693  
         Null() {
 694  1
             super();
 695  1
         }
 696  
 
 697  
         /**
 698  
          * <p>Ensure singleton.</p>
 699  
          *
 700  
          * @return the singleton value
 701  
          */
 702  
         private Object readResolve() {
 703  1
             return ObjectUtils.NULL;
 704  
         }
 705  
     }
 706  
 
 707  
 
 708  
     // Constants (LANG-816):
 709  
     /*
 710  
         These methods ensure constants are not inlined by javac.
 711  
         For example, typically a developer might declare a constant like so:
 712  
 
 713  
             public final static int MAGIC_NUMBER = 5;
 714  
 
 715  
         Should a different jar file refer to this, and the MAGIC_NUMBER
 716  
         is changed a later date (e.g., MAGIC_NUMBER = 6), the different jar
 717  
         file will need to recompile itself.  This is because javac
 718  
         typically inlines the primitive or String constant directly into
 719  
         the bytecode, and removes the reference to the MAGIC_NUMBER field.
 720  
 
 721  
         To help the other jar (so that it does not need to recompile
 722  
         when constants are changed) the original developer can declare
 723  
         their constant using one of the CONST() utility methods, instead:
 724  
 
 725  
             public final static int MAGIC_NUMBER = CONST(5);
 726  
      */
 727  
 
 728  
 
 729  
     /**
 730  
      * This method returns the provided value unchanged.
 731  
      * This can prevent javac from inlining a constant
 732  
      * field, e.g.,
 733  
      *
 734  
      * <pre>
 735  
      *     public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true);
 736  
      * </pre>
 737  
      *
 738  
      * This way any jars that refer to this field do not
 739  
      * have to recompile themselves if the field's value
 740  
      * changes at some future date.
 741  
      *
 742  
      * @param v the boolean value to return
 743  
      * @return the boolean v, unchanged
 744  
      * @since 3.2
 745  
      */
 746  2
     public static boolean CONST(final boolean v) { return v; }
 747  
 
 748  
     /**
 749  
      * This method returns the provided value unchanged.
 750  
      * This can prevent javac from inlining a constant
 751  
      * field, e.g.,
 752  
      *
 753  
      * <pre>
 754  
      *     public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127);
 755  
      * </pre>
 756  
      *
 757  
      * This way any jars that refer to this field do not
 758  
      * have to recompile themselves if the field's value
 759  
      * changes at some future date.
 760  
      *
 761  
      * @param v the byte value to return
 762  
      * @return the byte v, unchanged
 763  
      * @since 3.2
 764  
      */
 765  2
     public static byte CONST(final byte v) { return v; }
 766  
 
 767  
     /**
 768  
      * This method returns the provided value unchanged.
 769  
      * This can prevent javac from inlining a constant
 770  
      * field, e.g.,
 771  
      *
 772  
      * <pre>
 773  
      *     public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127);
 774  
      * </pre>
 775  
      *
 776  
      * This way any jars that refer to this field do not
 777  
      * have to recompile themselves if the field's value
 778  
      * changes at some future date.
 779  
      *
 780  
      * @param v the byte literal (as an int) value to return
 781  
      * @throws IllegalArgumentException if the value passed to v
 782  
      *         is larger than a byte, that is, smaller than -128 or
 783  
      *         larger than 127.
 784  
      * @return the byte v, unchanged
 785  
      * @since 3.2
 786  
      */
 787  
     public static byte CONST_BYTE(final int v) throws IllegalArgumentException {
 788  4
         if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) {
 789  3
             throw new IllegalArgumentException("Supplied value must be a valid byte literal between -128 and 127: [" + v + "]");
 790  
         }
 791  1
         return (byte) v;
 792  
     }
 793  
 
 794  
     /**
 795  
      * This method returns the provided value unchanged.
 796  
      * This can prevent javac from inlining a constant
 797  
      * field, e.g.,
 798  
      *
 799  
      * <pre>
 800  
      *     public final static char MAGIC_CHAR = ObjectUtils.CONST('a');
 801  
      * </pre>
 802  
      *
 803  
      * This way any jars that refer to this field do not
 804  
      * have to recompile themselves if the field's value
 805  
      * changes at some future date.
 806  
      *
 807  
      * @param v the char value to return
 808  
      * @return the char v, unchanged
 809  
      * @since 3.2
 810  
      */
 811  2
     public static char CONST(final char v) { return v; }
 812  
 
 813  
     /**
 814  
      * This method returns the provided value unchanged.
 815  
      * This can prevent javac from inlining a constant
 816  
      * field, e.g.,
 817  
      *
 818  
      * <pre>
 819  
      *     public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123);
 820  
      * </pre>
 821  
      *
 822  
      * This way any jars that refer to this field do not
 823  
      * have to recompile themselves if the field's value
 824  
      * changes at some future date.
 825  
      *
 826  
      * @param v the short value to return
 827  
      * @return the short v, unchanged
 828  
      * @since 3.2
 829  
      */
 830  2
     public static short CONST(final short v) { return v; }
 831  
 
 832  
     /**
 833  
      * This method returns the provided value unchanged.
 834  
      * This can prevent javac from inlining a constant
 835  
      * field, e.g.,
 836  
      *
 837  
      * <pre>
 838  
      *     public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127);
 839  
      * </pre>
 840  
      *
 841  
      * This way any jars that refer to this field do not
 842  
      * have to recompile themselves if the field's value
 843  
      * changes at some future date.
 844  
      *
 845  
      * @param v the short literal (as an int) value to return
 846  
      * @throws IllegalArgumentException if the value passed to v
 847  
      *         is larger than a short, that is, smaller than -32768 or
 848  
      *         larger than 32767.
 849  
      * @return the byte v, unchanged
 850  
      * @since 3.2
 851  
      */
 852  
     public static short CONST_SHORT(final int v) throws IllegalArgumentException {
 853  2
         if (v < Short.MIN_VALUE || v > Short.MAX_VALUE) {
 854  1
             throw new IllegalArgumentException("Supplied value must be a valid byte literal between -32768 and 32767: [" + v + "]");
 855  
         }
 856  1
         return (short) v;
 857  
     }
 858  
 
 859  
 
 860  
     /**
 861  
      * This method returns the provided value unchanged.
 862  
      * This can prevent javac from inlining a constant
 863  
      * field, e.g.,
 864  
      *
 865  
      * <pre>
 866  
      *     public final static int MAGIC_INT = ObjectUtils.CONST(123);
 867  
      * </pre>
 868  
      *
 869  
      * This way any jars that refer to this field do not
 870  
      * have to recompile themselves if the field's value
 871  
      * changes at some future date.
 872  
      *
 873  
      * @param v the int value to return
 874  
      * @return the int v, unchanged
 875  
      * @since 3.2
 876  
      */
 877  3
     public static int CONST(final int v) { return v; }
 878  
 
 879  
     /**
 880  
      * This method returns the provided value unchanged.
 881  
      * This can prevent javac from inlining a constant
 882  
      * field, e.g.,
 883  
      *
 884  
      * <pre>
 885  
      *     public final static long MAGIC_LONG = ObjectUtils.CONST(123L);
 886  
      * </pre>
 887  
      *
 888  
      * This way any jars that refer to this field do not
 889  
      * have to recompile themselves if the field's value
 890  
      * changes at some future date.
 891  
      *
 892  
      * @param v the long value to return
 893  
      * @return the long v, unchanged
 894  
      * @since 3.2
 895  
      */
 896  2
     public static long CONST(final long v) { return v; }
 897  
 
 898  
     /**
 899  
      * This method returns the provided value unchanged.
 900  
      * This can prevent javac from inlining a constant
 901  
      * field, e.g.,
 902  
      *
 903  
      * <pre>
 904  
      *     public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f);
 905  
      * </pre>
 906  
      *
 907  
      * This way any jars that refer to this field do not
 908  
      * have to recompile themselves if the field's value
 909  
      * changes at some future date.
 910  
      *
 911  
      * @param v the float value to return
 912  
      * @return the float v, unchanged
 913  
      * @since 3.2
 914  
      */
 915  2
     public static float CONST(final float v) { return v; }
 916  
 
 917  
     /**
 918  
      * This method returns the provided value unchanged.
 919  
      * This can prevent javac from inlining a constant
 920  
      * field, e.g.,
 921  
      *
 922  
      * <pre>
 923  
      *     public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0);
 924  
      * </pre>
 925  
      *
 926  
      * This way any jars that refer to this field do not
 927  
      * have to recompile themselves if the field's value
 928  
      * changes at some future date.
 929  
      *
 930  
      * @param v the double value to return
 931  
      * @return the double v, unchanged
 932  
      * @since 3.2
 933  
      */
 934  2
     public static double CONST(final double v) { return v; }
 935  
 
 936  
     /**
 937  
      * This method returns the provided value unchanged.
 938  
      * This can prevent javac from inlining a constant
 939  
      * field, e.g.,
 940  
      *
 941  
      * <pre>
 942  
      *     public final static String MAGIC_STRING = ObjectUtils.CONST("abc");
 943  
      * </pre>
 944  
      *
 945  
      * This way any jars that refer to this field do not
 946  
      * have to recompile themselves if the field's value
 947  
      * changes at some future date.
 948  
      *
 949  
      * @param <T> the Object type 
 950  
      * @param v the genericized Object value to return (typically a String).
 951  
      * @return the genericized Object v, unchanged (typically a String).
 952  
      * @since 3.2
 953  
      */
 954  2
     public static <T> T CONST(final T v) { return v; }
 955  
 
 956  
 }