diff --git a/Java/commons-lang-ObjectUtils_121/Dockerfile b/Java/commons-lang-ObjectUtils_121/Dockerfile new file mode 100644 index 000000000..7b7fbe349 --- /dev/null +++ b/Java/commons-lang-ObjectUtils_121/Dockerfile @@ -0,0 +1,18 @@ +FROM ghcr.io/kupl/starlab-benchmarks/java-base:commons-lang + +ENV TZ=Asia/Seoul + +COPY ./metadata.json . +COPY ./npe.json . +COPY ./buggy.java /tmp/buggy.java +RUN export BUGGY_PATH=$(cat metadata.json | jq -r ".npe.filepath") \ + && export BUGGY_LINE=$(cat metadata.json | jq -r ".npe.line") \ + && export BUGGY_MTHD=$(cat metadata.json | jq -r ".npe.npe_method") \ + && mv /tmp/buggy.java $BUGGY_PATH \ + && echo "[{\"filepath\": \"$BUGGY_PATH\", \"line\": $BUGGY_LINE, \"method_name\": \"$BUGGY_MTHD\"}]" | jq . > traces.json + +RUN git init . && git add -A + +RUN $(cat metadata.json | jq -r ".buildCommand") + +RUN $(cat metadata.json | jq -r ".testCommand"); if [ $? -eq 0 ]; then exit 1; fi diff --git a/Java/commons-lang-ObjectUtils_121/buggy.java b/Java/commons-lang-ObjectUtils_121/buggy.java new file mode 100644 index 000000000..1f665cff6 --- /dev/null +++ b/Java/commons-lang-ObjectUtils_121/buggy.java @@ -0,0 +1,1041 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.lang3; + +import java.io.IOException; +import java.io.Serializable; +import java.lang.reflect.Array; +import java.lang.reflect.InvocationTargetException; +import java.lang.reflect.Method; +import java.util.Collections; +import java.util.Comparator; +import java.util.HashMap; +import java.util.Map; +import java.util.TreeSet; + +import org.apache.commons.lang3.exception.CloneFailedException; +import org.apache.commons.lang3.mutable.MutableInt; +import org.apache.commons.lang3.text.StrBuilder; + +/** + *
Operations on {@code Object}.
+ * + *This class tries to handle {@code null} input gracefully. + * An exception will generally not be thrown for a {@code null} input. + * Each method documents its behaviour in more detail.
+ * + *#ThreadSafe#
+ * @since 1.0 + */ +//@Immutable +public class ObjectUtils { + + /** + *Singleton used as a {@code null} placeholder where + * {@code null} has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there + * is no matching key. The {@code Null} placeholder can be used to + * distinguish between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ * + *This instance is Serializable.
+ */ + public static final Null NULL = new Null(); + + /** + *{@code ObjectUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code ObjectUtils.defaultIfNull("a","b");}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public ObjectUtils() { + super(); + } + + // Defaulting + //----------------------------------------------------------------------- + /** + *Returns a default value if the object passed is {@code null}.
+ * + *+ * ObjectUtils.defaultIfNull(null, null) = null + * ObjectUtils.defaultIfNull(null, "") = "" + * ObjectUtils.defaultIfNull(null, "zz") = "zz" + * ObjectUtils.defaultIfNull("abc", *) = "abc" + * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE + *+ * + * @param
Returns the first value in the array which is not {@code null}. + * If all the values are {@code null} or the array is {@code null} + * or empty then {@code null} is returned.
+ * + *+ * ObjectUtils.firstNonNull(null, null) = null + * ObjectUtils.firstNonNull(null, "") = "" + * ObjectUtils.firstNonNull(null, null, "") = "" + * ObjectUtils.firstNonNull(null, "zz") = "zz" + * ObjectUtils.firstNonNull("abc", *) = "abc" + * ObjectUtils.firstNonNull(null, "xyz", *) = "xyz" + * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE + * ObjectUtils.firstNonNull() = null + *+ * + * @param
Returns the first value in the array which is not {@code null}. + * If all the values are {@code null} or the array is {@code null} + * or empty then {@code null} is returned.
+ * + *+ * ObjectUtils.firstNonNull(null, null) = null + * ObjectUtils.firstNonNull(null, "") = "" + * ObjectUtils.firstNonNull(null, null, "") = "" + * ObjectUtils.firstNonNull(null, "zz") = "zz" + * ObjectUtils.firstNonNull("abc", *) = "abc" + * ObjectUtils.firstNonNull(null, "xyz", *) = "xyz" + * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE + * ObjectUtils.firstNonNull() = null + *+ * + * @param
+ * If all the values are {@code null} or the array is {@code null} + * or empty then {@code false} is returned. Otherwise {@code true} is returned. + *
+ * + *+ * ObjectUtils.anyNotNull(*) = true + * ObjectUtils.anyNotNull(*, null) = true + * ObjectUtils.anyNotNull(null, *) = true + * ObjectUtils.anyNotNull(null, null, *, *) = true + * ObjectUtils.anyNotNull(null) = false + * ObjectUtils.anyNotNull(null, null) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code true} if there is at least one non-null value in the array, + * {@code false} if all values in the array are {@code null}s. + * If the array is {@code null} or empty {@code false} is also returned. + * @since 3.5 + */ + public static boolean anyNotNull(final Object... values) { + return firstNonNull(values) != null; + } + + /** + * Checks if all values in the array are not {@code nulls}. + * + *
+ * If any value is {@code null} or the array is {@code null} then + * {@code false} is returned. If all elements in array are not + * {@code null} or the array is empty (contains no elements) {@code true} + * is returned. + *
+ * + *+ * ObjectUtils.allNotNull(*) = true + * ObjectUtils.allNotNull(*, *) = true + * ObjectUtils.allNotNull(null) = false + * ObjectUtils.allNotNull(null, null) = false + * ObjectUtils.allNotNull(null, *) = false + * ObjectUtils.allNotNull(*, null) = false + * ObjectUtils.allNotNull(*, *, null, *) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code false} if there is at least one {@code null} value in the array or the array is {@code null}, + * {@code true} if all values in the array are not {@code null}s or array contains no elements. + * @since 3.5 + */ + public static boolean allNotNull(final Object... values) { + if (values == null) { + return false; + } + + for (final Object val : values) { + if (val == null) { + return false; + } + } + + return true; + } + + // Null-safe equals/hashCode + //----------------------------------------------------------------------- + /** + *
Compares two objects for equality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.equals(null, null) = true + * ObjectUtils.equals(null, "") = false + * ObjectUtils.equals("", null) = false + * ObjectUtils.equals("", "") = true + * ObjectUtils.equals(Boolean.TRUE, null) = false + * ObjectUtils.equals(Boolean.TRUE, "true") = false + * ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE) = true + * ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code true} if the values of both objects are the same + * @deprecated this method has been replaced by {@code java.util.Objects.equals(Object, Object)} in Java 7 and will + * be removed from future releases. + */ + @Deprecated + public static boolean equals(final Object object1, final Object object2) { + if (object1 == object2) { + return true; + } + if (object1 == null || object2 == null) { + return false; + } + return object1.equals(object2); + } + + /** + *
Compares two objects for inequality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.notEqual(null, null) = false + * ObjectUtils.notEqual(null, "") = true + * ObjectUtils.notEqual("", null) = true + * ObjectUtils.notEqual("", "") = false + * ObjectUtils.notEqual(Boolean.TRUE, null) = true + * ObjectUtils.notEqual(Boolean.TRUE, "true") = true + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE) = false + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code false} if the values of both objects are the same + */ + public static boolean notEqual(final Object object1, final Object object2) { + return ObjectUtils.equals(object1, object2) == false; + } + + /** + *
Gets the hash code of an object returning zero when the + * object is {@code null}.
+ * + *+ * ObjectUtils.hashCode(null) = 0 + * ObjectUtils.hashCode(obj) = obj.hashCode() + *+ * + * @param obj the object to obtain the hash code of, may be {@code null} + * @return the hash code of the object, or zero if null + * @since 2.1 + * @deprecated this method has been replaced by {@code java.util.Objects.hashCode(Object)} in Java 7 and will be + * removed in future releases + */ + @Deprecated + public static int hashCode(final Object obj) { + // hashCode(Object) retained for performance, as hash code is often critical + return obj == null ? 0 : obj.hashCode(); + } + + /** + *
Gets the hash code for multiple objects.
+ * + *This allows a hash code to be rapidly calculated for a number of objects. + * The hash code for a single object is the not same as {@link #hashCode(Object)}. + * The hash code for multiple objects is the same as that calculated by an + * {@code ArrayList} containing the specified objects.
+ * + *+ * ObjectUtils.hashCodeMulti() = 1 + * ObjectUtils.hashCodeMulti((Object[]) null) = 1 + * ObjectUtils.hashCodeMulti(a) = 31 + a.hashCode() + * ObjectUtils.hashCodeMulti(a,b) = (31 + a.hashCode()) * 31 + b.hashCode() + * ObjectUtils.hashCodeMulti(a,b,c) = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode() + *+ * + * @param objects the objects to obtain the hash code of, may be {@code null} + * @return the hash code of the objects, or zero if null + * @since 3.0 + * @deprecated this method has been replaced by {@code java.util.Objects.hash(Object...)} in Java 7 and will be + * removed in future releases. + */ + @Deprecated + public static int hashCodeMulti(final Object... objects) { + int hash = 1; + if (objects != null) { + for (final Object object : objects) { + final int tmpHash = ObjectUtils.hashCode(object); + hash = hash * 31 + tmpHash; + } + } + return hash; + } + + // Identity ToString + //----------------------------------------------------------------------- + /** + *
Gets the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will return {@code null}.
+ * + *+ * ObjectUtils.identityToString(null) = null + * ObjectUtils.identityToString("") = "java.lang.String@1e23" + * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa" + *+ * + * @param object the object to create a toString for, may be + * {@code null} + * @return the default toString text, or {@code null} if + * {@code null} passed in + */ + public static String identityToString(final Object object) { + if (object == null) { + return null; + } + final StringBuilder builder = new StringBuilder(); + identityToString(builder, object); + return builder.toString(); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(appendable, "") = appendable.append("java.lang.String@1e23" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa") + *+ * + * @param appendable the appendable to append to + * @param object the object to create a toString for + * @throws IOException if an I/O error occurs + * @since 3.2 + */ + public static void identityToString(final Appendable appendable, final Object object) throws IOException { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + appendable.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StrBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(buf, "") = buf.append("java.lang.String@1e23" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa") + *+ * + * @param buffer the buffer to append to + * @param object the object to create a toString for + * @since 2.4 + */ + public static void identityToString(final StringBuffer buffer, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + buffer.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StringBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + // ToString + //----------------------------------------------------------------------- + /** + *
Gets the {@code toString} of an {@code Object} returning + * an empty string ("") if {@code null} input.
+ * + *+ * ObjectUtils.toString(null) = "" + * ObjectUtils.toString("") = "" + * ObjectUtils.toString("bat") = "bat" + * ObjectUtils.toString(Boolean.TRUE) = "true" + *+ * + * @see StringUtils#defaultString(String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @return the passed in Object's toString, or {@code ""} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object)} in Java 7 and will be + * removed in future releases. Note however that said method will return "null" for null references, while this + * method returns and empty String. To preserve behavior use {@code java.util.Objects.toString(myObject, "")} + */ + @Deprecated + public static String toString(final Object obj) { + return obj == null ? StringUtils.EMPTY : obj.toString(); + } + + /** + *
Gets the {@code toString} of an {@code Object} returning + * a specified text if {@code null} input.
+ * + *+ * ObjectUtils.toString(null, null) = null + * ObjectUtils.toString(null, "null") = "null" + * ObjectUtils.toString("", "null") = "" + * ObjectUtils.toString("bat", "null") = "bat" + * ObjectUtils.toString(Boolean.TRUE, "null") = "true" + *+ * + * @see StringUtils#defaultString(String,String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @param nullStr the String to return if {@code null} input, may be null + * @return the passed in Object's toString, or {@code nullStr} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object, String)} in Java 7 and + * will be removed in future releases. + */ + @Deprecated + public static String toString(final Object obj, final String nullStr) { + return obj == null ? nullStr : obj.toString(); + } + + // Comparable + //----------------------------------------------------------------------- + /** + *
Null safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables. + * {@code null} is assumed to be less than a non-{@code null} value.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramClone an object.
+ * + * @paramClone an object if possible.
+ * + *This method is similar to {@link #clone(Object)}, but will return the provided + * instance as the return value instead of {@code null} if the instance + * is not cloneable. This is more convenient if the caller uses different + * implementations (e.g. of a service) and some of the implementations do not allow concurrent + * processing or have state. In such cases the implementation can simply provide a proper + * clone implementation and the caller's code does not have to change.
+ * + * @paramClass used as a null placeholder where {@code null} + * has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there is + * no matching key. The {@code Null} placeholder can be used to distinguish + * between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ */ + public static class Null implements Serializable { + /** + * Required for serialization support. Declare serialization compatibility with Commons Lang 1.0 + * + * @see java.io.Serializable + */ + private static final long serialVersionUID = 7092611880189329093L; + + /** + * Restricted constructor - singleton. + */ + Null() { + super(); + } + + /** + *Ensure singleton.
+ * + * @return the singleton value + */ + private Object readResolve() { + return ObjectUtils.NULL; + } + } + + + // Constants (LANG-816): + /* + These methods ensure constants are not inlined by javac. + For example, typically a developer might declare a constant like so: + + public final static int MAGIC_NUMBER = 5; + + Should a different jar file refer to this, and the MAGIC_NUMBER + is changed a later date (e.g., MAGIC_NUMBER = 6), the different jar + file will need to recompile itself. This is because javac + typically inlines the primitive or String constant directly into + the bytecode, and removes the reference to the MAGIC_NUMBER field. + + To help the other jar (so that it does not need to recompile + when constants are changed) the original developer can declare + their constant using one of the CONST() utility methods, instead: + + public final static int MAGIC_NUMBER = CONST(5); + */ + + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *+ * public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the boolean value to return + * @return the boolean v, unchanged + * @since 3.2 + */ + public static boolean CONST(final boolean v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the byte value to return + * @return the byte v, unchanged + * @since 3.2 + */ + public static byte CONST(final byte v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the byte literal (as an int) value to return + * @throws IllegalArgumentException if the value passed to v + * is larger than a byte, that is, smaller than -128 or + * larger than 127. + * @return the byte v, unchanged + * @since 3.2 + */ + public static byte CONST_BYTE(final int v) throws IllegalArgumentException { + if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) { + throw new IllegalArgumentException("Supplied value must be a valid byte literal between -128 and 127: [" + v + "]"); + } + return (byte) v; + } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static char MAGIC_CHAR = ObjectUtils.CONST('a'); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the char value to return + * @return the char v, unchanged + * @since 3.2 + */ + public static char CONST(final char v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the short value to return + * @return the short v, unchanged + * @since 3.2 + */ + public static short CONST(final short v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the short literal (as an int) value to return + * @throws IllegalArgumentException if the value passed to v + * is larger than a short, that is, smaller than -32768 or + * larger than 32767. + * @return the byte v, unchanged + * @since 3.2 + */ + public static short CONST_SHORT(final int v) throws IllegalArgumentException { + if (v < Short.MIN_VALUE || v > Short.MAX_VALUE) { + throw new IllegalArgumentException("Supplied value must be a valid byte literal between -32768 and 32767: [" + v + "]"); + } + return (short) v; + } + + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static int MAGIC_INT = ObjectUtils.CONST(123); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the int value to return + * @return the int v, unchanged + * @since 3.2 + */ + public static int CONST(final int v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static long MAGIC_LONG = ObjectUtils.CONST(123L); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the long value to return + * @return the long v, unchanged + * @since 3.2 + */ + public static long CONST(final long v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the float value to return + * @return the float v, unchanged + * @since 3.2 + */ + public static float CONST(final float v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the double value to return + * @return the double v, unchanged + * @since 3.2 + */ + public static double CONST(final double v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static String MAGIC_STRING = ObjectUtils.CONST("abc"); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param
Operations on {@code Object}.
+ * + *This class tries to handle {@code null} input gracefully. + * An exception will generally not be thrown for a {@code null} input. + * Each method documents its behaviour in more detail.
+ * + *#ThreadSafe#
+ * @since 1.0 + */ +//@Immutable +public class ObjectUtils { + + /** + *Singleton used as a {@code null} placeholder where + * {@code null} has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there + * is no matching key. The {@code Null} placeholder can be used to + * distinguish between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ * + *This instance is Serializable.
+ */ + public static final Null NULL = new Null(); + + /** + *{@code ObjectUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code ObjectUtils.defaultIfNull("a","b");}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public ObjectUtils() { + super(); + } + + // Defaulting + //----------------------------------------------------------------------- + /** + *Returns a default value if the object passed is {@code null}.
+ * + *+ * ObjectUtils.defaultIfNull(null, null) = null + * ObjectUtils.defaultIfNull(null, "") = "" + * ObjectUtils.defaultIfNull(null, "zz") = "zz" + * ObjectUtils.defaultIfNull("abc", *) = "abc" + * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE + *+ * + * @param
Returns the first value in the array which is not {@code null}. + * If all the values are {@code null} or the array is {@code null} + * or empty then {@code null} is returned.
+ * + *+ * ObjectUtils.firstNonNull(null, null) = null + * ObjectUtils.firstNonNull(null, "") = "" + * ObjectUtils.firstNonNull(null, null, "") = "" + * ObjectUtils.firstNonNull(null, "zz") = "zz" + * ObjectUtils.firstNonNull("abc", *) = "abc" + * ObjectUtils.firstNonNull(null, "xyz", *) = "xyz" + * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE + * ObjectUtils.firstNonNull() = null + *+ * + * @param
Returns the first value in the array which is not {@code null}. + * If all the values are {@code null} or the array is {@code null} + * or empty then {@code null} is returned.
+ * + *+ * ObjectUtils.firstNonNull(null, null) = null + * ObjectUtils.firstNonNull(null, "") = "" + * ObjectUtils.firstNonNull(null, null, "") = "" + * ObjectUtils.firstNonNull(null, "zz") = "zz" + * ObjectUtils.firstNonNull("abc", *) = "abc" + * ObjectUtils.firstNonNull(null, "xyz", *) = "xyz" + * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE + * ObjectUtils.firstNonNull() = null + *+ * + * @param
+ * If all the values are {@code null} or the array is {@code null} + * or empty then {@code false} is returned. Otherwise {@code true} is returned. + *
+ * + *+ * ObjectUtils.anyNotNull(*) = true + * ObjectUtils.anyNotNull(*, null) = true + * ObjectUtils.anyNotNull(null, *) = true + * ObjectUtils.anyNotNull(null, null, *, *) = true + * ObjectUtils.anyNotNull(null) = false + * ObjectUtils.anyNotNull(null, null) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code true} if there is at least one non-null value in the array, + * {@code false} if all values in the array are {@code null}s. + * If the array is {@code null} or empty {@code false} is also returned. + * @since 3.5 + */ + public static boolean anyNotNull(final Object... values) { + return firstNonNull(values) != null; + } + + /** + * Checks if all values in the array are not {@code nulls}. + * + *
+ * If any value is {@code null} or the array is {@code null} then + * {@code false} is returned. If all elements in array are not + * {@code null} or the array is empty (contains no elements) {@code true} + * is returned. + *
+ * + *+ * ObjectUtils.allNotNull(*) = true + * ObjectUtils.allNotNull(*, *) = true + * ObjectUtils.allNotNull(null) = false + * ObjectUtils.allNotNull(null, null) = false + * ObjectUtils.allNotNull(null, *) = false + * ObjectUtils.allNotNull(*, null) = false + * ObjectUtils.allNotNull(*, *, null, *) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code false} if there is at least one {@code null} value in the array or the array is {@code null}, + * {@code true} if all values in the array are not {@code null}s or array contains no elements. + * @since 3.5 + */ + public static boolean allNotNull(final Object... values) { + if (values == null) { + return false; + } + + for (final Object val : values) { + if (val == null) { + return false; + } + } + + return true; + } + + // Null-safe equals/hashCode + //----------------------------------------------------------------------- + /** + *
Compares two objects for equality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.equals(null, null) = true + * ObjectUtils.equals(null, "") = false + * ObjectUtils.equals("", null) = false + * ObjectUtils.equals("", "") = true + * ObjectUtils.equals(Boolean.TRUE, null) = false + * ObjectUtils.equals(Boolean.TRUE, "true") = false + * ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE) = true + * ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code true} if the values of both objects are the same + * @deprecated this method has been replaced by {@code java.util.Objects.equals(Object, Object)} in Java 7 and will + * be removed from future releases. + */ + @Deprecated + public static boolean equals(final Object object1, final Object object2) { + if (object1 == object2) { + return true; + } + if (object1 == null || object2 == null) { + return false; + } + return object1.equals(object2); + } + + /** + *
Compares two objects for inequality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.notEqual(null, null) = false + * ObjectUtils.notEqual(null, "") = true + * ObjectUtils.notEqual("", null) = true + * ObjectUtils.notEqual("", "") = false + * ObjectUtils.notEqual(Boolean.TRUE, null) = true + * ObjectUtils.notEqual(Boolean.TRUE, "true") = true + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE) = false + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code false} if the values of both objects are the same + */ + public static boolean notEqual(final Object object1, final Object object2) { + return ObjectUtils.equals(object1, object2) == false; + } + + /** + *
Gets the hash code of an object returning zero when the + * object is {@code null}.
+ * + *+ * ObjectUtils.hashCode(null) = 0 + * ObjectUtils.hashCode(obj) = obj.hashCode() + *+ * + * @param obj the object to obtain the hash code of, may be {@code null} + * @return the hash code of the object, or zero if null + * @since 2.1 + * @deprecated this method has been replaced by {@code java.util.Objects.hashCode(Object)} in Java 7 and will be + * removed in future releases + */ + @Deprecated + public static int hashCode(final Object obj) { + // hashCode(Object) retained for performance, as hash code is often critical + return obj == null ? 0 : obj.hashCode(); + } + + /** + *
Gets the hash code for multiple objects.
+ * + *This allows a hash code to be rapidly calculated for a number of objects. + * The hash code for a single object is the not same as {@link #hashCode(Object)}. + * The hash code for multiple objects is the same as that calculated by an + * {@code ArrayList} containing the specified objects.
+ * + *+ * ObjectUtils.hashCodeMulti() = 1 + * ObjectUtils.hashCodeMulti((Object[]) null) = 1 + * ObjectUtils.hashCodeMulti(a) = 31 + a.hashCode() + * ObjectUtils.hashCodeMulti(a,b) = (31 + a.hashCode()) * 31 + b.hashCode() + * ObjectUtils.hashCodeMulti(a,b,c) = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode() + *+ * + * @param objects the objects to obtain the hash code of, may be {@code null} + * @return the hash code of the objects, or zero if null + * @since 3.0 + * @deprecated this method has been replaced by {@code java.util.Objects.hash(Object...)} in Java 7 and will be + * removed in future releases. + */ + @Deprecated + public static int hashCodeMulti(final Object... objects) { + int hash = 1; + if (objects != null) { + for (final Object object : objects) { + final int tmpHash = ObjectUtils.hashCode(object); + hash = hash * 31 + tmpHash; + } + } + return hash; + } + + // Identity ToString + //----------------------------------------------------------------------- + /** + *
Gets the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will return {@code null}.
+ * + *+ * ObjectUtils.identityToString(null) = null + * ObjectUtils.identityToString("") = "java.lang.String@1e23" + * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa" + *+ * + * @param object the object to create a toString for, may be + * {@code null} + * @return the default toString text, or {@code null} if + * {@code null} passed in + */ + public static String identityToString(final Object object) { + if (object == null) { + return null; + } + final StringBuilder builder = new StringBuilder(); + identityToString(builder, object); + return builder.toString(); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(appendable, "") = appendable.append("java.lang.String@1e23" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa") + *+ * + * @param appendable the appendable to append to + * @param object the object to create a toString for + * @throws IOException if an I/O error occurs + * @since 3.2 + */ + public static void identityToString(final Appendable appendable, final Object object) throws IOException { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + appendable.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StrBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(buf, "") = buf.append("java.lang.String@1e23" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa") + *+ * + * @param buffer the buffer to append to + * @param object the object to create a toString for + * @since 2.4 + */ + public static void identityToString(final StringBuffer buffer, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + buffer.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StringBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + // ToString + //----------------------------------------------------------------------- + /** + *
Gets the {@code toString} of an {@code Object} returning + * an empty string ("") if {@code null} input.
+ * + *+ * ObjectUtils.toString(null) = "" + * ObjectUtils.toString("") = "" + * ObjectUtils.toString("bat") = "bat" + * ObjectUtils.toString(Boolean.TRUE) = "true" + *+ * + * @see StringUtils#defaultString(String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @return the passed in Object's toString, or {@code ""} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object)} in Java 7 and will be + * removed in future releases. Note however that said method will return "null" for null references, while this + * method returns and empty String. To preserve behavior use {@code java.util.Objects.toString(myObject, "")} + */ + @Deprecated + public static String toString(final Object obj) { + return obj == null ? StringUtils.EMPTY : obj.toString(); + } + + /** + *
Gets the {@code toString} of an {@code Object} returning + * a specified text if {@code null} input.
+ * + *+ * ObjectUtils.toString(null, null) = null + * ObjectUtils.toString(null, "null") = "null" + * ObjectUtils.toString("", "null") = "" + * ObjectUtils.toString("bat", "null") = "bat" + * ObjectUtils.toString(Boolean.TRUE, "null") = "true" + *+ * + * @see StringUtils#defaultString(String,String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @param nullStr the String to return if {@code null} input, may be null + * @return the passed in Object's toString, or {@code nullStr} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object, String)} in Java 7 and + * will be removed in future releases. + */ + @Deprecated + public static String toString(final Object obj, final String nullStr) { + return obj == null ? nullStr : obj.toString(); + } + + // Comparable + //----------------------------------------------------------------------- + /** + *
Null safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables. + * {@code null} is assumed to be less than a non-{@code null} value.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramClone an object.
+ * + * @paramClone an object if possible.
+ * + *This method is similar to {@link #clone(Object)}, but will return the provided + * instance as the return value instead of {@code null} if the instance + * is not cloneable. This is more convenient if the caller uses different + * implementations (e.g. of a service) and some of the implementations do not allow concurrent + * processing or have state. In such cases the implementation can simply provide a proper + * clone implementation and the caller's code does not have to change.
+ * + * @paramClass used as a null placeholder where {@code null} + * has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there is + * no matching key. The {@code Null} placeholder can be used to distinguish + * between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ */ + public static class Null implements Serializable { + /** + * Required for serialization support. Declare serialization compatibility with Commons Lang 1.0 + * + * @see java.io.Serializable + */ + private static final long serialVersionUID = 7092611880189329093L; + + /** + * Restricted constructor - singleton. + */ + Null() { + super(); + } + + /** + *Ensure singleton.
+ * + * @return the singleton value + */ + private Object readResolve() { + return ObjectUtils.NULL; + } + } + + + // Constants (LANG-816): + /* + These methods ensure constants are not inlined by javac. + For example, typically a developer might declare a constant like so: + + public final static int MAGIC_NUMBER = 5; + + Should a different jar file refer to this, and the MAGIC_NUMBER + is changed a later date (e.g., MAGIC_NUMBER = 6), the different jar + file will need to recompile itself. This is because javac + typically inlines the primitive or String constant directly into + the bytecode, and removes the reference to the MAGIC_NUMBER field. + + To help the other jar (so that it does not need to recompile + when constants are changed) the original developer can declare + their constant using one of the CONST() utility methods, instead: + + public final static int MAGIC_NUMBER = CONST(5); + */ + + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *+ * public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the boolean value to return + * @return the boolean v, unchanged + * @since 3.2 + */ + public static boolean CONST(final boolean v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the byte value to return + * @return the byte v, unchanged + * @since 3.2 + */ + public static byte CONST(final byte v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the byte literal (as an int) value to return + * @throws IllegalArgumentException if the value passed to v + * is larger than a byte, that is, smaller than -128 or + * larger than 127. + * @return the byte v, unchanged + * @since 3.2 + */ + public static byte CONST_BYTE(final int v) throws IllegalArgumentException { + if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) { + throw new IllegalArgumentException("Supplied value must be a valid byte literal between -128 and 127: [" + v + "]"); + } + return (byte) v; + } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static char MAGIC_CHAR = ObjectUtils.CONST('a'); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the char value to return + * @return the char v, unchanged + * @since 3.2 + */ + public static char CONST(final char v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the short value to return + * @return the short v, unchanged + * @since 3.2 + */ + public static short CONST(final short v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the short literal (as an int) value to return + * @throws IllegalArgumentException if the value passed to v + * is larger than a short, that is, smaller than -32768 or + * larger than 32767. + * @return the byte v, unchanged + * @since 3.2 + */ + public static short CONST_SHORT(final int v) throws IllegalArgumentException { + if (v < Short.MIN_VALUE || v > Short.MAX_VALUE) { + throw new IllegalArgumentException("Supplied value must be a valid byte literal between -32768 and 32767: [" + v + "]"); + } + return (short) v; + } + + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static int MAGIC_INT = ObjectUtils.CONST(123); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the int value to return + * @return the int v, unchanged + * @since 3.2 + */ + public static int CONST(final int v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static long MAGIC_LONG = ObjectUtils.CONST(123L); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the long value to return + * @return the long v, unchanged + * @since 3.2 + */ + public static long CONST(final long v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the float value to return + * @return the float v, unchanged + * @since 3.2 + */ + public static float CONST(final float v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the double value to return + * @return the double v, unchanged + * @since 3.2 + */ + public static double CONST(final double v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static String MAGIC_STRING = ObjectUtils.CONST("abc"); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param
Operations on {@code Object}.
+ * + *This class tries to handle {@code null} input gracefully. + * An exception will generally not be thrown for a {@code null} input. + * Each method documents its behaviour in more detail.
+ * + *#ThreadSafe#
+ * @since 1.0 + */ +//@Immutable +public class ObjectUtils { + + /** + *Singleton used as a {@code null} placeholder where + * {@code null} has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there + * is no matching key. The {@code Null} placeholder can be used to + * distinguish between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ * + *This instance is Serializable.
+ */ + public static final Null NULL = new Null(); + + /** + *{@code ObjectUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code ObjectUtils.defaultIfNull("a","b");}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public ObjectUtils() { + super(); + } + + // Defaulting + //----------------------------------------------------------------------- + /** + *Returns a default value if the object passed is {@code null}.
+ * + *+ * ObjectUtils.defaultIfNull(null, null) = null + * ObjectUtils.defaultIfNull(null, "") = "" + * ObjectUtils.defaultIfNull(null, "zz") = "zz" + * ObjectUtils.defaultIfNull("abc", *) = "abc" + * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE + *+ * + * @param
Returns the first value in the array which is not {@code null}. + * If all the values are {@code null} or the array is {@code null} + * or empty then {@code null} is returned.
+ * + *+ * ObjectUtils.firstNonNull(null, null) = null + * ObjectUtils.firstNonNull(null, "") = "" + * ObjectUtils.firstNonNull(null, null, "") = "" + * ObjectUtils.firstNonNull(null, "zz") = "zz" + * ObjectUtils.firstNonNull("abc", *) = "abc" + * ObjectUtils.firstNonNull(null, "xyz", *) = "xyz" + * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE + * ObjectUtils.firstNonNull() = null + *+ * + * @param
+ * If all the values are {@code null} or the array is {@code null} + * or empty then {@code false} is returned. Otherwise {@code true} is returned. + *
+ * + *+ * ObjectUtils.anyNotNull(*) = true + * ObjectUtils.anyNotNull(*, null) = true + * ObjectUtils.anyNotNull(null, *) = true + * ObjectUtils.anyNotNull(null, null, *, *) = true + * ObjectUtils.anyNotNull(null) = false + * ObjectUtils.anyNotNull(null, null) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code true} if there is at least one non-null value in the array, + * {@code false} if all values in the array are {@code null}s. + * If the array is {@code null} or empty {@code false} is also returned. + * @since 3.5 + */ + public static boolean anyNotNull(final Object... values) { + return firstNonNull(values) != null; + } + + /** + * Checks if all values in the array are not {@code nulls}. + * + *
+ * If any value is {@code null} or the array is {@code null} then + * {@code false} is returned. If all elements in array are not + * {@code null} or the array is empty (contains no elements) {@code true} + * is returned. + *
+ * + *+ * ObjectUtils.allNotNull(*) = true + * ObjectUtils.allNotNull(*, *) = true + * ObjectUtils.allNotNull(null) = false + * ObjectUtils.allNotNull(null, null) = false + * ObjectUtils.allNotNull(null, *) = false + * ObjectUtils.allNotNull(*, null) = false + * ObjectUtils.allNotNull(*, *, null, *) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code false} if there is at least one {@code null} value in the array or the array is {@code null}, + * {@code true} if all values in the array are not {@code null}s or array contains no elements. + * @since 3.5 + */ +/** + * Checks if all values in the array are not {@code nulls}. + * + *
+ * If any value is {@code null} or the array is {@code null} then + * {@code false} is returned. If all elements in array are not + * {@code null} or the array is empty (contains no elements) {@code true} + * is returned. + *
+ * + *+ * ObjectUtils.allNotNull(*) = true + * ObjectUtils.allNotNull(*, *) = true + * ObjectUtils.allNotNull(null) = false + * ObjectUtils.allNotNull(null, null) = false + * ObjectUtils.allNotNull(null, *) = false + * ObjectUtils.allNotNull(*, null) = false + * ObjectUtils.allNotNull(*, *, null, *) = false + *+ * + * @param values + * the values to test, may be {@code null} or empty + * @return {@code false} if there is at least one {@code null} value in the array or the array is {@code null}, +{@code true} if all values in the array are not {@code null}s or array contains no elements. + * @since 3.5 + */ +public static boolean allNotNull(final java.lang.Object... values) { + { + for (final java.lang.Object val : /* NPEX_NULL_EXP */ + values) { + if (val == null) { + return false; + } + } + return true; + } +} + + // Null-safe equals/hashCode + //----------------------------------------------------------------------- + /** + *
Compares two objects for equality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.equals(null, null) = true + * ObjectUtils.equals(null, "") = false + * ObjectUtils.equals("", null) = false + * ObjectUtils.equals("", "") = true + * ObjectUtils.equals(Boolean.TRUE, null) = false + * ObjectUtils.equals(Boolean.TRUE, "true") = false + * ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE) = true + * ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code true} if the values of both objects are the same + * @deprecated this method has been replaced by {@code java.util.Objects.equals(Object, Object)} in Java 7 and will + * be removed from future releases. + */ + @Deprecated + public static boolean equals(final Object object1, final Object object2) { + if (object1 == object2) { + return true; + } + if (object1 == null || object2 == null) { + return false; + } + return object1.equals(object2); + } + + /** + *
Compares two objects for inequality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.notEqual(null, null) = false + * ObjectUtils.notEqual(null, "") = true + * ObjectUtils.notEqual("", null) = true + * ObjectUtils.notEqual("", "") = false + * ObjectUtils.notEqual(Boolean.TRUE, null) = true + * ObjectUtils.notEqual(Boolean.TRUE, "true") = true + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE) = false + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code false} if the values of both objects are the same + */ + public static boolean notEqual(final Object object1, final Object object2) { + return ObjectUtils.equals(object1, object2) == false; + } + + /** + *
Gets the hash code of an object returning zero when the + * object is {@code null}.
+ * + *+ * ObjectUtils.hashCode(null) = 0 + * ObjectUtils.hashCode(obj) = obj.hashCode() + *+ * + * @param obj the object to obtain the hash code of, may be {@code null} + * @return the hash code of the object, or zero if null + * @since 2.1 + * @deprecated this method has been replaced by {@code java.util.Objects.hashCode(Object)} in Java 7 and will be + * removed in future releases + */ + @Deprecated + public static int hashCode(final Object obj) { + // hashCode(Object) retained for performance, as hash code is often critical + return obj == null ? 0 : obj.hashCode(); + } + + /** + *
Gets the hash code for multiple objects.
+ * + *This allows a hash code to be rapidly calculated for a number of objects. + * The hash code for a single object is the not same as {@link #hashCode(Object)}. + * The hash code for multiple objects is the same as that calculated by an + * {@code ArrayList} containing the specified objects.
+ * + *+ * ObjectUtils.hashCodeMulti() = 1 + * ObjectUtils.hashCodeMulti((Object[]) null) = 1 + * ObjectUtils.hashCodeMulti(a) = 31 + a.hashCode() + * ObjectUtils.hashCodeMulti(a,b) = (31 + a.hashCode()) * 31 + b.hashCode() + * ObjectUtils.hashCodeMulti(a,b,c) = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode() + *+ * + * @param objects the objects to obtain the hash code of, may be {@code null} + * @return the hash code of the objects, or zero if null + * @since 3.0 + * @deprecated this method has been replaced by {@code java.util.Objects.hash(Object...)} in Java 7 and will be + * removed in future releases. + */ + @Deprecated + public static int hashCodeMulti(final Object... objects) { + int hash = 1; + if (objects != null) { + for (final Object object : objects) { + final int tmpHash = ObjectUtils.hashCode(object); + hash = hash * 31 + tmpHash; + } + } + return hash; + } + + // Identity ToString + //----------------------------------------------------------------------- + /** + *
Gets the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will return {@code null}.
+ * + *+ * ObjectUtils.identityToString(null) = null + * ObjectUtils.identityToString("") = "java.lang.String@1e23" + * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa" + *+ * + * @param object the object to create a toString for, may be + * {@code null} + * @return the default toString text, or {@code null} if + * {@code null} passed in + */ + public static String identityToString(final Object object) { + if (object == null) { + return null; + } + final StringBuilder builder = new StringBuilder(); + identityToString(builder, object); + return builder.toString(); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(appendable, "") = appendable.append("java.lang.String@1e23" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa") + *+ * + * @param appendable the appendable to append to + * @param object the object to create a toString for + * @throws IOException if an I/O error occurs + * @since 3.2 + */ + public static void identityToString(final Appendable appendable, final Object object) throws IOException { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + appendable.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StrBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(buf, "") = buf.append("java.lang.String@1e23" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa") + *+ * + * @param buffer the buffer to append to + * @param object the object to create a toString for + * @since 2.4 + */ + public static void identityToString(final StringBuffer buffer, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + buffer.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StringBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + // ToString + //----------------------------------------------------------------------- + /** + *
Gets the {@code toString} of an {@code Object} returning + * an empty string ("") if {@code null} input.
+ * + *+ * ObjectUtils.toString(null) = "" + * ObjectUtils.toString("") = "" + * ObjectUtils.toString("bat") = "bat" + * ObjectUtils.toString(Boolean.TRUE) = "true" + *+ * + * @see StringUtils#defaultString(String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @return the passed in Object's toString, or {@code ""} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object)} in Java 7 and will be + * removed in future releases. Note however that said method will return "null" for null references, while this + * method returns and empty String. To preserve behavior use {@code java.util.Objects.toString(myObject, "")} + */ + @Deprecated + public static String toString(final Object obj) { + return obj == null ? StringUtils.EMPTY : obj.toString(); + } + + /** + *
Gets the {@code toString} of an {@code Object} returning + * a specified text if {@code null} input.
+ * + *+ * ObjectUtils.toString(null, null) = null + * ObjectUtils.toString(null, "null") = "null" + * ObjectUtils.toString("", "null") = "" + * ObjectUtils.toString("bat", "null") = "bat" + * ObjectUtils.toString(Boolean.TRUE, "null") = "true" + *+ * + * @see StringUtils#defaultString(String,String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @param nullStr the String to return if {@code null} input, may be null + * @return the passed in Object's toString, or {@code nullStr} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object, String)} in Java 7 and + * will be removed in future releases. + */ + @Deprecated + public static String toString(final Object obj, final String nullStr) { + return obj == null ? nullStr : obj.toString(); + } + + // Comparable + //----------------------------------------------------------------------- + /** + *
Null safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables. + * {@code null} is assumed to be less than a non-{@code null} value.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramClone an object.
+ * + * @paramClone an object if possible.
+ * + *This method is similar to {@link #clone(Object)}, but will return the provided + * instance as the return value instead of {@code null} if the instance + * is not cloneable. This is more convenient if the caller uses different + * implementations (e.g. of a service) and some of the implementations do not allow concurrent + * processing or have state. In such cases the implementation can simply provide a proper + * clone implementation and the caller's code does not have to change.
+ * + * @paramClass used as a null placeholder where {@code null} + * has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there is + * no matching key. The {@code Null} placeholder can be used to distinguish + * between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ */ + public static class Null implements Serializable { + /** + * Required for serialization support. Declare serialization compatibility with Commons Lang 1.0 + * + * @see java.io.Serializable + */ + private static final long serialVersionUID = 7092611880189329093L; + + /** + * Restricted constructor - singleton. + */ + Null() { + super(); + } + + /** + *Ensure singleton.
+ * + * @return the singleton value + */ + private Object readResolve() { + return ObjectUtils.NULL; + } + } + + + // Constants (LANG-816): + /* + These methods ensure constants are not inlined by javac. + For example, typically a developer might declare a constant like so: + + public final static int MAGIC_NUMBER = 5; + + Should a different jar file refer to this, and the MAGIC_NUMBER + is changed a later date (e.g., MAGIC_NUMBER = 6), the different jar + file will need to recompile itself. This is because javac + typically inlines the primitive or String constant directly into + the bytecode, and removes the reference to the MAGIC_NUMBER field. + + To help the other jar (so that it does not need to recompile + when constants are changed) the original developer can declare + their constant using one of the CONST() utility methods, instead: + + public final static int MAGIC_NUMBER = CONST(5); + */ + + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *+ * public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the boolean value to return + * @return the boolean v, unchanged + * @since 3.2 + */ + public static boolean CONST(final boolean v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the byte value to return + * @return the byte v, unchanged + * @since 3.2 + */ + public static byte CONST(final byte v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the byte literal (as an int) value to return + * @throws IllegalArgumentException if the value passed to v + * is larger than a byte, that is, smaller than -128 or + * larger than 127. + * @return the byte v, unchanged + * @since 3.2 + */ + public static byte CONST_BYTE(final int v) throws IllegalArgumentException { + if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) { + throw new IllegalArgumentException("Supplied value must be a valid byte literal between -128 and 127: [" + v + "]"); + } + return (byte) v; + } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static char MAGIC_CHAR = ObjectUtils.CONST('a'); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the char value to return + * @return the char v, unchanged + * @since 3.2 + */ + public static char CONST(final char v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the short value to return + * @return the short v, unchanged + * @since 3.2 + */ + public static short CONST(final short v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the short literal (as an int) value to return + * @throws IllegalArgumentException if the value passed to v + * is larger than a short, that is, smaller than -32768 or + * larger than 32767. + * @return the byte v, unchanged + * @since 3.2 + */ + public static short CONST_SHORT(final int v) throws IllegalArgumentException { + if (v < Short.MIN_VALUE || v > Short.MAX_VALUE) { + throw new IllegalArgumentException("Supplied value must be a valid byte literal between -32768 and 32767: [" + v + "]"); + } + return (short) v; + } + + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static int MAGIC_INT = ObjectUtils.CONST(123); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the int value to return + * @return the int v, unchanged + * @since 3.2 + */ + public static int CONST(final int v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static long MAGIC_LONG = ObjectUtils.CONST(123L); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the long value to return + * @return the long v, unchanged + * @since 3.2 + */ + public static long CONST(final long v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the float value to return + * @return the float v, unchanged + * @since 3.2 + */ + public static float CONST(final float v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the double value to return + * @return the double v, unchanged + * @since 3.2 + */ + public static double CONST(final double v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static String MAGIC_STRING = ObjectUtils.CONST("abc"); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param
Operations on {@code Object}.
+ * + *This class tries to handle {@code null} input gracefully. + * An exception will generally not be thrown for a {@code null} input. + * Each method documents its behaviour in more detail.
+ * + *#ThreadSafe#
+ * @since 1.0 + */ +//@Immutable +public class ObjectUtils { + + /** + *Singleton used as a {@code null} placeholder where + * {@code null} has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there + * is no matching key. The {@code Null} placeholder can be used to + * distinguish between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ * + *This instance is Serializable.
+ */ + public static final Null NULL = new Null(); + + /** + *{@code ObjectUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code ObjectUtils.defaultIfNull("a","b");}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public ObjectUtils() { + super(); + } + + // Defaulting + //----------------------------------------------------------------------- + /** + *Returns a default value if the object passed is {@code null}.
+ * + *+ * ObjectUtils.defaultIfNull(null, null) = null + * ObjectUtils.defaultIfNull(null, "") = "" + * ObjectUtils.defaultIfNull(null, "zz") = "zz" + * ObjectUtils.defaultIfNull("abc", *) = "abc" + * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE + *+ * + * @param
Returns the first value in the array which is not {@code null}. + * If all the values are {@code null} or the array is {@code null} + * or empty then {@code null} is returned.
+ * + *+ * ObjectUtils.firstNonNull(null, null) = null + * ObjectUtils.firstNonNull(null, "") = "" + * ObjectUtils.firstNonNull(null, null, "") = "" + * ObjectUtils.firstNonNull(null, "zz") = "zz" + * ObjectUtils.firstNonNull("abc", *) = "abc" + * ObjectUtils.firstNonNull(null, "xyz", *) = "xyz" + * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE + * ObjectUtils.firstNonNull() = null + *+ * + * @param
+ * If all the values are {@code null} or the array is {@code null} + * or empty then {@code false} is returned. Otherwise {@code true} is returned. + *
+ * + *+ * ObjectUtils.anyNotNull(*) = true + * ObjectUtils.anyNotNull(*, null) = true + * ObjectUtils.anyNotNull(null, *) = true + * ObjectUtils.anyNotNull(null, null, *, *) = true + * ObjectUtils.anyNotNull(null) = false + * ObjectUtils.anyNotNull(null, null) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code true} if there is at least one non-null value in the array, + * {@code false} if all values in the array are {@code null}s. + * If the array is {@code null} or empty {@code false} is also returned. + * @since 3.5 + */ + public static boolean anyNotNull(final Object... values) { + return firstNonNull(values) != null; + } + + /** + * Checks if all values in the array are not {@code nulls}. + * + *
+ * If any value is {@code null} or the array is {@code null} then + * {@code false} is returned. If all elements in array are not + * {@code null} or the array is empty (contains no elements) {@code true} + * is returned. + *
+ * + *+ * ObjectUtils.allNotNull(*) = true + * ObjectUtils.allNotNull(*, *) = true + * ObjectUtils.allNotNull(null) = false + * ObjectUtils.allNotNull(null, null) = false + * ObjectUtils.allNotNull(null, *) = false + * ObjectUtils.allNotNull(*, null) = false + * ObjectUtils.allNotNull(*, *, null, *) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code false} if there is at least one {@code null} value in the array or the array is {@code null}, + * {@code true} if all values in the array are not {@code null}s or array contains no elements. + * @since 3.5 + */ + public static boolean allNotNull(final Object... values) { + if (values == null) { + return false; + } + + for (final Object val : values) { + if (val == null) { + return false; + } + } + + return true; + } + + // Null-safe equals/hashCode + //----------------------------------------------------------------------- + /** + *
Compares two objects for equality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.equals(null, null) = true + * ObjectUtils.equals(null, "") = false + * ObjectUtils.equals("", null) = false + * ObjectUtils.equals("", "") = true + * ObjectUtils.equals(Boolean.TRUE, null) = false + * ObjectUtils.equals(Boolean.TRUE, "true") = false + * ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE) = true + * ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code true} if the values of both objects are the same + * @deprecated this method has been replaced by {@code java.util.Objects.equals(Object, Object)} in Java 7 and will + * be removed from future releases. + */ + @Deprecated + public static boolean equals(final Object object1, final Object object2) { + if (object1 == object2) { + return true; + } + if (object1 == null || object2 == null) { + return false; + } + return object1.equals(object2); + } + + /** + *
Compares two objects for inequality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.notEqual(null, null) = false + * ObjectUtils.notEqual(null, "") = true + * ObjectUtils.notEqual("", null) = true + * ObjectUtils.notEqual("", "") = false + * ObjectUtils.notEqual(Boolean.TRUE, null) = true + * ObjectUtils.notEqual(Boolean.TRUE, "true") = true + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE) = false + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code false} if the values of both objects are the same + */ + public static boolean notEqual(final Object object1, final Object object2) { + return ObjectUtils.equals(object1, object2) == false; + } + + /** + *
Gets the hash code of an object returning zero when the + * object is {@code null}.
+ * + *+ * ObjectUtils.hashCode(null) = 0 + * ObjectUtils.hashCode(obj) = obj.hashCode() + *+ * + * @param obj the object to obtain the hash code of, may be {@code null} + * @return the hash code of the object, or zero if null + * @since 2.1 + * @deprecated this method has been replaced by {@code java.util.Objects.hashCode(Object)} in Java 7 and will be + * removed in future releases + */ + @Deprecated +/** + *
Gets the hash code of an object returning zero when the + * object is {@code null}.
+ * + *+ * ObjectUtils.hashCode(null) = 0 + * ObjectUtils.hashCode(obj) = obj.hashCode() + *+ * + * @param obj + * the object to obtain the hash code of, may be {@code null} + * @return the hash code of the object, or zero if null + * @since 2.1 + * @deprecated this method has been replaced by {@code java.util.Objects.hashCode(Object)} in Java 7 and will be +removed in future releases + */ +public static int hashCode(final java.lang.Object obj) { + // hashCode(Object) retained for performance, as hash code is often critical + return /* NPEX_NULL_EXP */ + obj.hashCode(); +} + + /** + *
Gets the hash code for multiple objects.
+ * + *This allows a hash code to be rapidly calculated for a number of objects. + * The hash code for a single object is the not same as {@link #hashCode(Object)}. + * The hash code for multiple objects is the same as that calculated by an + * {@code ArrayList} containing the specified objects.
+ * + *+ * ObjectUtils.hashCodeMulti() = 1 + * ObjectUtils.hashCodeMulti((Object[]) null) = 1 + * ObjectUtils.hashCodeMulti(a) = 31 + a.hashCode() + * ObjectUtils.hashCodeMulti(a,b) = (31 + a.hashCode()) * 31 + b.hashCode() + * ObjectUtils.hashCodeMulti(a,b,c) = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode() + *+ * + * @param objects the objects to obtain the hash code of, may be {@code null} + * @return the hash code of the objects, or zero if null + * @since 3.0 + * @deprecated this method has been replaced by {@code java.util.Objects.hash(Object...)} in Java 7 and will be + * removed in future releases. + */ + @Deprecated + public static int hashCodeMulti(final Object... objects) { + int hash = 1; + if (objects != null) { + for (final Object object : objects) { + final int tmpHash = ObjectUtils.hashCode(object); + hash = hash * 31 + tmpHash; + } + } + return hash; + } + + // Identity ToString + //----------------------------------------------------------------------- + /** + *
Gets the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will return {@code null}.
+ * + *+ * ObjectUtils.identityToString(null) = null + * ObjectUtils.identityToString("") = "java.lang.String@1e23" + * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa" + *+ * + * @param object the object to create a toString for, may be + * {@code null} + * @return the default toString text, or {@code null} if + * {@code null} passed in + */ + public static String identityToString(final Object object) { + if (object == null) { + return null; + } + final StringBuilder builder = new StringBuilder(); + identityToString(builder, object); + return builder.toString(); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(appendable, "") = appendable.append("java.lang.String@1e23" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa") + *+ * + * @param appendable the appendable to append to + * @param object the object to create a toString for + * @throws IOException if an I/O error occurs + * @since 3.2 + */ + public static void identityToString(final Appendable appendable, final Object object) throws IOException { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + appendable.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StrBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(buf, "") = buf.append("java.lang.String@1e23" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa") + *+ * + * @param buffer the buffer to append to + * @param object the object to create a toString for + * @since 2.4 + */ + public static void identityToString(final StringBuffer buffer, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + buffer.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StringBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + // ToString + //----------------------------------------------------------------------- + /** + *
Gets the {@code toString} of an {@code Object} returning + * an empty string ("") if {@code null} input.
+ * + *+ * ObjectUtils.toString(null) = "" + * ObjectUtils.toString("") = "" + * ObjectUtils.toString("bat") = "bat" + * ObjectUtils.toString(Boolean.TRUE) = "true" + *+ * + * @see StringUtils#defaultString(String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @return the passed in Object's toString, or {@code ""} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object)} in Java 7 and will be + * removed in future releases. Note however that said method will return "null" for null references, while this + * method returns and empty String. To preserve behavior use {@code java.util.Objects.toString(myObject, "")} + */ + @Deprecated + public static String toString(final Object obj) { + return obj == null ? StringUtils.EMPTY : obj.toString(); + } + + /** + *
Gets the {@code toString} of an {@code Object} returning + * a specified text if {@code null} input.
+ * + *+ * ObjectUtils.toString(null, null) = null + * ObjectUtils.toString(null, "null") = "null" + * ObjectUtils.toString("", "null") = "" + * ObjectUtils.toString("bat", "null") = "bat" + * ObjectUtils.toString(Boolean.TRUE, "null") = "true" + *+ * + * @see StringUtils#defaultString(String,String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @param nullStr the String to return if {@code null} input, may be null + * @return the passed in Object's toString, or {@code nullStr} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object, String)} in Java 7 and + * will be removed in future releases. + */ + @Deprecated + public static String toString(final Object obj, final String nullStr) { + return obj == null ? nullStr : obj.toString(); + } + + // Comparable + //----------------------------------------------------------------------- + /** + *
Null safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables. + * {@code null} is assumed to be less than a non-{@code null} value.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramClone an object.
+ * + * @paramClone an object if possible.
+ * + *This method is similar to {@link #clone(Object)}, but will return the provided + * instance as the return value instead of {@code null} if the instance + * is not cloneable. This is more convenient if the caller uses different + * implementations (e.g. of a service) and some of the implementations do not allow concurrent + * processing or have state. In such cases the implementation can simply provide a proper + * clone implementation and the caller's code does not have to change.
+ * + * @paramClass used as a null placeholder where {@code null} + * has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there is + * no matching key. The {@code Null} placeholder can be used to distinguish + * between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ */ + public static class Null implements Serializable { + /** + * Required for serialization support. Declare serialization compatibility with Commons Lang 1.0 + * + * @see java.io.Serializable + */ + private static final long serialVersionUID = 7092611880189329093L; + + /** + * Restricted constructor - singleton. + */ + Null() { + super(); + } + + /** + *Ensure singleton.
+ * + * @return the singleton value + */ + private Object readResolve() { + return ObjectUtils.NULL; + } + } + + + // Constants (LANG-816): + /* + These methods ensure constants are not inlined by javac. + For example, typically a developer might declare a constant like so: + + public final static int MAGIC_NUMBER = 5; + + Should a different jar file refer to this, and the MAGIC_NUMBER + is changed a later date (e.g., MAGIC_NUMBER = 6), the different jar + file will need to recompile itself. This is because javac + typically inlines the primitive or String constant directly into + the bytecode, and removes the reference to the MAGIC_NUMBER field. + + To help the other jar (so that it does not need to recompile + when constants are changed) the original developer can declare + their constant using one of the CONST() utility methods, instead: + + public final static int MAGIC_NUMBER = CONST(5); + */ + + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *+ * public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the boolean value to return + * @return the boolean v, unchanged + * @since 3.2 + */ + public static boolean CONST(final boolean v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the byte value to return + * @return the byte v, unchanged + * @since 3.2 + */ + public static byte CONST(final byte v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the byte literal (as an int) value to return + * @throws IllegalArgumentException if the value passed to v + * is larger than a byte, that is, smaller than -128 or + * larger than 127. + * @return the byte v, unchanged + * @since 3.2 + */ + public static byte CONST_BYTE(final int v) throws IllegalArgumentException { + if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) { + throw new IllegalArgumentException("Supplied value must be a valid byte literal between -128 and 127: [" + v + "]"); + } + return (byte) v; + } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static char MAGIC_CHAR = ObjectUtils.CONST('a'); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the char value to return + * @return the char v, unchanged + * @since 3.2 + */ + public static char CONST(final char v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the short value to return + * @return the short v, unchanged + * @since 3.2 + */ + public static short CONST(final short v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the short literal (as an int) value to return + * @throws IllegalArgumentException if the value passed to v + * is larger than a short, that is, smaller than -32768 or + * larger than 32767. + * @return the byte v, unchanged + * @since 3.2 + */ + public static short CONST_SHORT(final int v) throws IllegalArgumentException { + if (v < Short.MIN_VALUE || v > Short.MAX_VALUE) { + throw new IllegalArgumentException("Supplied value must be a valid byte literal between -32768 and 32767: [" + v + "]"); + } + return (short) v; + } + + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static int MAGIC_INT = ObjectUtils.CONST(123); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the int value to return + * @return the int v, unchanged + * @since 3.2 + */ + public static int CONST(final int v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static long MAGIC_LONG = ObjectUtils.CONST(123L); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the long value to return + * @return the long v, unchanged + * @since 3.2 + */ + public static long CONST(final long v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the float value to return + * @return the float v, unchanged + * @since 3.2 + */ + public static float CONST(final float v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the double value to return + * @return the double v, unchanged + * @since 3.2 + */ + public static double CONST(final double v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static String MAGIC_STRING = ObjectUtils.CONST("abc"); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param
Operations on {@code Object}.
+ * + *This class tries to handle {@code null} input gracefully. + * An exception will generally not be thrown for a {@code null} input. + * Each method documents its behaviour in more detail.
+ * + *#ThreadSafe#
+ * @since 1.0 + */ +//@Immutable +public class ObjectUtils { + + /** + *Singleton used as a {@code null} placeholder where + * {@code null} has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there + * is no matching key. The {@code Null} placeholder can be used to + * distinguish between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ * + *This instance is Serializable.
+ */ + public static final Null NULL = new Null(); + + /** + *{@code ObjectUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code ObjectUtils.defaultIfNull("a","b");}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public ObjectUtils() { + super(); + } + + // Defaulting + //----------------------------------------------------------------------- + /** + *Returns a default value if the object passed is {@code null}.
+ * + *+ * ObjectUtils.defaultIfNull(null, null) = null + * ObjectUtils.defaultIfNull(null, "") = "" + * ObjectUtils.defaultIfNull(null, "zz") = "zz" + * ObjectUtils.defaultIfNull("abc", *) = "abc" + * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE + *+ * + * @param
Returns the first value in the array which is not {@code null}. + * If all the values are {@code null} or the array is {@code null} + * or empty then {@code null} is returned.
+ * + *+ * ObjectUtils.firstNonNull(null, null) = null + * ObjectUtils.firstNonNull(null, "") = "" + * ObjectUtils.firstNonNull(null, null, "") = "" + * ObjectUtils.firstNonNull(null, "zz") = "zz" + * ObjectUtils.firstNonNull("abc", *) = "abc" + * ObjectUtils.firstNonNull(null, "xyz", *) = "xyz" + * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE + * ObjectUtils.firstNonNull() = null + *+ * + * @param
+ * If all the values are {@code null} or the array is {@code null} + * or empty then {@code false} is returned. Otherwise {@code true} is returned. + *
+ * + *+ * ObjectUtils.anyNotNull(*) = true + * ObjectUtils.anyNotNull(*, null) = true + * ObjectUtils.anyNotNull(null, *) = true + * ObjectUtils.anyNotNull(null, null, *, *) = true + * ObjectUtils.anyNotNull(null) = false + * ObjectUtils.anyNotNull(null, null) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code true} if there is at least one non-null value in the array, + * {@code false} if all values in the array are {@code null}s. + * If the array is {@code null} or empty {@code false} is also returned. + * @since 3.5 + */ + public static boolean anyNotNull(final Object... values) { + return firstNonNull(values) != null; + } + + /** + * Checks if all values in the array are not {@code nulls}. + * + *
+ * If any value is {@code null} or the array is {@code null} then + * {@code false} is returned. If all elements in array are not + * {@code null} or the array is empty (contains no elements) {@code true} + * is returned. + *
+ * + *+ * ObjectUtils.allNotNull(*) = true + * ObjectUtils.allNotNull(*, *) = true + * ObjectUtils.allNotNull(null) = false + * ObjectUtils.allNotNull(null, null) = false + * ObjectUtils.allNotNull(null, *) = false + * ObjectUtils.allNotNull(*, null) = false + * ObjectUtils.allNotNull(*, *, null, *) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code false} if there is at least one {@code null} value in the array or the array is {@code null}, + * {@code true} if all values in the array are not {@code null}s or array contains no elements. + * @since 3.5 + */ + public static boolean allNotNull(final Object... values) { + if (values == null) { + return false; + } + + for (final Object val : values) { + if (val == null) { + return false; + } + } + + return true; + } + + // Null-safe equals/hashCode + //----------------------------------------------------------------------- + /** + *
Compares two objects for equality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.equals(null, null) = true + * ObjectUtils.equals(null, "") = false + * ObjectUtils.equals("", null) = false + * ObjectUtils.equals("", "") = true + * ObjectUtils.equals(Boolean.TRUE, null) = false + * ObjectUtils.equals(Boolean.TRUE, "true") = false + * ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE) = true + * ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code true} if the values of both objects are the same + * @deprecated this method has been replaced by {@code java.util.Objects.equals(Object, Object)} in Java 7 and will + * be removed from future releases. + */ + @Deprecated + public static boolean equals(final Object object1, final Object object2) { + if (object1 == object2) { + return true; + } + if (object1 == null || object2 == null) { + return false; + } + return object1.equals(object2); + } + + /** + *
Compares two objects for inequality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.notEqual(null, null) = false + * ObjectUtils.notEqual(null, "") = true + * ObjectUtils.notEqual("", null) = true + * ObjectUtils.notEqual("", "") = false + * ObjectUtils.notEqual(Boolean.TRUE, null) = true + * ObjectUtils.notEqual(Boolean.TRUE, "true") = true + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE) = false + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code false} if the values of both objects are the same + */ + public static boolean notEqual(final Object object1, final Object object2) { + return ObjectUtils.equals(object1, object2) == false; + } + + /** + *
Gets the hash code of an object returning zero when the + * object is {@code null}.
+ * + *+ * ObjectUtils.hashCode(null) = 0 + * ObjectUtils.hashCode(obj) = obj.hashCode() + *+ * + * @param obj the object to obtain the hash code of, may be {@code null} + * @return the hash code of the object, or zero if null + * @since 2.1 + * @deprecated this method has been replaced by {@code java.util.Objects.hashCode(Object)} in Java 7 and will be + * removed in future releases + */ + @Deprecated + public static int hashCode(final Object obj) { + // hashCode(Object) retained for performance, as hash code is often critical + return obj == null ? 0 : obj.hashCode(); + } + + /** + *
Gets the hash code for multiple objects.
+ * + *This allows a hash code to be rapidly calculated for a number of objects. + * The hash code for a single object is the not same as {@link #hashCode(Object)}. + * The hash code for multiple objects is the same as that calculated by an + * {@code ArrayList} containing the specified objects.
+ * + *+ * ObjectUtils.hashCodeMulti() = 1 + * ObjectUtils.hashCodeMulti((Object[]) null) = 1 + * ObjectUtils.hashCodeMulti(a) = 31 + a.hashCode() + * ObjectUtils.hashCodeMulti(a,b) = (31 + a.hashCode()) * 31 + b.hashCode() + * ObjectUtils.hashCodeMulti(a,b,c) = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode() + *+ * + * @param objects the objects to obtain the hash code of, may be {@code null} + * @return the hash code of the objects, or zero if null + * @since 3.0 + * @deprecated this method has been replaced by {@code java.util.Objects.hash(Object...)} in Java 7 and will be + * removed in future releases. + */ + @Deprecated +/** + *
Gets the hash code for multiple objects.
+ * + *This allows a hash code to be rapidly calculated for a number of objects. + * The hash code for a single object is the not same as {@link #hashCode(Object)}. + * The hash code for multiple objects is the same as that calculated by an + * {@code ArrayList} containing the specified objects.
+ * + *+ * ObjectUtils.hashCodeMulti() = 1 + * ObjectUtils.hashCodeMulti((Object[]) null) = 1 + * ObjectUtils.hashCodeMulti(a) = 31 + a.hashCode() + * ObjectUtils.hashCodeMulti(a,b) = (31 + a.hashCode()) * 31 + b.hashCode() + * ObjectUtils.hashCodeMulti(a,b,c) = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode() + *+ * + * @param objects + * the objects to obtain the hash code of, may be {@code null} + * @return the hash code of the objects, or zero if null + * @since 3.0 + * @deprecated this method has been replaced by {@code java.util.Objects.hash(Object...)} in Java 7 and will be +removed in future releases. + */ +public static int hashCodeMulti(final java.lang.Object... objects) { + int hash = 1; + { + for (final java.lang.Object object : /* NPEX_NULL_EXP */ + objects) { + final int tmpHash = org.apache.commons.lang3.ObjectUtils.hashCode(object); + hash = (hash * 31) + tmpHash; + } + } + return hash; +} + + // Identity ToString + //----------------------------------------------------------------------- + /** + *
Gets the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will return {@code null}.
+ * + *+ * ObjectUtils.identityToString(null) = null + * ObjectUtils.identityToString("") = "java.lang.String@1e23" + * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa" + *+ * + * @param object the object to create a toString for, may be + * {@code null} + * @return the default toString text, or {@code null} if + * {@code null} passed in + */ + public static String identityToString(final Object object) { + if (object == null) { + return null; + } + final StringBuilder builder = new StringBuilder(); + identityToString(builder, object); + return builder.toString(); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(appendable, "") = appendable.append("java.lang.String@1e23" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa") + *+ * + * @param appendable the appendable to append to + * @param object the object to create a toString for + * @throws IOException if an I/O error occurs + * @since 3.2 + */ + public static void identityToString(final Appendable appendable, final Object object) throws IOException { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + appendable.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StrBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(buf, "") = buf.append("java.lang.String@1e23" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa") + *+ * + * @param buffer the buffer to append to + * @param object the object to create a toString for + * @since 2.4 + */ + public static void identityToString(final StringBuffer buffer, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + buffer.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StringBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + // ToString + //----------------------------------------------------------------------- + /** + *
Gets the {@code toString} of an {@code Object} returning + * an empty string ("") if {@code null} input.
+ * + *+ * ObjectUtils.toString(null) = "" + * ObjectUtils.toString("") = "" + * ObjectUtils.toString("bat") = "bat" + * ObjectUtils.toString(Boolean.TRUE) = "true" + *+ * + * @see StringUtils#defaultString(String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @return the passed in Object's toString, or {@code ""} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object)} in Java 7 and will be + * removed in future releases. Note however that said method will return "null" for null references, while this + * method returns and empty String. To preserve behavior use {@code java.util.Objects.toString(myObject, "")} + */ + @Deprecated + public static String toString(final Object obj) { + return obj == null ? StringUtils.EMPTY : obj.toString(); + } + + /** + *
Gets the {@code toString} of an {@code Object} returning + * a specified text if {@code null} input.
+ * + *+ * ObjectUtils.toString(null, null) = null + * ObjectUtils.toString(null, "null") = "null" + * ObjectUtils.toString("", "null") = "" + * ObjectUtils.toString("bat", "null") = "bat" + * ObjectUtils.toString(Boolean.TRUE, "null") = "true" + *+ * + * @see StringUtils#defaultString(String,String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @param nullStr the String to return if {@code null} input, may be null + * @return the passed in Object's toString, or {@code nullStr} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object, String)} in Java 7 and + * will be removed in future releases. + */ + @Deprecated + public static String toString(final Object obj, final String nullStr) { + return obj == null ? nullStr : obj.toString(); + } + + // Comparable + //----------------------------------------------------------------------- + /** + *
Null safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables. + * {@code null} is assumed to be less than a non-{@code null} value.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramClone an object.
+ * + * @paramClone an object if possible.
+ * + *This method is similar to {@link #clone(Object)}, but will return the provided + * instance as the return value instead of {@code null} if the instance + * is not cloneable. This is more convenient if the caller uses different + * implementations (e.g. of a service) and some of the implementations do not allow concurrent + * processing or have state. In such cases the implementation can simply provide a proper + * clone implementation and the caller's code does not have to change.
+ * + * @paramClass used as a null placeholder where {@code null} + * has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there is + * no matching key. The {@code Null} placeholder can be used to distinguish + * between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ */ + public static class Null implements Serializable { + /** + * Required for serialization support. Declare serialization compatibility with Commons Lang 1.0 + * + * @see java.io.Serializable + */ + private static final long serialVersionUID = 7092611880189329093L; + + /** + * Restricted constructor - singleton. + */ + Null() { + super(); + } + + /** + *Ensure singleton.
+ * + * @return the singleton value + */ + private Object readResolve() { + return ObjectUtils.NULL; + } + } + + + // Constants (LANG-816): + /* + These methods ensure constants are not inlined by javac. + For example, typically a developer might declare a constant like so: + + public final static int MAGIC_NUMBER = 5; + + Should a different jar file refer to this, and the MAGIC_NUMBER + is changed a later date (e.g., MAGIC_NUMBER = 6), the different jar + file will need to recompile itself. This is because javac + typically inlines the primitive or String constant directly into + the bytecode, and removes the reference to the MAGIC_NUMBER field. + + To help the other jar (so that it does not need to recompile + when constants are changed) the original developer can declare + their constant using one of the CONST() utility methods, instead: + + public final static int MAGIC_NUMBER = CONST(5); + */ + + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *+ * public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the boolean value to return + * @return the boolean v, unchanged + * @since 3.2 + */ + public static boolean CONST(final boolean v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the byte value to return + * @return the byte v, unchanged + * @since 3.2 + */ + public static byte CONST(final byte v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the byte literal (as an int) value to return + * @throws IllegalArgumentException if the value passed to v + * is larger than a byte, that is, smaller than -128 or + * larger than 127. + * @return the byte v, unchanged + * @since 3.2 + */ + public static byte CONST_BYTE(final int v) throws IllegalArgumentException { + if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) { + throw new IllegalArgumentException("Supplied value must be a valid byte literal between -128 and 127: [" + v + "]"); + } + return (byte) v; + } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static char MAGIC_CHAR = ObjectUtils.CONST('a'); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the char value to return + * @return the char v, unchanged + * @since 3.2 + */ + public static char CONST(final char v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the short value to return + * @return the short v, unchanged + * @since 3.2 + */ + public static short CONST(final short v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the short literal (as an int) value to return + * @throws IllegalArgumentException if the value passed to v + * is larger than a short, that is, smaller than -32768 or + * larger than 32767. + * @return the byte v, unchanged + * @since 3.2 + */ + public static short CONST_SHORT(final int v) throws IllegalArgumentException { + if (v < Short.MIN_VALUE || v > Short.MAX_VALUE) { + throw new IllegalArgumentException("Supplied value must be a valid byte literal between -32768 and 32767: [" + v + "]"); + } + return (short) v; + } + + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static int MAGIC_INT = ObjectUtils.CONST(123); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the int value to return + * @return the int v, unchanged + * @since 3.2 + */ + public static int CONST(final int v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static long MAGIC_LONG = ObjectUtils.CONST(123L); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the long value to return + * @return the long v, unchanged + * @since 3.2 + */ + public static long CONST(final long v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the float value to return + * @return the float v, unchanged + * @since 3.2 + */ + public static float CONST(final float v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the double value to return + * @return the double v, unchanged + * @since 3.2 + */ + public static double CONST(final double v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static String MAGIC_STRING = ObjectUtils.CONST("abc"); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param
Operations on {@code Object}.
+ * + *This class tries to handle {@code null} input gracefully. + * An exception will generally not be thrown for a {@code null} input. + * Each method documents its behaviour in more detail.
+ * + *#ThreadSafe#
+ * @since 1.0 + */ +//@Immutable +public class ObjectUtils { + + /** + *Singleton used as a {@code null} placeholder where + * {@code null} has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there + * is no matching key. The {@code Null} placeholder can be used to + * distinguish between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ * + *This instance is Serializable.
+ */ + public static final Null NULL = new Null(); + + /** + *{@code ObjectUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code ObjectUtils.defaultIfNull("a","b");}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public ObjectUtils() { + super(); + } + + // Defaulting + //----------------------------------------------------------------------- + /** + *Returns a default value if the object passed is {@code null}.
+ * + *+ * ObjectUtils.defaultIfNull(null, null) = null + * ObjectUtils.defaultIfNull(null, "") = "" + * ObjectUtils.defaultIfNull(null, "zz") = "zz" + * ObjectUtils.defaultIfNull("abc", *) = "abc" + * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE + *+ * + * @param
Returns the first value in the array which is not {@code null}. + * If all the values are {@code null} or the array is {@code null} + * or empty then {@code null} is returned.
+ * + *+ * ObjectUtils.firstNonNull(null, null) = null + * ObjectUtils.firstNonNull(null, "") = "" + * ObjectUtils.firstNonNull(null, null, "") = "" + * ObjectUtils.firstNonNull(null, "zz") = "zz" + * ObjectUtils.firstNonNull("abc", *) = "abc" + * ObjectUtils.firstNonNull(null, "xyz", *) = "xyz" + * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE + * ObjectUtils.firstNonNull() = null + *+ * + * @param
+ * If all the values are {@code null} or the array is {@code null} + * or empty then {@code false} is returned. Otherwise {@code true} is returned. + *
+ * + *+ * ObjectUtils.anyNotNull(*) = true + * ObjectUtils.anyNotNull(*, null) = true + * ObjectUtils.anyNotNull(null, *) = true + * ObjectUtils.anyNotNull(null, null, *, *) = true + * ObjectUtils.anyNotNull(null) = false + * ObjectUtils.anyNotNull(null, null) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code true} if there is at least one non-null value in the array, + * {@code false} if all values in the array are {@code null}s. + * If the array is {@code null} or empty {@code false} is also returned. + * @since 3.5 + */ + public static boolean anyNotNull(final Object... values) { + return firstNonNull(values) != null; + } + + /** + * Checks if all values in the array are not {@code nulls}. + * + *
+ * If any value is {@code null} or the array is {@code null} then + * {@code false} is returned. If all elements in array are not + * {@code null} or the array is empty (contains no elements) {@code true} + * is returned. + *
+ * + *+ * ObjectUtils.allNotNull(*) = true + * ObjectUtils.allNotNull(*, *) = true + * ObjectUtils.allNotNull(null) = false + * ObjectUtils.allNotNull(null, null) = false + * ObjectUtils.allNotNull(null, *) = false + * ObjectUtils.allNotNull(*, null) = false + * ObjectUtils.allNotNull(*, *, null, *) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code false} if there is at least one {@code null} value in the array or the array is {@code null}, + * {@code true} if all values in the array are not {@code null}s or array contains no elements. + * @since 3.5 + */ + public static boolean allNotNull(final Object... values) { + if (values == null) { + return false; + } + + for (final Object val : values) { + if (val == null) { + return false; + } + } + + return true; + } + + // Null-safe equals/hashCode + //----------------------------------------------------------------------- + /** + *
Compares two objects for equality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.equals(null, null) = true + * ObjectUtils.equals(null, "") = false + * ObjectUtils.equals("", null) = false + * ObjectUtils.equals("", "") = true + * ObjectUtils.equals(Boolean.TRUE, null) = false + * ObjectUtils.equals(Boolean.TRUE, "true") = false + * ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE) = true + * ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code true} if the values of both objects are the same + * @deprecated this method has been replaced by {@code java.util.Objects.equals(Object, Object)} in Java 7 and will + * be removed from future releases. + */ + @Deprecated + public static boolean equals(final Object object1, final Object object2) { + if (object1 == object2) { + return true; + } + if (object1 == null || object2 == null) { + return false; + } + return object1.equals(object2); + } + + /** + *
Compares two objects for inequality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.notEqual(null, null) = false + * ObjectUtils.notEqual(null, "") = true + * ObjectUtils.notEqual("", null) = true + * ObjectUtils.notEqual("", "") = false + * ObjectUtils.notEqual(Boolean.TRUE, null) = true + * ObjectUtils.notEqual(Boolean.TRUE, "true") = true + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE) = false + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code false} if the values of both objects are the same + */ + public static boolean notEqual(final Object object1, final Object object2) { + return ObjectUtils.equals(object1, object2) == false; + } + + /** + *
Gets the hash code of an object returning zero when the + * object is {@code null}.
+ * + *+ * ObjectUtils.hashCode(null) = 0 + * ObjectUtils.hashCode(obj) = obj.hashCode() + *+ * + * @param obj the object to obtain the hash code of, may be {@code null} + * @return the hash code of the object, or zero if null + * @since 2.1 + * @deprecated this method has been replaced by {@code java.util.Objects.hashCode(Object)} in Java 7 and will be + * removed in future releases + */ + @Deprecated + public static int hashCode(final Object obj) { + // hashCode(Object) retained for performance, as hash code is often critical + return obj == null ? 0 : obj.hashCode(); + } + + /** + *
Gets the hash code for multiple objects.
+ * + *This allows a hash code to be rapidly calculated for a number of objects. + * The hash code for a single object is the not same as {@link #hashCode(Object)}. + * The hash code for multiple objects is the same as that calculated by an + * {@code ArrayList} containing the specified objects.
+ * + *+ * ObjectUtils.hashCodeMulti() = 1 + * ObjectUtils.hashCodeMulti((Object[]) null) = 1 + * ObjectUtils.hashCodeMulti(a) = 31 + a.hashCode() + * ObjectUtils.hashCodeMulti(a,b) = (31 + a.hashCode()) * 31 + b.hashCode() + * ObjectUtils.hashCodeMulti(a,b,c) = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode() + *+ * + * @param objects the objects to obtain the hash code of, may be {@code null} + * @return the hash code of the objects, or zero if null + * @since 3.0 + * @deprecated this method has been replaced by {@code java.util.Objects.hash(Object...)} in Java 7 and will be + * removed in future releases. + */ + @Deprecated + public static int hashCodeMulti(final Object... objects) { + int hash = 1; + if (objects != null) { + for (final Object object : objects) { + final int tmpHash = ObjectUtils.hashCode(object); + hash = hash * 31 + tmpHash; + } + } + return hash; + } + + // Identity ToString + //----------------------------------------------------------------------- + /** + *
Gets the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will return {@code null}.
+ * + *+ * ObjectUtils.identityToString(null) = null + * ObjectUtils.identityToString("") = "java.lang.String@1e23" + * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa" + *+ * + * @param object the object to create a toString for, may be + * {@code null} + * @return the default toString text, or {@code null} if + * {@code null} passed in + */ +// Identity ToString +// ----------------------------------------------------------------------- +/** + *
Gets the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will return {@code null}.
+ * + *+ * ObjectUtils.identityToString(null) = null + * ObjectUtils.identityToString("") = "java.lang.String@1e23" + * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa" + *+ * + * @param object + * the object to create a toString for, may be + * {@code null} + * @return the default toString text, or {@code null} if +{@code null} passed in + */ +public static java.lang.String identityToString(final java.lang.Object object) { + { + final java.lang.StringBuilder builder = new java.lang.StringBuilder(); + org.apache.commons.lang3.ObjectUtils.identityToString(builder, /* NPEX_NULL_EXP */ + object); + return builder.toString(); + } +} + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(appendable, "") = appendable.append("java.lang.String@1e23" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa") + *+ * + * @param appendable the appendable to append to + * @param object the object to create a toString for + * @throws IOException if an I/O error occurs + * @since 3.2 + */ + public static void identityToString(final Appendable appendable, final Object object) throws IOException { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + appendable.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StrBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(buf, "") = buf.append("java.lang.String@1e23" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa") + *+ * + * @param buffer the buffer to append to + * @param object the object to create a toString for + * @since 2.4 + */ + public static void identityToString(final StringBuffer buffer, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + buffer.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StringBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + // ToString + //----------------------------------------------------------------------- + /** + *
Gets the {@code toString} of an {@code Object} returning + * an empty string ("") if {@code null} input.
+ * + *+ * ObjectUtils.toString(null) = "" + * ObjectUtils.toString("") = "" + * ObjectUtils.toString("bat") = "bat" + * ObjectUtils.toString(Boolean.TRUE) = "true" + *+ * + * @see StringUtils#defaultString(String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @return the passed in Object's toString, or {@code ""} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object)} in Java 7 and will be + * removed in future releases. Note however that said method will return "null" for null references, while this + * method returns and empty String. To preserve behavior use {@code java.util.Objects.toString(myObject, "")} + */ + @Deprecated + public static String toString(final Object obj) { + return obj == null ? StringUtils.EMPTY : obj.toString(); + } + + /** + *
Gets the {@code toString} of an {@code Object} returning + * a specified text if {@code null} input.
+ * + *+ * ObjectUtils.toString(null, null) = null + * ObjectUtils.toString(null, "null") = "null" + * ObjectUtils.toString("", "null") = "" + * ObjectUtils.toString("bat", "null") = "bat" + * ObjectUtils.toString(Boolean.TRUE, "null") = "true" + *+ * + * @see StringUtils#defaultString(String,String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @param nullStr the String to return if {@code null} input, may be null + * @return the passed in Object's toString, or {@code nullStr} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object, String)} in Java 7 and + * will be removed in future releases. + */ + @Deprecated + public static String toString(final Object obj, final String nullStr) { + return obj == null ? nullStr : obj.toString(); + } + + // Comparable + //----------------------------------------------------------------------- + /** + *
Null safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables. + * {@code null} is assumed to be less than a non-{@code null} value.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramClone an object.
+ * + * @paramClone an object if possible.
+ * + *This method is similar to {@link #clone(Object)}, but will return the provided + * instance as the return value instead of {@code null} if the instance + * is not cloneable. This is more convenient if the caller uses different + * implementations (e.g. of a service) and some of the implementations do not allow concurrent + * processing or have state. In such cases the implementation can simply provide a proper + * clone implementation and the caller's code does not have to change.
+ * + * @paramClass used as a null placeholder where {@code null} + * has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there is + * no matching key. The {@code Null} placeholder can be used to distinguish + * between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ */ + public static class Null implements Serializable { + /** + * Required for serialization support. Declare serialization compatibility with Commons Lang 1.0 + * + * @see java.io.Serializable + */ + private static final long serialVersionUID = 7092611880189329093L; + + /** + * Restricted constructor - singleton. + */ + Null() { + super(); + } + + /** + *Ensure singleton.
+ * + * @return the singleton value + */ + private Object readResolve() { + return ObjectUtils.NULL; + } + } + + + // Constants (LANG-816): + /* + These methods ensure constants are not inlined by javac. + For example, typically a developer might declare a constant like so: + + public final static int MAGIC_NUMBER = 5; + + Should a different jar file refer to this, and the MAGIC_NUMBER + is changed a later date (e.g., MAGIC_NUMBER = 6), the different jar + file will need to recompile itself. This is because javac + typically inlines the primitive or String constant directly into + the bytecode, and removes the reference to the MAGIC_NUMBER field. + + To help the other jar (so that it does not need to recompile + when constants are changed) the original developer can declare + their constant using one of the CONST() utility methods, instead: + + public final static int MAGIC_NUMBER = CONST(5); + */ + + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *+ * public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the boolean value to return + * @return the boolean v, unchanged + * @since 3.2 + */ + public static boolean CONST(final boolean v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the byte value to return + * @return the byte v, unchanged + * @since 3.2 + */ + public static byte CONST(final byte v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the byte literal (as an int) value to return + * @throws IllegalArgumentException if the value passed to v + * is larger than a byte, that is, smaller than -128 or + * larger than 127. + * @return the byte v, unchanged + * @since 3.2 + */ + public static byte CONST_BYTE(final int v) throws IllegalArgumentException { + if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) { + throw new IllegalArgumentException("Supplied value must be a valid byte literal between -128 and 127: [" + v + "]"); + } + return (byte) v; + } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static char MAGIC_CHAR = ObjectUtils.CONST('a'); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the char value to return + * @return the char v, unchanged + * @since 3.2 + */ + public static char CONST(final char v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the short value to return + * @return the short v, unchanged + * @since 3.2 + */ + public static short CONST(final short v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the short literal (as an int) value to return + * @throws IllegalArgumentException if the value passed to v + * is larger than a short, that is, smaller than -32768 or + * larger than 32767. + * @return the byte v, unchanged + * @since 3.2 + */ + public static short CONST_SHORT(final int v) throws IllegalArgumentException { + if (v < Short.MIN_VALUE || v > Short.MAX_VALUE) { + throw new IllegalArgumentException("Supplied value must be a valid byte literal between -32768 and 32767: [" + v + "]"); + } + return (short) v; + } + + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static int MAGIC_INT = ObjectUtils.CONST(123); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the int value to return + * @return the int v, unchanged + * @since 3.2 + */ + public static int CONST(final int v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static long MAGIC_LONG = ObjectUtils.CONST(123L); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the long value to return + * @return the long v, unchanged + * @since 3.2 + */ + public static long CONST(final long v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the float value to return + * @return the float v, unchanged + * @since 3.2 + */ + public static float CONST(final float v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the double value to return + * @return the double v, unchanged + * @since 3.2 + */ + public static double CONST(final double v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static String MAGIC_STRING = ObjectUtils.CONST("abc"); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param
Operations on {@code Object}.
+ * + *This class tries to handle {@code null} input gracefully. + * An exception will generally not be thrown for a {@code null} input. + * Each method documents its behaviour in more detail.
+ * + *#ThreadSafe#
+ * @since 1.0 + */ +//@Immutable +public class ObjectUtils { + + /** + *Singleton used as a {@code null} placeholder where + * {@code null} has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there + * is no matching key. The {@code Null} placeholder can be used to + * distinguish between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ * + *This instance is Serializable.
+ */ + public static final Null NULL = new Null(); + + /** + *{@code ObjectUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code ObjectUtils.defaultIfNull("a","b");}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public ObjectUtils() { + super(); + } + + // Defaulting + //----------------------------------------------------------------------- + /** + *Returns a default value if the object passed is {@code null}.
+ * + *+ * ObjectUtils.defaultIfNull(null, null) = null + * ObjectUtils.defaultIfNull(null, "") = "" + * ObjectUtils.defaultIfNull(null, "zz") = "zz" + * ObjectUtils.defaultIfNull("abc", *) = "abc" + * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE + *+ * + * @param
Returns the first value in the array which is not {@code null}. + * If all the values are {@code null} or the array is {@code null} + * or empty then {@code null} is returned.
+ * + *+ * ObjectUtils.firstNonNull(null, null) = null + * ObjectUtils.firstNonNull(null, "") = "" + * ObjectUtils.firstNonNull(null, null, "") = "" + * ObjectUtils.firstNonNull(null, "zz") = "zz" + * ObjectUtils.firstNonNull("abc", *) = "abc" + * ObjectUtils.firstNonNull(null, "xyz", *) = "xyz" + * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE + * ObjectUtils.firstNonNull() = null + *+ * + * @param
+ * If all the values are {@code null} or the array is {@code null} + * or empty then {@code false} is returned. Otherwise {@code true} is returned. + *
+ * + *+ * ObjectUtils.anyNotNull(*) = true + * ObjectUtils.anyNotNull(*, null) = true + * ObjectUtils.anyNotNull(null, *) = true + * ObjectUtils.anyNotNull(null, null, *, *) = true + * ObjectUtils.anyNotNull(null) = false + * ObjectUtils.anyNotNull(null, null) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code true} if there is at least one non-null value in the array, + * {@code false} if all values in the array are {@code null}s. + * If the array is {@code null} or empty {@code false} is also returned. + * @since 3.5 + */ + public static boolean anyNotNull(final Object... values) { + return firstNonNull(values) != null; + } + + /** + * Checks if all values in the array are not {@code nulls}. + * + *
+ * If any value is {@code null} or the array is {@code null} then + * {@code false} is returned. If all elements in array are not + * {@code null} or the array is empty (contains no elements) {@code true} + * is returned. + *
+ * + *+ * ObjectUtils.allNotNull(*) = true + * ObjectUtils.allNotNull(*, *) = true + * ObjectUtils.allNotNull(null) = false + * ObjectUtils.allNotNull(null, null) = false + * ObjectUtils.allNotNull(null, *) = false + * ObjectUtils.allNotNull(*, null) = false + * ObjectUtils.allNotNull(*, *, null, *) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code false} if there is at least one {@code null} value in the array or the array is {@code null}, + * {@code true} if all values in the array are not {@code null}s or array contains no elements. + * @since 3.5 + */ + public static boolean allNotNull(final Object... values) { + if (values == null) { + return false; + } + + for (final Object val : values) { + if (val == null) { + return false; + } + } + + return true; + } + + // Null-safe equals/hashCode + //----------------------------------------------------------------------- + /** + *
Compares two objects for equality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.equals(null, null) = true + * ObjectUtils.equals(null, "") = false + * ObjectUtils.equals("", null) = false + * ObjectUtils.equals("", "") = true + * ObjectUtils.equals(Boolean.TRUE, null) = false + * ObjectUtils.equals(Boolean.TRUE, "true") = false + * ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE) = true + * ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code true} if the values of both objects are the same + * @deprecated this method has been replaced by {@code java.util.Objects.equals(Object, Object)} in Java 7 and will + * be removed from future releases. + */ + @Deprecated + public static boolean equals(final Object object1, final Object object2) { + if (object1 == object2) { + return true; + } + if (object1 == null || object2 == null) { + return false; + } + return object1.equals(object2); + } + + /** + *
Compares two objects for inequality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.notEqual(null, null) = false + * ObjectUtils.notEqual(null, "") = true + * ObjectUtils.notEqual("", null) = true + * ObjectUtils.notEqual("", "") = false + * ObjectUtils.notEqual(Boolean.TRUE, null) = true + * ObjectUtils.notEqual(Boolean.TRUE, "true") = true + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE) = false + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code false} if the values of both objects are the same + */ + public static boolean notEqual(final Object object1, final Object object2) { + return ObjectUtils.equals(object1, object2) == false; + } + + /** + *
Gets the hash code of an object returning zero when the + * object is {@code null}.
+ * + *+ * ObjectUtils.hashCode(null) = 0 + * ObjectUtils.hashCode(obj) = obj.hashCode() + *+ * + * @param obj the object to obtain the hash code of, may be {@code null} + * @return the hash code of the object, or zero if null + * @since 2.1 + * @deprecated this method has been replaced by {@code java.util.Objects.hashCode(Object)} in Java 7 and will be + * removed in future releases + */ + @Deprecated + public static int hashCode(final Object obj) { + // hashCode(Object) retained for performance, as hash code is often critical + return obj == null ? 0 : obj.hashCode(); + } + + /** + *
Gets the hash code for multiple objects.
+ * + *This allows a hash code to be rapidly calculated for a number of objects. + * The hash code for a single object is the not same as {@link #hashCode(Object)}. + * The hash code for multiple objects is the same as that calculated by an + * {@code ArrayList} containing the specified objects.
+ * + *+ * ObjectUtils.hashCodeMulti() = 1 + * ObjectUtils.hashCodeMulti((Object[]) null) = 1 + * ObjectUtils.hashCodeMulti(a) = 31 + a.hashCode() + * ObjectUtils.hashCodeMulti(a,b) = (31 + a.hashCode()) * 31 + b.hashCode() + * ObjectUtils.hashCodeMulti(a,b,c) = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode() + *+ * + * @param objects the objects to obtain the hash code of, may be {@code null} + * @return the hash code of the objects, or zero if null + * @since 3.0 + * @deprecated this method has been replaced by {@code java.util.Objects.hash(Object...)} in Java 7 and will be + * removed in future releases. + */ + @Deprecated + public static int hashCodeMulti(final Object... objects) { + int hash = 1; + if (objects != null) { + for (final Object object : objects) { + final int tmpHash = ObjectUtils.hashCode(object); + hash = hash * 31 + tmpHash; + } + } + return hash; + } + + // Identity ToString + //----------------------------------------------------------------------- + /** + *
Gets the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will return {@code null}.
+ * + *+ * ObjectUtils.identityToString(null) = null + * ObjectUtils.identityToString("") = "java.lang.String@1e23" + * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa" + *+ * + * @param object the object to create a toString for, may be + * {@code null} + * @return the default toString text, or {@code null} if + * {@code null} passed in + */ + public static String identityToString(final Object object) { + if (object == null) { + return null; + } + final StringBuilder builder = new StringBuilder(); + identityToString(builder, object); + return builder.toString(); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(appendable, "") = appendable.append("java.lang.String@1e23" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa") + *+ * + * @param appendable the appendable to append to + * @param object the object to create a toString for + * @throws IOException if an I/O error occurs + * @since 3.2 + */ + public static void identityToString(final Appendable appendable, final Object object) throws IOException { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + appendable.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StrBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(buf, "") = buf.append("java.lang.String@1e23" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa") + *+ * + * @param buffer the buffer to append to + * @param object the object to create a toString for + * @since 2.4 + */ + public static void identityToString(final StringBuffer buffer, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + buffer.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StringBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + // ToString + //----------------------------------------------------------------------- + /** + *
Gets the {@code toString} of an {@code Object} returning + * an empty string ("") if {@code null} input.
+ * + *+ * ObjectUtils.toString(null) = "" + * ObjectUtils.toString("") = "" + * ObjectUtils.toString("bat") = "bat" + * ObjectUtils.toString(Boolean.TRUE) = "true" + *+ * + * @see StringUtils#defaultString(String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @return the passed in Object's toString, or {@code ""} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object)} in Java 7 and will be + * removed in future releases. Note however that said method will return "null" for null references, while this + * method returns and empty String. To preserve behavior use {@code java.util.Objects.toString(myObject, "")} + */ + @Deprecated +// ToString +// ----------------------------------------------------------------------- +/** + *
Gets the {@code toString} of an {@code Object} returning + * an empty string ("") if {@code null} input.
+ * + *+ * ObjectUtils.toString(null) = "" + * ObjectUtils.toString("") = "" + * ObjectUtils.toString("bat") = "bat" + * ObjectUtils.toString(Boolean.TRUE) = "true" + *+ * + * @see StringUtils#defaultString(String) + * @see String#valueOf(Object) + * @param obj + * the Object to {@code toString}, may be null + * @return the passed in Object's toString, or {@code ""} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object)} in Java 7 and will be +removed in future releases. Note however that said method will return "null" for null references, while this +method returns and empty String. To preserve behavior use {@code java.util.Objects.toString(myObject, "")} + */ +public static java.lang.String toString(final java.lang.Object obj) { + return /* NPEX_NULL_EXP */ + obj.toString(); +} + + /** + *
Gets the {@code toString} of an {@code Object} returning + * a specified text if {@code null} input.
+ * + *+ * ObjectUtils.toString(null, null) = null + * ObjectUtils.toString(null, "null") = "null" + * ObjectUtils.toString("", "null") = "" + * ObjectUtils.toString("bat", "null") = "bat" + * ObjectUtils.toString(Boolean.TRUE, "null") = "true" + *+ * + * @see StringUtils#defaultString(String,String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @param nullStr the String to return if {@code null} input, may be null + * @return the passed in Object's toString, or {@code nullStr} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object, String)} in Java 7 and + * will be removed in future releases. + */ + @Deprecated + public static String toString(final Object obj, final String nullStr) { + return obj == null ? nullStr : obj.toString(); + } + + // Comparable + //----------------------------------------------------------------------- + /** + *
Null safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables. + * {@code null} is assumed to be less than a non-{@code null} value.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramClone an object.
+ * + * @paramClone an object if possible.
+ * + *This method is similar to {@link #clone(Object)}, but will return the provided + * instance as the return value instead of {@code null} if the instance + * is not cloneable. This is more convenient if the caller uses different + * implementations (e.g. of a service) and some of the implementations do not allow concurrent + * processing or have state. In such cases the implementation can simply provide a proper + * clone implementation and the caller's code does not have to change.
+ * + * @paramClass used as a null placeholder where {@code null} + * has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there is + * no matching key. The {@code Null} placeholder can be used to distinguish + * between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ */ + public static class Null implements Serializable { + /** + * Required for serialization support. Declare serialization compatibility with Commons Lang 1.0 + * + * @see java.io.Serializable + */ + private static final long serialVersionUID = 7092611880189329093L; + + /** + * Restricted constructor - singleton. + */ + Null() { + super(); + } + + /** + *Ensure singleton.
+ * + * @return the singleton value + */ + private Object readResolve() { + return ObjectUtils.NULL; + } + } + + + // Constants (LANG-816): + /* + These methods ensure constants are not inlined by javac. + For example, typically a developer might declare a constant like so: + + public final static int MAGIC_NUMBER = 5; + + Should a different jar file refer to this, and the MAGIC_NUMBER + is changed a later date (e.g., MAGIC_NUMBER = 6), the different jar + file will need to recompile itself. This is because javac + typically inlines the primitive or String constant directly into + the bytecode, and removes the reference to the MAGIC_NUMBER field. + + To help the other jar (so that it does not need to recompile + when constants are changed) the original developer can declare + their constant using one of the CONST() utility methods, instead: + + public final static int MAGIC_NUMBER = CONST(5); + */ + + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *+ * public final static boolean MAGIC_FLAG = ObjectUtils.CONST(true); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the boolean value to return + * @return the boolean v, unchanged + * @since 3.2 + */ + public static boolean CONST(final boolean v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static byte MAGIC_BYTE = ObjectUtils.CONST((byte) 127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the byte value to return + * @return the byte v, unchanged + * @since 3.2 + */ + public static byte CONST(final byte v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static byte MAGIC_BYTE = ObjectUtils.CONST_BYTE(127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the byte literal (as an int) value to return + * @throws IllegalArgumentException if the value passed to v + * is larger than a byte, that is, smaller than -128 or + * larger than 127. + * @return the byte v, unchanged + * @since 3.2 + */ + public static byte CONST_BYTE(final int v) throws IllegalArgumentException { + if (v < Byte.MIN_VALUE || v > Byte.MAX_VALUE) { + throw new IllegalArgumentException("Supplied value must be a valid byte literal between -128 and 127: [" + v + "]"); + } + return (byte) v; + } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static char MAGIC_CHAR = ObjectUtils.CONST('a'); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the char value to return + * @return the char v, unchanged + * @since 3.2 + */ + public static char CONST(final char v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static short MAGIC_SHORT = ObjectUtils.CONST((short) 123); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the short value to return + * @return the short v, unchanged + * @since 3.2 + */ + public static short CONST(final short v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static short MAGIC_SHORT = ObjectUtils.CONST_SHORT(127); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the short literal (as an int) value to return + * @throws IllegalArgumentException if the value passed to v + * is larger than a short, that is, smaller than -32768 or + * larger than 32767. + * @return the byte v, unchanged + * @since 3.2 + */ + public static short CONST_SHORT(final int v) throws IllegalArgumentException { + if (v < Short.MIN_VALUE || v > Short.MAX_VALUE) { + throw new IllegalArgumentException("Supplied value must be a valid byte literal between -32768 and 32767: [" + v + "]"); + } + return (short) v; + } + + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static int MAGIC_INT = ObjectUtils.CONST(123); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the int value to return + * @return the int v, unchanged + * @since 3.2 + */ + public static int CONST(final int v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static long MAGIC_LONG = ObjectUtils.CONST(123L); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the long value to return + * @return the long v, unchanged + * @since 3.2 + */ + public static long CONST(final long v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static float MAGIC_FLOAT = ObjectUtils.CONST(1.0f); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the float value to return + * @return the float v, unchanged + * @since 3.2 + */ + public static float CONST(final float v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static double MAGIC_DOUBLE = ObjectUtils.CONST(1.0); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param v the double value to return + * @return the double v, unchanged + * @since 3.2 + */ + public static double CONST(final double v) { return v; } + + /** + * This method returns the provided value unchanged. + * This can prevent javac from inlining a constant + * field, e.g., + * + *
+ * public final static String MAGIC_STRING = ObjectUtils.CONST("abc"); + *+ * + * This way any jars that refer to this field do not + * have to recompile themselves if the field's value + * changes at some future date. + * + * @param
Operations on {@code Object}.
+ * + *This class tries to handle {@code null} input gracefully. + * An exception will generally not be thrown for a {@code null} input. + * Each method documents its behaviour in more detail.
+ * + *#ThreadSafe#
+ * @since 1.0 + */ +//@Immutable +public class ObjectUtils { + + /** + *Singleton used as a {@code null} placeholder where + * {@code null} has another meaning.
+ * + *For example, in a {@code HashMap} the + * {@link java.util.HashMap#get(java.lang.Object)} method returns + * {@code null} if the {@code Map} contains {@code null} or if there + * is no matching key. The {@code Null} placeholder can be used to + * distinguish between these two cases.
+ * + *Another example is {@code Hashtable}, where {@code null} + * cannot be stored.
+ * + *This instance is Serializable.
+ */ + public static final Null NULL = new Null(); + + /** + *{@code ObjectUtils} instances should NOT be constructed in + * standard programming. Instead, the static methods on the class should + * be used, such as {@code ObjectUtils.defaultIfNull("a","b");}.
+ * + *This constructor is public to permit tools that require a JavaBean + * instance to operate.
+ */ + public ObjectUtils() { + super(); + } + + // Defaulting + //----------------------------------------------------------------------- + /** + *Returns a default value if the object passed is {@code null}.
+ * + *+ * ObjectUtils.defaultIfNull(null, null) = null + * ObjectUtils.defaultIfNull(null, "") = "" + * ObjectUtils.defaultIfNull(null, "zz") = "zz" + * ObjectUtils.defaultIfNull("abc", *) = "abc" + * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE + *+ * + * @param
Returns the first value in the array which is not {@code null}. + * If all the values are {@code null} or the array is {@code null} + * or empty then {@code null} is returned.
+ * + *+ * ObjectUtils.firstNonNull(null, null) = null + * ObjectUtils.firstNonNull(null, "") = "" + * ObjectUtils.firstNonNull(null, null, "") = "" + * ObjectUtils.firstNonNull(null, "zz") = "zz" + * ObjectUtils.firstNonNull("abc", *) = "abc" + * ObjectUtils.firstNonNull(null, "xyz", *) = "xyz" + * ObjectUtils.firstNonNull(Boolean.TRUE, *) = Boolean.TRUE + * ObjectUtils.firstNonNull() = null + *+ * + * @param
+ * If all the values are {@code null} or the array is {@code null} + * or empty then {@code false} is returned. Otherwise {@code true} is returned. + *
+ * + *+ * ObjectUtils.anyNotNull(*) = true + * ObjectUtils.anyNotNull(*, null) = true + * ObjectUtils.anyNotNull(null, *) = true + * ObjectUtils.anyNotNull(null, null, *, *) = true + * ObjectUtils.anyNotNull(null) = false + * ObjectUtils.anyNotNull(null, null) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code true} if there is at least one non-null value in the array, + * {@code false} if all values in the array are {@code null}s. + * If the array is {@code null} or empty {@code false} is also returned. + * @since 3.5 + */ + public static boolean anyNotNull(final Object... values) { + return firstNonNull(values) != null; + } + + /** + * Checks if all values in the array are not {@code nulls}. + * + *
+ * If any value is {@code null} or the array is {@code null} then + * {@code false} is returned. If all elements in array are not + * {@code null} or the array is empty (contains no elements) {@code true} + * is returned. + *
+ * + *+ * ObjectUtils.allNotNull(*) = true + * ObjectUtils.allNotNull(*, *) = true + * ObjectUtils.allNotNull(null) = false + * ObjectUtils.allNotNull(null, null) = false + * ObjectUtils.allNotNull(null, *) = false + * ObjectUtils.allNotNull(*, null) = false + * ObjectUtils.allNotNull(*, *, null, *) = false + *+ * + * @param values the values to test, may be {@code null} or empty + * @return {@code false} if there is at least one {@code null} value in the array or the array is {@code null}, + * {@code true} if all values in the array are not {@code null}s or array contains no elements. + * @since 3.5 + */ + public static boolean allNotNull(final Object... values) { + if (values == null) { + return false; + } + + for (final Object val : values) { + if (val == null) { + return false; + } + } + + return true; + } + + // Null-safe equals/hashCode + //----------------------------------------------------------------------- + /** + *
Compares two objects for equality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.equals(null, null) = true + * ObjectUtils.equals(null, "") = false + * ObjectUtils.equals("", null) = false + * ObjectUtils.equals("", "") = true + * ObjectUtils.equals(Boolean.TRUE, null) = false + * ObjectUtils.equals(Boolean.TRUE, "true") = false + * ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE) = true + * ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code true} if the values of both objects are the same + * @deprecated this method has been replaced by {@code java.util.Objects.equals(Object, Object)} in Java 7 and will + * be removed from future releases. + */ + @Deprecated + public static boolean equals(final Object object1, final Object object2) { + if (object1 == object2) { + return true; + } + if (object1 == null || object2 == null) { + return false; + } + return object1.equals(object2); + } + + /** + *
Compares two objects for inequality, where either one or both + * objects may be {@code null}.
+ * + *+ * ObjectUtils.notEqual(null, null) = false + * ObjectUtils.notEqual(null, "") = true + * ObjectUtils.notEqual("", null) = true + * ObjectUtils.notEqual("", "") = false + * ObjectUtils.notEqual(Boolean.TRUE, null) = true + * ObjectUtils.notEqual(Boolean.TRUE, "true") = true + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.TRUE) = false + * ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true + *+ * + * @param object1 the first object, may be {@code null} + * @param object2 the second object, may be {@code null} + * @return {@code false} if the values of both objects are the same + */ + public static boolean notEqual(final Object object1, final Object object2) { + return ObjectUtils.equals(object1, object2) == false; + } + + /** + *
Gets the hash code of an object returning zero when the + * object is {@code null}.
+ * + *+ * ObjectUtils.hashCode(null) = 0 + * ObjectUtils.hashCode(obj) = obj.hashCode() + *+ * + * @param obj the object to obtain the hash code of, may be {@code null} + * @return the hash code of the object, or zero if null + * @since 2.1 + * @deprecated this method has been replaced by {@code java.util.Objects.hashCode(Object)} in Java 7 and will be + * removed in future releases + */ + @Deprecated + public static int hashCode(final Object obj) { + // hashCode(Object) retained for performance, as hash code is often critical + return obj == null ? 0 : obj.hashCode(); + } + + /** + *
Gets the hash code for multiple objects.
+ * + *This allows a hash code to be rapidly calculated for a number of objects. + * The hash code for a single object is the not same as {@link #hashCode(Object)}. + * The hash code for multiple objects is the same as that calculated by an + * {@code ArrayList} containing the specified objects.
+ * + *+ * ObjectUtils.hashCodeMulti() = 1 + * ObjectUtils.hashCodeMulti((Object[]) null) = 1 + * ObjectUtils.hashCodeMulti(a) = 31 + a.hashCode() + * ObjectUtils.hashCodeMulti(a,b) = (31 + a.hashCode()) * 31 + b.hashCode() + * ObjectUtils.hashCodeMulti(a,b,c) = ((31 + a.hashCode()) * 31 + b.hashCode()) * 31 + c.hashCode() + *+ * + * @param objects the objects to obtain the hash code of, may be {@code null} + * @return the hash code of the objects, or zero if null + * @since 3.0 + * @deprecated this method has been replaced by {@code java.util.Objects.hash(Object...)} in Java 7 and will be + * removed in future releases. + */ + @Deprecated + public static int hashCodeMulti(final Object... objects) { + int hash = 1; + if (objects != null) { + for (final Object object : objects) { + final int tmpHash = ObjectUtils.hashCode(object); + hash = hash * 31 + tmpHash; + } + } + return hash; + } + + // Identity ToString + //----------------------------------------------------------------------- + /** + *
Gets the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will return {@code null}.
+ * + *+ * ObjectUtils.identityToString(null) = null + * ObjectUtils.identityToString("") = "java.lang.String@1e23" + * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa" + *+ * + * @param object the object to create a toString for, may be + * {@code null} + * @return the default toString text, or {@code null} if + * {@code null} passed in + */ + public static String identityToString(final Object object) { + if (object == null) { + return null; + } + final StringBuilder builder = new StringBuilder(); + identityToString(builder, object); + return builder.toString(); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(appendable, "") = appendable.append("java.lang.String@1e23" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(appendable, Boolean.TRUE) = appendable.append("java.lang.Boolean@7fa") + *+ * + * @param appendable the appendable to append to + * @param object the object to create a toString for + * @throws IOException if an I/O error occurs + * @since 3.2 + */ + public static void identityToString(final Appendable appendable, final Object object) throws IOException { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + appendable.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StrBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(buf, "") = buf.append("java.lang.String@1e23" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa") + *+ * + * @param buffer the buffer to append to + * @param object the object to create a toString for + * @since 2.4 + */ + public static void identityToString(final StringBuffer buffer, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + buffer.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + /** + *
Appends the toString that would be produced by {@code Object} + * if a class did not override toString itself. {@code null} + * will throw a NullPointerException for either of the two parameters.
+ * + *+ * ObjectUtils.identityToString(builder, "") = builder.append("java.lang.String@1e23" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa" + * ObjectUtils.identityToString(builder, Boolean.TRUE) = builder.append("java.lang.Boolean@7fa") + *+ * + * @param builder the builder to append to + * @param object the object to create a toString for + * @since 3.2 + */ + public static void identityToString(final StringBuilder builder, final Object object) { + if (object == null) { + throw new NullPointerException("Cannot get the toString of a null identity"); + } + builder.append(object.getClass().getName()) + .append('@') + .append(Integer.toHexString(System.identityHashCode(object))); + } + + // ToString + //----------------------------------------------------------------------- + /** + *
Gets the {@code toString} of an {@code Object} returning + * an empty string ("") if {@code null} input.
+ * + *+ * ObjectUtils.toString(null) = "" + * ObjectUtils.toString("") = "" + * ObjectUtils.toString("bat") = "bat" + * ObjectUtils.toString(Boolean.TRUE) = "true" + *+ * + * @see StringUtils#defaultString(String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @return the passed in Object's toString, or {@code ""} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object)} in Java 7 and will be + * removed in future releases. Note however that said method will return "null" for null references, while this + * method returns and empty String. To preserve behavior use {@code java.util.Objects.toString(myObject, "")} + */ + @Deprecated + public static String toString(final Object obj) { + return obj == null ? StringUtils.EMPTY : obj.toString(); + } + + /** + *
Gets the {@code toString} of an {@code Object} returning + * a specified text if {@code null} input.
+ * + *+ * ObjectUtils.toString(null, null) = null + * ObjectUtils.toString(null, "null") = "null" + * ObjectUtils.toString("", "null") = "" + * ObjectUtils.toString("bat", "null") = "bat" + * ObjectUtils.toString(Boolean.TRUE, "null") = "true" + *+ * + * @see StringUtils#defaultString(String,String) + * @see String#valueOf(Object) + * @param obj the Object to {@code toString}, may be null + * @param nullStr the String to return if {@code null} input, may be null + * @return the passed in Object's toString, or {@code nullStr} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object, String)} in Java 7 and + * will be removed in future releases. + */ + @Deprecated +/** + *
Gets the {@code toString} of an {@code Object} returning + * a specified text if {@code null} input.
+ * + *+ * ObjectUtils.toString(null, null) = null + * ObjectUtils.toString(null, "null") = "null" + * ObjectUtils.toString("", "null") = "" + * ObjectUtils.toString("bat", "null") = "bat" + * ObjectUtils.toString(Boolean.TRUE, "null") = "true" + *+ * + * @see StringUtils#defaultString(String,String) + * @see String#valueOf(Object) + * @param obj + * the Object to {@code toString}, may be null + * @param nullStr + * the String to return if {@code null} input, may be null + * @return the passed in Object's toString, or {@code nullStr} if {@code null} input + * @since 2.0 + * @deprecated this method has been replaced by {@code java.util.Objects.toString(Object, String)} in Java 7 and +will be removed in future releases. + */ +public static java.lang.String toString(final java.lang.Object obj, final java.lang.String nullStr) { + return /* NPEX_NULL_EXP */ + obj.toString(); +} + + // Comparable + //----------------------------------------------------------------------- + /** + *
Null safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramNull safe comparison of Comparables. + * {@code null} is assumed to be less than a non-{@code null} value.
+ * + * @paramNull safe comparison of Comparables.
+ * + * @paramClone an object.
+ * + * @paramClone an object if possible.
+ * + *This method is similar to {@link #clone(Object)}, but will return the provided + * instance as the return value instead of {@code null} if the instance + * is not cloneable. This is more convenient if the caller uses different + * implementations (e.g. of a service) and some of the implementations do not allow concurrent + * processing or have state. In such cases the implementation can simply provide a proper + * clone implementation and the caller's code does not have to change.
+ * + * @param