Javadoc
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/lang/trunk@1077992 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Stephen Colebourne
parent
c21a7a26c0
commit
81b5d12e81
|
|
@ -24,10 +24,10 @@ import java.lang.reflect.Method;
|
|||
import org.apache.commons.lang3.exception.CloneFailedException;
|
||||
|
||||
/**
|
||||
* <p>Operations on <code>Object</code>.</p>
|
||||
* <p>Operations on {@code Object}.</p>
|
||||
*
|
||||
* <p>This class tries to handle <code>null</code> input gracefully.
|
||||
* An exception will generally not be thrown for a <code>null</code> input.
|
||||
* <p>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.</p>
|
||||
*
|
||||
* <p>#ThreadSafe#</p>
|
||||
|
|
@ -45,17 +45,16 @@ import org.apache.commons.lang3.exception.CloneFailedException;
|
|||
public class ObjectUtils {
|
||||
|
||||
/**
|
||||
* <p>Singleton used as a <code>null</code> placeholder where
|
||||
* <code>null</code> has another meaning.</p>
|
||||
* <p>Singleton used as a {@code null} placeholder where
|
||||
* {@code null} has another meaning.</p>
|
||||
*
|
||||
* <p>For example, in a <code>HashMap</code> the
|
||||
* <p>For example, in a {@code HashMap} the
|
||||
* {@link java.util.HashMap#get(java.lang.Object)} method returns
|
||||
* <code>null</code> if the <code>Map</code> contains
|
||||
* <code>null</code> or if there is no matching key. The
|
||||
* <code>Null</code> placeholder can be used to distinguish between
|
||||
* these two cases.</p>
|
||||
* {@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.</p>
|
||||
*
|
||||
* <p>Another example is <code>Hashtable</code>, where <code>null</code>
|
||||
* <p>Another example is {@code Hashtable}, where {@code null}
|
||||
* cannot be stored.</p>
|
||||
*
|
||||
* <p>This instance is Serializable.</p>
|
||||
|
|
@ -63,12 +62,12 @@ public class ObjectUtils {
|
|||
public static final Null NULL = new Null();
|
||||
|
||||
/**
|
||||
* <p><code>ObjectUtils</code> instances should NOT be constructed in
|
||||
* standard programming. Instead, the class should be used as
|
||||
* <code>ObjectUtils.defaultIfNull("a","b");</code>.</p>
|
||||
* <p>{@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");}.</p>
|
||||
*
|
||||
* <p>This constructor is public to permit tools that require a JavaBean instance
|
||||
* to operate.</p>
|
||||
* <p>This constructor is public to permit tools that require a JavaBean
|
||||
* instance to operate.</p>
|
||||
*/
|
||||
public ObjectUtils() {
|
||||
super();
|
||||
|
|
@ -77,8 +76,7 @@ public class ObjectUtils {
|
|||
// Defaulting
|
||||
//-----------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Returns a default value if the object passed is
|
||||
* <code>null</code>.</p>
|
||||
* <p>Returns a default value if the object passed is {@code null}.</p>
|
||||
*
|
||||
* <pre>
|
||||
* ObjectUtils.defaultIfNull(null, null) = null
|
||||
|
|
@ -88,18 +86,18 @@ public class ObjectUtils {
|
|||
* ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE
|
||||
* </pre>
|
||||
*
|
||||
* @param object the <code>Object</code> to test, may be <code>null</code>
|
||||
* @param defaultValue the default value to return, may be <code>null</code>
|
||||
* @return <code>object</code> if it is not <code>null</code>, defaultValue otherwise
|
||||
* @param object the {@code Object} to test, may be {@code null}
|
||||
* @param defaultValue the default value to return, may be {@code null}
|
||||
* @return {@code object} if it is not {@code null}, defaultValue otherwise
|
||||
*/
|
||||
public static <T> T defaultIfNull(T object, T defaultValue) {
|
||||
return object != null ? object : defaultValue;
|
||||
}
|
||||
|
||||
/**
|
||||
* <p>Returns the first value in the array which is not <code>null</code>.
|
||||
* If all the values are <code>null</code> or the array is <code>null</code>
|
||||
* or empty then <code>null</code> is returned.</p>
|
||||
* <p>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.</p>
|
||||
*
|
||||
* <pre>
|
||||
* ObjectUtils.firstNonNull(null, null) = null
|
||||
|
|
@ -112,9 +110,9 @@ public class ObjectUtils {
|
|||
* ObjectUtils.firstNonNull() = null
|
||||
* </pre>
|
||||
*
|
||||
* @param values the values to test, may be <code>null</code> or empty
|
||||
* @return the first value from <code>values</code> which is not <code>null</code>,
|
||||
* or <code>null</code> if there are no non-null values
|
||||
* @param values the values to test, may be {@code null} or empty
|
||||
* @return the first value from {@code values} which is not {@code null},
|
||||
* or {@code null} if there are no non-null values
|
||||
*/
|
||||
public static <T> T firstNonNull(T... values) {
|
||||
if (values != null) {
|
||||
|
|
@ -131,7 +129,7 @@ public class ObjectUtils {
|
|||
//-----------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Compares two objects for equality, where either one or both
|
||||
* objects may be <code>null</code>.</p>
|
||||
* objects may be {@code null}.</p>
|
||||
*
|
||||
* <pre>
|
||||
* ObjectUtils.equals(null, null) = true
|
||||
|
|
@ -144,9 +142,9 @@ public class ObjectUtils {
|
|||
* ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false
|
||||
* </pre>
|
||||
*
|
||||
* @param object1 the first object, may be <code>null</code>
|
||||
* @param object2 the second object, may be <code>null</code>
|
||||
* @return <code>true</code> if the values of both objects are the same
|
||||
* @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
|
||||
*/
|
||||
public static boolean equals(Object object1, Object object2) {
|
||||
if (object1 == object2) {
|
||||
|
|
@ -160,7 +158,7 @@ public class ObjectUtils {
|
|||
|
||||
/**
|
||||
* <p>Compares two objects for inequality, where either one or both
|
||||
* objects may be <code>null</code>.</p>
|
||||
* objects may be {@code null}.</p>
|
||||
*
|
||||
* <pre>
|
||||
* ObjectUtils.notEqual(null, null) = false
|
||||
|
|
@ -173,9 +171,9 @@ public class ObjectUtils {
|
|||
* ObjectUtils.notEqual(Boolean.TRUE, Boolean.FALSE) = true
|
||||
* </pre>
|
||||
*
|
||||
* @param object1 the first object, may be <code>null</code>
|
||||
* @param object2 the second object, may be <code>null</code>
|
||||
* @return <code>false</code> if the values of both objects are the same
|
||||
* @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(Object object1, Object object2) {
|
||||
return ObjectUtils.equals(object1, object2) == false;
|
||||
|
|
@ -183,14 +181,14 @@ public class ObjectUtils {
|
|||
|
||||
/**
|
||||
* <p>Gets the hash code of an object returning zero when the
|
||||
* object is <code>null</code>.</p>
|
||||
* object is {@code null}.</p>
|
||||
*
|
||||
* <pre>
|
||||
* ObjectUtils.hashCode(null) = 0
|
||||
* ObjectUtils.hashCode(obj) = obj.hashCode()
|
||||
* </pre>
|
||||
*
|
||||
* @param obj the object to obtain the hash code of, may be <code>null</code>
|
||||
* @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
|
||||
*/
|
||||
|
|
@ -201,9 +199,9 @@ public class ObjectUtils {
|
|||
// Identity ToString
|
||||
//-----------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Gets the toString that would be produced by <code>Object</code>
|
||||
* if a class did not override toString itself. <code>null</code>
|
||||
* will return <code>null</code>.</p>
|
||||
* <p>Gets the toString that would be produced by {@code Object}
|
||||
* if a class did not override toString itself. {@code null}
|
||||
* will return {@code null}.</p>
|
||||
*
|
||||
* <pre>
|
||||
* ObjectUtils.identityToString(null) = null
|
||||
|
|
@ -212,9 +210,9 @@ public class ObjectUtils {
|
|||
* </pre>
|
||||
*
|
||||
* @param object the object to create a toString for, may be
|
||||
* <code>null</code>
|
||||
* @return the default toString text, or <code>null</code> if
|
||||
* <code>null</code> passed in
|
||||
* {@code null}
|
||||
* @return the default toString text, or {@code null} if
|
||||
* {@code null} passed in
|
||||
*/
|
||||
public static String identityToString(Object object) {
|
||||
if (object == null) {
|
||||
|
|
@ -226,8 +224,8 @@ public class ObjectUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Appends the toString that would be produced by <code>Object</code>
|
||||
* if a class did not override toString itself. <code>null</code>
|
||||
* <p>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. </p>
|
||||
*
|
||||
* <pre>
|
||||
|
|
@ -252,8 +250,8 @@ public class ObjectUtils {
|
|||
// ToString
|
||||
//-----------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Gets the <code>toString</code> of an <code>Object</code> returning
|
||||
* an empty string ("") if <code>null</code> input.</p>
|
||||
* <p>Gets the {@code toString} of an {@code Object} returning
|
||||
* an empty string ("") if {@code null} input.</p>
|
||||
*
|
||||
* <pre>
|
||||
* ObjectUtils.toString(null) = ""
|
||||
|
|
@ -264,8 +262,8 @@ public class ObjectUtils {
|
|||
*
|
||||
* @see StringUtils#defaultString(String)
|
||||
* @see String#valueOf(Object)
|
||||
* @param obj the Object to <code>toString</code>, may be null
|
||||
* @return the passed in Object's toString, or nullStr if <code>null</code> input
|
||||
* @param obj the Object to {@code toString}, may be null
|
||||
* @return the passed in Object's toString, or nullStr if {@code null} input
|
||||
* @since 2.0
|
||||
*/
|
||||
public static String toString(Object obj) {
|
||||
|
|
@ -273,8 +271,8 @@ public class ObjectUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Gets the <code>toString</code> of an <code>Object</code> returning
|
||||
* a specified text if <code>null</code> input.</p>
|
||||
* <p>Gets the {@code toString} of an {@code Object} returning
|
||||
* a specified text if {@code null} input.</p>
|
||||
*
|
||||
* <pre>
|
||||
* ObjectUtils.toString(null, null) = null
|
||||
|
|
@ -286,9 +284,9 @@ public class ObjectUtils {
|
|||
*
|
||||
* @see StringUtils#defaultString(String,String)
|
||||
* @see String#valueOf(Object)
|
||||
* @param obj the Object to <code>toString</code>, may be null
|
||||
* @param nullStr the String to return if <code>null</code> input, may be null
|
||||
* @return the passed in Object's toString, or nullStr if <code>null</code> input
|
||||
* @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 nullStr if {@code null} input
|
||||
* @since 2.0
|
||||
*/
|
||||
public static String toString(Object obj, String nullStr) {
|
||||
|
|
@ -298,14 +296,14 @@ public class ObjectUtils {
|
|||
// Min/Max
|
||||
//-----------------------------------------------------------------------
|
||||
/**
|
||||
* Null safe comparison of Comparables.
|
||||
* <p>Null safe comparison of Comparables.</p>
|
||||
*
|
||||
* @param values the set of comparable values, may be null
|
||||
* @return
|
||||
* <ul>
|
||||
* <li>If any objects are non-null and unequal, the lesser object.
|
||||
* <li>If all objects are non-null and equal, the first.
|
||||
* <li>If any of the comparables are null, the lesser of the non-null object.
|
||||
* <li>If any of the comparables are null, the lesser of the non-null objects.
|
||||
* <li>If all the comparables are null, null is returned.
|
||||
* </ul>
|
||||
*/
|
||||
|
|
@ -322,14 +320,14 @@ public class ObjectUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* Null safe comparison of Comparables.
|
||||
* <p>Null safe comparison of Comparables.</p>
|
||||
*
|
||||
* @param values the set of comparable values, may be null
|
||||
* @return
|
||||
* <ul>
|
||||
* <li>If any objects are non-null and unequal, the greater object.
|
||||
* <li>If all objects are non-null and equal, the first.
|
||||
* <li>If any of the comparables are null, the greater of the non-null object.
|
||||
* <li>If any of the comparables are null, the greater of the non-null objects.
|
||||
* <li>If all the comparables are null, null is returned.
|
||||
* </ul>
|
||||
*/
|
||||
|
|
@ -346,28 +344,28 @@ public class ObjectUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* Null safe comparison of Comparables.
|
||||
* {@code null} is assumed to be less than a non-{@code null} value.
|
||||
* <p>Null safe comparison of Comparables.
|
||||
* {@code null} is assumed to be less than a non-{@code null} value.</p>
|
||||
*
|
||||
* @param c1 the first comparable, may be null
|
||||
* @param c2 the second comparable, may be null
|
||||
* @return a negative value if c1 < c2, zero if c1 = c2
|
||||
* and a positive value if c1 > c2
|
||||
* and a positive value if c1 > c2
|
||||
*/
|
||||
public static <T extends Comparable<? super T>> int compare(T c1, T c2) {
|
||||
return compare(c1, c2, false);
|
||||
}
|
||||
|
||||
/**
|
||||
* Null safe comparison of Comparables.
|
||||
* <p>Null safe comparison of Comparables.</p>
|
||||
*
|
||||
* @param c1 the first comparable, may be null
|
||||
* @param c2 the second comparable, may be null
|
||||
* @param nullGreater if true <code>null</code> is considered greater
|
||||
* than a Non-<code>null</code> value or if false <code>null</code> is
|
||||
* considered less than a Non-<code>null</code> value
|
||||
* @param nullGreater if true {@code null} is considered greater
|
||||
* than a non-{@code null} value or if false {@code null} is
|
||||
* considered less than a Non-{@code null} value
|
||||
* @return a negative value if c1 < c2, zero if c1 = c2
|
||||
* and a positive value if c1 > c2
|
||||
* and a positive value if c1 > c2
|
||||
* @see java.util.Comparator#compare(Object, Object)
|
||||
*/
|
||||
public static <T extends Comparable<? super T>> int compare(T c1, T c2, boolean nullGreater) {
|
||||
|
|
@ -382,42 +380,42 @@ public class ObjectUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* Clone an object.
|
||||
* <p>Clone an object.</p>
|
||||
*
|
||||
* @param <T> the type of the object
|
||||
* @param o the object to clone
|
||||
* @return the clone if the object implements {@link Cloneable} otherwise <code>null</code>
|
||||
* @param obj the object to clone, null returns null
|
||||
* @return the clone if the object implements {@link Cloneable} otherwise {@code null}
|
||||
* @throws CloneFailedException if the object is cloneable and the clone operation fails
|
||||
* @since 3.0
|
||||
*/
|
||||
public static <T> T clone(final T o) {
|
||||
if (o instanceof Cloneable) {
|
||||
public static <T> T clone(final T obj) {
|
||||
if (obj instanceof Cloneable) {
|
||||
final Object result;
|
||||
if (o.getClass().isArray()) {
|
||||
final Class<?> componentType = o.getClass().getComponentType();
|
||||
if (obj.getClass().isArray()) {
|
||||
final Class<?> componentType = obj.getClass().getComponentType();
|
||||
if (!componentType.isPrimitive()) {
|
||||
result = ((Object[]) o).clone();
|
||||
result = ((Object[]) obj).clone();
|
||||
} else {
|
||||
int length = Array.getLength(o);
|
||||
int length = Array.getLength(obj);
|
||||
result = Array.newInstance(componentType, length);
|
||||
while (length-- > 0) {
|
||||
Array.set(result, length, Array.get(o, length));
|
||||
Array.set(result, length, Array.get(obj, length));
|
||||
}
|
||||
}
|
||||
} else {
|
||||
try {
|
||||
final Method clone = o.getClass().getMethod("clone");
|
||||
result = clone.invoke(o);
|
||||
final Method clone = obj.getClass().getMethod("clone");
|
||||
result = clone.invoke(obj);
|
||||
} catch (final NoSuchMethodException e) {
|
||||
throw new CloneFailedException("Cloneable type "
|
||||
+ o.getClass().getName()
|
||||
+ obj.getClass().getName()
|
||||
+ " has no clone method", e);
|
||||
} catch (final IllegalAccessException e) {
|
||||
throw new CloneFailedException("Cannot clone Cloneable type "
|
||||
+ o.getClass().getName(), e);
|
||||
+ obj.getClass().getName(), e);
|
||||
} catch (final InvocationTargetException e) {
|
||||
throw new CloneFailedException("Exception cloning Cloneable type "
|
||||
+ o.getClass().getName(), e.getCause());
|
||||
+ obj.getClass().getName(), e.getCause());
|
||||
}
|
||||
}
|
||||
@SuppressWarnings("unchecked")
|
||||
|
|
@ -429,38 +427,39 @@ public class ObjectUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* Clone 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</code> if the instance
|
||||
* <p>Clone an object if possible.</p>
|
||||
*
|
||||
* <p>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.
|
||||
* clone implementation and the caller's code does not have to change.</p>
|
||||
*
|
||||
* @param <T> the type of the object
|
||||
* @param o the object to clone
|
||||
* @param obj the object to clone, null returns null
|
||||
* @return the clone if the object implements {@link Cloneable} otherwise the object itself
|
||||
* @throws CloneFailedException if the object is cloneable and the clone operation fails
|
||||
* @since 3.0
|
||||
*/
|
||||
public static <T> T cloneIfPossible(final T o) {
|
||||
final T clone = clone(o);
|
||||
return clone == null ? o : clone;
|
||||
public static <T> T cloneIfPossible(final T obj) {
|
||||
final T clone = clone(obj);
|
||||
return clone == null ? obj : clone;
|
||||
}
|
||||
|
||||
// Null
|
||||
//-----------------------------------------------------------------------
|
||||
/**
|
||||
* <p>Class used as a null placeholder where <code>null</code>
|
||||
* <p>Class used as a null placeholder where {@code null}
|
||||
* has another meaning.</p>
|
||||
*
|
||||
* <p>For example, in a <code>HashMap</code> the
|
||||
* <p>For example, in a {@code HashMap} the
|
||||
* {@link java.util.HashMap#get(java.lang.Object)} method returns
|
||||
* <code>null</code> if the <code>Map</code> contains
|
||||
* <code>null</code> or if there is no matching key. The
|
||||
* <code>Null</code> placeholder can be used to distinguish between
|
||||
* these two cases.</p>
|
||||
* {@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.</p>
|
||||
*
|
||||
* <p>Another example is <code>Hashtable</code>, where <code>null</code>
|
||||
* <p>Another example is {@code Hashtable}, where {@code null}
|
||||
* cannot be stored.</p>
|
||||
*/
|
||||
public static class Null implements Serializable {
|
||||
|
|
|
|||
Loading…
Reference in New Issue