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 */
017package org.apache.commons.lang3;
018
019import java.io.IOException;
020import java.io.Serializable;
021import java.lang.reflect.Array;
022import java.lang.reflect.InvocationTargetException;
023import java.lang.reflect.Method;
024import java.util.Collections;
025import java.util.Comparator;
026import java.util.HashMap;
027import java.util.Map;
028import java.util.TreeSet;
029
030import org.apache.commons.lang3.exception.CloneFailedException;
031import org.apache.commons.lang3.mutable.MutableInt;
032import org.apache.commons.lang3.text.StrBuilder;
033
034/**
035 * <p>Operations on {@code Object}.</p>
036 *
037 * <p>This class tries to handle {@code null} input gracefully.
038 * An exception will generally not be thrown for a {@code null} input.
039 * Each method documents its behaviour in more detail.</p>
040 *
041 * <p>#ThreadSafe#</p>
042 * @since 1.0
043 * @version $Id: ObjectUtils.java 1669786 2015-03-28 15:09:29Z britter $
044 */
045//@Immutable
046public class ObjectUtils {
047
048    /**
049     * <p>Singleton used as a {@code null} placeholder where
050     * {@code null} has another meaning.</p>
051     *
052     * <p>For example, in a {@code HashMap} the
053     * {@link java.util.HashMap#get(java.lang.Object)} method returns
054     * {@code null} if the {@code Map} contains {@code null} or if there
055     * is no matching key. The {@code Null} placeholder can be used to
056     * distinguish between these two cases.</p>
057     *
058     * <p>Another example is {@code Hashtable}, where {@code null}
059     * cannot be stored.</p>
060     *
061     * <p>This instance is Serializable.</p>
062     */
063    public static final Null NULL = new Null();
064
065    /**
066     * <p>{@code ObjectUtils} instances should NOT be constructed in
067     * standard programming. Instead, the static methods on the class should
068     * be used, such as {@code ObjectUtils.defaultIfNull("a","b");}.</p>
069     *
070     * <p>This constructor is public to permit tools that require a JavaBean
071     * instance to operate.</p>
072     */
073    public ObjectUtils() {
074        super();
075    }
076
077    // Defaulting
078    //-----------------------------------------------------------------------
079    /**
080     * <p>Returns a default value if the object passed is {@code null}.</p>
081     *
082     * <pre>
083     * ObjectUtils.defaultIfNull(null, null)      = null
084     * ObjectUtils.defaultIfNull(null, "")        = ""
085     * ObjectUtils.defaultIfNull(null, "zz")      = "zz"
086     * ObjectUtils.defaultIfNull("abc", *)        = "abc"
087     * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE
088     * </pre>
089     *
090     * @param <T> the type of the object
091     * @param object  the {@code Object} to test, may be {@code null}
092     * @param defaultValue  the default value to return, may be {@code null}
093     * @return {@code object} if it is not {@code null}, defaultValue otherwise
094     */
095    public static <T> T defaultIfNull(final T object, final T defaultValue) {
096        return object != null ? object : defaultValue;
097    }
098
099    /**
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        if (values != null) {
123            for (final T val : values) {
124                if (val != null) {
125                    return val;
126                }
127            }
128        }
129        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        if (object1 == object2) {
158            return true;
159        }
160        if (object1 == null || object2 == null) {
161            return false;
162        }
163        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        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        return obj == null ? 0 : obj.hashCode();
208    }
209
210    /**
211     * <p>Gets the hash code for multiple objects.</p>
212     * 
213     * <p>This allows a hash code to be rapidly calculated for a number of objects.
214     * The hash code for a single object is the <em>not</em> same as {@link #hashCode(Object)}.
215     * The hash code for multiple objects is the same as that calculated by an
216     * {@code ArrayList} containing the specified objects.</p>
217     *
218     * <pre>
219     * ObjectUtils.hashCodeMulti()                 = 1
220     * ObjectUtils.hashCodeMulti((Object[]) null)  = 1
221     * ObjectUtils.hashCodeMulti(a)                = 31 + a.hashCode()
222     * ObjectUtils.hashCodeMulti(a,b)              = (31 + a.hashCode()) * 31 + b.hashCode()
223     * ObjectUtils.hashCodeMulti(a,b,c)            = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode()
224     * </pre>
225     *
226     * @param objects  the objects to obtain the hash code of, may be {@code null}
227     * @return the hash code of the objects, or zero if null
228     * @since 3.0
229     * @deprecated this method has been replaced by {@code java.util.Objects.hash(Object...)} in Java 7 and will be
230     * removed in future releases.
231     */
232    @Deprecated
233    public static int hashCodeMulti(final Object... objects) {
234        int hash = 1;
235        if (objects != null) {
236            for (final Object object : objects) {
237                final int tmpHash = ObjectUtils.hashCode(object);
238                hash = hash * 31 + tmpHash;
239            }
240        }
241        return hash;
242    }
243
244    // Identity ToString
245    //-----------------------------------------------------------------------
246    /**
247     * <p>Gets the toString that would be produced by {@code Object}
248     * if a class did not override toString itself. {@code null}
249     * will return {@code null}.</p>
250     *
251     * <pre>
252     * ObjectUtils.identityToString(null)         = null
253     * ObjectUtils.identityToString("")           = "java.lang.String@1e23"
254     * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa"
255     * </pre>
256     *
257     * @param object  the object to create a toString for, may be
258     *  {@code null}
259     * @return the default toString text, or {@code null} if
260     *  {@code null} passed in
261     */
262    public static String identityToString(final Object object) {
263        if (object == null) {
264            return null;
265        }
266        final StringBuilder builder = new StringBuilder();
267        identityToString(builder, object);
268        return builder.toString();
269    }
270
271    /**
272     * <p>Appends the toString that would be produced by {@code Object}
273     * if a class did not override toString itself. {@code null}
274     * will throw a NullPointerException for either of the two parameters. </p>
275     *
276     * <pre>
277     * ObjectUtils.identityToString(appendable, "")            = appendable.append("java.lang.String@1e23"
278     * ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa"
279     * ObjectUtils.identityToString(appendable, Boolean.TRUE)  = appendable.append("java.lang.Boolean@7fa")
280     * </pre>
281     *
282     * @param appendable  the appendable to append to
283     * @param object  the object to create a toString for
284     * @throws IOException if an I/O error occurs
285     * @since 3.2
286     */
287    public static void identityToString(final Appendable appendable, final Object object) throws IOException {
288        if (object == null) {
289            throw new NullPointerException("Cannot get the toString of a null identity");
290        }
291        appendable.append(object.getClass().getName())
292              .append('@')
293              .append(Integer.toHexString(System.identityHashCode(object)));
294    }
295
296    /**
297     * <p>Appends the toString that would be produced by {@code Object}
298     * if a class did not override toString itself. {@code null}
299     * will throw a NullPointerException for either of the two parameters. </p>
300     *
301     * <pre>
302     * ObjectUtils.identityToString(builder, "")            = builder.append("java.lang.String@1e23"
303     * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa"
304     * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")
305     * </pre>
306     *
307     * @param builder  the builder to append to
308     * @param object  the object to create a toString for
309     * @since 3.2
310     */
311    public static void identityToString(final StrBuilder builder, final Object object) {
312        if (object == null) {
313            throw new NullPointerException("Cannot get the toString of a null identity");
314        }
315        builder.append(object.getClass().getName())
316              .append('@')
317              .append(Integer.toHexString(System.identityHashCode(object)));
318    }
319
320    /**
321     * <p>Appends the toString that would be produced by {@code Object}
322     * if a class did not override toString itself. {@code null}
323     * will throw a NullPointerException for either of the two parameters. </p>
324     *
325     * <pre>
326     * ObjectUtils.identityToString(buf, "")            = buf.append("java.lang.String@1e23"
327     * ObjectUtils.identityToString(buf, Boolean.TRUE)  = buf.append("java.lang.Boolean@7fa"
328     * ObjectUtils.identityToString(buf, Boolean.TRUE)  = buf.append("java.lang.Boolean@7fa")
329     * </pre>
330     *
331     * @param buffer  the buffer to append to
332     * @param object  the object to create a toString for
333     * @since 2.4
334     */
335    public static void identityToString(final StringBuffer buffer, final Object object) {
336        if (object == null) {
337            throw new NullPointerException("Cannot get the toString of a null identity");
338        }
339        buffer.append(object.getClass().getName())
340              .append('@')
341              .append(Integer.toHexString(System.identityHashCode(object)));
342    }
343
344    /**
345     * <p>Appends the toString that would be produced by {@code Object}
346     * if a class did not override toString itself. {@code null}
347     * will throw a NullPointerException for either of the two parameters. </p>
348     *
349     * <pre>
350     * ObjectUtils.identityToString(builder, "")            = builder.append("java.lang.String@1e23"
351     * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa"
352     * ObjectUtils.identityToString(builder, Boolean.TRUE)  = builder.append("java.lang.Boolean@7fa")
353     * </pre>
354     *
355     * @param builder  the builder to append to
356     * @param object  the object to create a toString for
357     * @since 3.2
358     */
359    public static void identityToString(final StringBuilder builder, final Object object) {
360        if (object == null) {
361            throw new NullPointerException("Cannot get the toString of a null identity");
362        }
363        builder.append(object.getClass().getName())
364              .append('@')
365              .append(Integer.toHexString(System.identityHashCode(object)));
366    }
367
368    // ToString
369    //-----------------------------------------------------------------------
370    /**
371     * <p>Gets the {@code toString} of an {@code Object} returning
372     * an empty string ("") if {@code null} input.</p>
373     *
374     * <pre>
375     * ObjectUtils.toString(null)         = ""
376     * ObjectUtils.toString("")           = ""
377     * ObjectUtils.toString("bat")        = "bat"
378     * ObjectUtils.toString(Boolean.TRUE) = "true"
379     * </pre>
380     *
381     * @see StringUtils#defaultString(String)
382     * @see String#valueOf(Object)
383     * @param obj  the Object to {@code toString}, may be null
384     * @return the passed in Object's toString, or {@code ""} if {@code null} input
385     * @since 2.0
386     * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object)} in Java 7 and will be
387     * removed in future releases. Note however that said method will return "null" for null references, while this
388     * method returns and empty String. To preserve behavior use {@code java.util.Objects.toString(myObject, "")}
389     */
390    @Deprecated
391    public static String toString(final Object obj) {
392        return obj == null ? "" : obj.toString();
393    }
394
395    /**
396     * <p>Gets the {@code toString} of an {@code Object} returning
397     * a specified text if {@code null} input.</p>
398     *
399     * <pre>
400     * ObjectUtils.toString(null, null)           = null
401     * ObjectUtils.toString(null, "null")         = "null"
402     * ObjectUtils.toString("", "null")           = ""
403     * ObjectUtils.toString("bat", "null")        = "bat"
404     * ObjectUtils.toString(Boolean.TRUE, "null") = "true"
405     * </pre>
406     *
407     * @see StringUtils#defaultString(String,String)
408     * @see String#valueOf(Object)
409     * @param obj  the Object to {@code toString}, may be null
410     * @param nullStr  the String to return if {@code null} input, may be null
411     * @return the passed in Object's toString, or {@code nullStr} if {@code null} input
412     * @since 2.0
413     * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object, String)} in Java 7 and
414     * will be removed in future releases.
415     */
416    @Deprecated
417    public static String toString(final Object obj, final String nullStr) {
418        return obj == null ? nullStr : obj.toString();
419    }
420
421    // Comparable
422    //-----------------------------------------------------------------------
423    /**
424     * <p>Null safe comparison of Comparables.</p>
425     *
426     * @param <T> type of the values processed by this method
427     * @param values the set of comparable values, may be null
428     * @return
429     *  <ul>
430     *   <li>If any objects are non-null and unequal, the lesser object.
431     *   <li>If all objects are non-null and equal, the first.
432     *   <li>If any of the comparables are null, the lesser of the non-null objects.
433     *   <li>If all the comparables are null, null is returned.
434     *  </ul>
435     */
436    public static <T extends Comparable<? super T>> T min(final T... values) {
437        T result = null;
438        if (values != null) {
439            for (final T value : values) {
440                if (compare(value, result, true) < 0) {
441                    result = value;
442                }
443            }
444        }
445        return result;
446    }
447
448    /**
449     * <p>Null safe comparison of Comparables.</p>
450     *
451     * @param <T> type of the values processed by this method
452     * @param values the set of comparable values, may be null
453     * @return
454     *  <ul>
455     *   <li>If any objects are non-null and unequal, the greater object.
456     *   <li>If all objects are non-null and equal, the first.
457     *   <li>If any of the comparables are null, the greater of the non-null objects.
458     *   <li>If all the comparables are null, null is returned.
459     *  </ul>
460     */
461    public static <T extends Comparable<? super T>> T max(final T... values) {
462        T result = null;
463        if (values != null) {
464            for (final T value : values) {
465                if (compare(value, result, false) > 0) {
466                    result = value;
467                }
468            }
469        }
470        return result;
471    }
472
473    /**
474     * <p>Null safe comparison of Comparables.
475     * {@code null} is assumed to be less than a non-{@code null} value.</p>
476     *
477     * @param <T> type of the values processed by this method
478     * @param c1  the first comparable, may be null
479     * @param c2  the second comparable, may be null
480     * @return a negative value if c1 &lt; c2, zero if c1 = c2
481     *  and a positive value if c1 &gt; c2
482     */
483    public static <T extends Comparable<? super T>> int compare(final T c1, final T c2) {
484        return compare(c1, c2, false);
485    }
486
487    /**
488     * <p>Null safe comparison of Comparables.</p>
489     *
490     * @param <T> type of the values processed by this method
491     * @param c1  the first comparable, may be null
492     * @param c2  the second comparable, may be null
493     * @param nullGreater if true {@code null} is considered greater
494     *  than a non-{@code null} value or if false {@code null} is
495     *  considered less than a Non-{@code null} value
496     * @return a negative value if c1 &lt; c2, zero if c1 = c2
497     *  and a positive value if c1 &gt; c2
498     * @see java.util.Comparator#compare(Object, Object)
499     */
500    public static <T extends Comparable<? super T>> int compare(final T c1, final T c2, final boolean nullGreater) {
501        if (c1 == c2) {
502            return 0;
503        } else if (c1 == null) {
504            return nullGreater ? 1 : -1;
505        } else if (c2 == null) {
506            return nullGreater ? -1 : 1;
507        }
508        return c1.compareTo(c2);
509    }
510
511    /**
512     * Find the "best guess" middle value among comparables. If there is an even
513     * number of total values, the lower of the two middle values will be returned.
514     * @param <T> type of values processed by this method
515     * @param items to compare
516     * @return T at middle position
517     * @throws NullPointerException if items is {@code null}
518     * @throws IllegalArgumentException if items is empty or contains {@code null} values
519     * @since 3.0.1
520     */
521    public static <T extends Comparable<? super T>> T median(final T... items) {
522        Validate.notEmpty(items);
523        Validate.noNullElements(items);
524        final TreeSet<T> sort = new TreeSet<T>();
525        Collections.addAll(sort, items);
526        @SuppressWarnings("unchecked") //we know all items added were T instances
527        final
528        T result = (T) sort.toArray()[(sort.size() - 1) / 2];
529        return result;
530    }
531
532    /**
533     * Find the "best guess" middle value among comparables. If there is an even
534     * number of total values, the lower of the two middle values will be returned.
535     * @param <T> type of values processed by this method
536     * @param comparator to use for comparisons
537     * @param items to compare
538     * @return T at middle position
539     * @throws NullPointerException if items or comparator is {@code null}
540     * @throws IllegalArgumentException if items is empty or contains {@code null} values
541     * @since 3.0.1
542     */
543    public static <T> T median(final Comparator<T> comparator, final T... items) {
544        Validate.notEmpty(items, "null/empty items");
545        Validate.noNullElements(items);
546        Validate.notNull(comparator, "null comparator");
547        final TreeSet<T> sort = new TreeSet<T>(comparator);
548        Collections.addAll(sort, items);
549        @SuppressWarnings("unchecked") //we know all items added were T instances
550        final
551        T result = (T) sort.toArray()[(sort.size() - 1) / 2];
552        return result;
553    }
554
555    // Mode
556    //-----------------------------------------------------------------------
557    /**
558     * Find the most frequently occurring item.
559     * 
560     * @param <T> type of values processed by this method
561     * @param items to check
562     * @return most populous T, {@code null} if non-unique or no items supplied
563     * @since 3.0.1
564     */
565    public static <T> T mode(final T... items) {
566        if (ArrayUtils.isNotEmpty(items)) {
567            final HashMap<T, MutableInt> occurrences = new HashMap<T, MutableInt>(items.length);
568            for (final T t : items) {
569                final MutableInt count = occurrences.get(t);
570                if (count == null) {
571                    occurrences.put(t, new MutableInt(1));
572                } else {
573                    count.increment();
574                }
575            }
576            T result = null;
577            int max = 0;
578            for (final Map.Entry<T, MutableInt> e : occurrences.entrySet()) {
579                final int cmp = e.getValue().intValue();
580                if (cmp == max) {
581                    result = null;
582                } else if (cmp > max) {
583                    max = cmp;
584                    result = e.getKey();
585                }
586            }
587            return result;
588        }
589        return null;
590    }
591
592    // cloning
593    //-----------------------------------------------------------------------
594    /**
595     * <p>Clone an object.</p>
596     *
597     * @param <T> the type of the object
598     * @param obj  the object to clone, null returns null
599     * @return the clone if the object implements {@link Cloneable} otherwise {@code null}
600     * @throws CloneFailedException if the object is cloneable and the clone operation fails
601     * @since 3.0
602     */
603    public static <T> T clone(final T obj) {
604        if (obj instanceof Cloneable) {
605            final Object result;
606            if (obj.getClass().isArray()) {
607                final Class<?> componentType = obj.getClass().getComponentType();
608                if (!componentType.isPrimitive()) {
609                    result = ((Object[]) obj).clone();
610                } else {
611                    int length = Array.getLength(obj);
612                    result = Array.newInstance(componentType, length);
613                    while (length-- > 0) {
614                        Array.set(result, length, Array.get(obj, length));
615                    }
616                }
617            } else {
618                try {
619                    final Method clone = obj.getClass().getMethod("clone");
620                    result = clone.invoke(obj);
621                } catch (final NoSuchMethodException e) {
622                    throw new CloneFailedException("Cloneable type "
623                        + obj.getClass().getName()
624                        + " has no clone method", e);
625                } catch (final IllegalAccessException e) {
626                    throw new CloneFailedException("Cannot clone Cloneable type "
627                        + obj.getClass().getName(), e);
628                } catch (final InvocationTargetException e) {
629                    throw new CloneFailedException("Exception cloning Cloneable type "
630                        + obj.getClass().getName(), e.getCause());
631                }
632            }
633            @SuppressWarnings("unchecked") // OK because input is of type T
634            final T checked = (T) result;
635            return checked;
636        }
637
638        return null;
639    }
640
641    /**
642     * <p>Clone an object if possible.</p>
643     *
644     * <p>This method is similar to {@link #clone(Object)}, but will return the provided
645     * instance as the return value instead of {@code null} if the instance
646     * is not cloneable. This is more convenient if the caller uses different
647     * implementations (e.g. of a service) and some of the implementations do not allow concurrent
648     * processing or have state. In such cases the implementation can simply provide a proper
649     * clone implementation and the caller's code does not have to change.</p>
650     *
651     * @param <T> the type of the object
652     * @param obj  the object to clone, null returns null
653     * @return the clone if the object implements {@link Cloneable} otherwise the object itself
654     * @throws CloneFailedException if the object is cloneable and the clone operation fails
655     * @since 3.0
656     */
657    public static <T> T cloneIfPossible(final T obj) {
658        final T clone = clone(obj);
659        return clone == null ? obj : clone;
660    }
661
662    // Null
663    //-----------------------------------------------------------------------
664    /**
665     * <p>Class used as a null placeholder where {@code null}
666     * has another meaning.</p>
667     *
668     * <p>For example, in a {@code HashMap} the
669     * {@link java.util.HashMap#get(java.lang.Object)} method returns
670     * {@code null} if the {@code Map} contains {@code null} or if there is
671     * no matching key. The {@code Null} placeholder can be used to distinguish
672     * between these two cases.</p>
673     *
674     * <p>Another example is {@code Hashtable}, where {@code null}
675     * cannot be stored.</p>
676     */
677    public static class Null implements Serializable {
678        /**
679         * Required for serialization support. Declare serialization compatibility with Commons Lang 1.0
680         *
681         * @see java.io.Serializable
682         */
683        private static final long serialVersionUID = 7092611880189329093L;
684
685        /**
686         * Restricted constructor - singleton.
687         */
688        Null() {
689            super();
690        }
691
692        /**
693         * <p>Ensure singleton.</p>
694         *
695         * @return the singleton value
696         */
697        private Object readResolve() {
698            return ObjectUtils.NULL;
699        }
700    }
701
702
703    // Constants (LANG-816):
704    /*
705        These methods ensure constants are not inlined by javac.
706        For example, typically a developer might declare a constant like so:
707
708            public final static int MAGIC_NUMBER = 5;
709
710        Should a different jar file refer to this, and the MAGIC_NUMBER
711        is changed a later date (e.g., MAGIC_NUMBER = 6), the different jar
712        file will need to recompile itself.  This is because javac
713        typically inlines the primitive or String constant directly into
714        the bytecode, and removes the reference to the MAGIC_NUMBER field.
715
716        To help the other jar (so that it does not need to recompile
717        when constants are changed) the original developer can declare
718        their constant using one of the CONST() utility methods, instead:
719
720            public final static int MAGIC_NUMBER = CONST(5);
721     */
722
723
724    /**
725     * This method returns the provided value unchanged.
726     * This can prevent javac from inlining a constant
727     * field, e.g.,
728     *
729     * <pre>
730     *     public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true);
731     * </pre>
732     *
733     * This way any jars that refer to this field do not
734     * have to recompile themselves if the field's value
735     * changes at some future date.
736     *
737     * @param v the boolean value to return
738     * @return the boolean v, unchanged
739     * @since 3.2
740     */
741    public static boolean CONST(final boolean v) { return v; }
742
743    /**
744     * This method returns the provided value unchanged.
745     * This can prevent javac from inlining a constant
746     * field, e.g.,
747     *
748     * <pre>
749     *     public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127);
750     * </pre>
751     *
752     * This way any jars that refer to this field do not
753     * have to recompile themselves if the field's value
754     * changes at some future date.
755     *
756     * @param v the byte value to return
757     * @return the byte v, unchanged
758     * @since 3.2
759     */
760    public static byte CONST(final byte v) { return v; }
761
762    /**
763     * This method returns the provided value unchanged.
764     * This can prevent javac from inlining a constant
765     * field, e.g.,
766     *
767     * <pre>
768     *     public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127);
769     * </pre>
770     *
771     * This way any jars that refer to this field do not
772     * have to recompile themselves if the field's value
773     * changes at some future date.
774     *
775     * @param v the byte literal (as an int) value to return
776     * @throws IllegalArgumentException if the value passed to v
777     *         is larger than a byte, that is, smaller than -128 or
778     *         larger than 127.
779     * @return the byte v, unchanged
780     * @since 3.2
781     */
782    public static byte CONST_BYTE(final int v) throws IllegalArgumentException {
783        if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) {
784            throw new IllegalArgumentException("Supplied value must be a valid byte literal between -128 and 127: [" + v + "]");
785        }
786        return (byte) v;
787    }
788
789    /**
790     * This method returns the provided value unchanged.
791     * This can prevent javac from inlining a constant
792     * field, e.g.,
793     *
794     * <pre>
795     *     public final static char MAGIC_CHAR = ObjectUtils.CONST('a');
796     * </pre>
797     *
798     * This way any jars that refer to this field do not
799     * have to recompile themselves if the field's value
800     * changes at some future date.
801     *
802     * @param v the char value to return
803     * @return the char v, unchanged
804     * @since 3.2
805     */
806    public static char CONST(final char v) { return v; }
807
808    /**
809     * This method returns the provided value unchanged.
810     * This can prevent javac from inlining a constant
811     * field, e.g.,
812     *
813     * <pre>
814     *     public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123);
815     * </pre>
816     *
817     * This way any jars that refer to this field do not
818     * have to recompile themselves if the field's value
819     * changes at some future date.
820     *
821     * @param v the short value to return
822     * @return the short v, unchanged
823     * @since 3.2
824     */
825    public static short CONST(final short v) { return v; }
826
827    /**
828     * This method returns the provided value unchanged.
829     * This can prevent javac from inlining a constant
830     * field, e.g.,
831     *
832     * <pre>
833     *     public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127);
834     * </pre>
835     *
836     * This way any jars that refer to this field do not
837     * have to recompile themselves if the field's value
838     * changes at some future date.
839     *
840     * @param v the short literal (as an int) value to return
841     * @throws IllegalArgumentException if the value passed to v
842     *         is larger than a short, that is, smaller than -32768 or
843     *         larger than 32767.
844     * @return the byte v, unchanged
845     * @since 3.2
846     */
847    public static short CONST_SHORT(final int v) throws IllegalArgumentException {
848        if (v < Short.MIN_VALUE || v > Short.MAX_VALUE) {
849            throw new IllegalArgumentException("Supplied value must be a valid byte literal between -32768 and 32767: [" + v + "]");
850        }
851        return (short) v;
852    }
853
854
855    /**
856     * This method returns the provided value unchanged.
857     * This can prevent javac from inlining a constant
858     * field, e.g.,
859     *
860     * <pre>
861     *     public final static int MAGIC_INT = ObjectUtils.CONST(123);
862     * </pre>
863     *
864     * This way any jars that refer to this field do not
865     * have to recompile themselves if the field's value
866     * changes at some future date.
867     *
868     * @param v the int value to return
869     * @return the int v, unchanged
870     * @since 3.2
871     */
872    public static int CONST(final int v) { return v; }
873
874    /**
875     * This method returns the provided value unchanged.
876     * This can prevent javac from inlining a constant
877     * field, e.g.,
878     *
879     * <pre>
880     *     public final static long MAGIC_LONG = ObjectUtils.CONST(123L);
881     * </pre>
882     *
883     * This way any jars that refer to this field do not
884     * have to recompile themselves if the field's value
885     * changes at some future date.
886     *
887     * @param v the long value to return
888     * @return the long v, unchanged
889     * @since 3.2
890     */
891    public static long CONST(final long v) { return v; }
892
893    /**
894     * This method returns the provided value unchanged.
895     * This can prevent javac from inlining a constant
896     * field, e.g.,
897     *
898     * <pre>
899     *     public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f);
900     * </pre>
901     *
902     * This way any jars that refer to this field do not
903     * have to recompile themselves if the field's value
904     * changes at some future date.
905     *
906     * @param v the float value to return
907     * @return the float v, unchanged
908     * @since 3.2
909     */
910    public static float CONST(final float v) { return v; }
911
912    /**
913     * This method returns the provided value unchanged.
914     * This can prevent javac from inlining a constant
915     * field, e.g.,
916     *
917     * <pre>
918     *     public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0);
919     * </pre>
920     *
921     * This way any jars that refer to this field do not
922     * have to recompile themselves if the field's value
923     * changes at some future date.
924     *
925     * @param v the double value to return
926     * @return the double v, unchanged
927     * @since 3.2
928     */
929    public static double CONST(final double v) { return v; }
930
931    /**
932     * This method returns the provided value unchanged.
933     * This can prevent javac from inlining a constant
934     * field, e.g.,
935     *
936     * <pre>
937     *     public final static String MAGIC_STRING = ObjectUtils.CONST("abc");
938     * </pre>
939     *
940     * This way any jars that refer to this field do not
941     * have to recompile themselves if the field's value
942     * changes at some future date.
943     *
944     * @param <T> the Object type 
945     * @param v the genericized Object value to return (typically a String).
946     * @return the genericized Object v, unchanged (typically a String).
947     * @since 3.2
948     */
949    public static <T> T CONST(final T v) { return v; }
950
951}