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