Author: scolebourne
Date: Fri Mar 4 15:08:53 2011
New Revision: 1077992
URL: http://svn.apache.org/viewvc?rev=1077992&view=rev
Log:
Javadoc
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/ObjectUtils.java
Modified:
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/ObjectUtils.java
URL:
http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/ObjectUtils.java?rev=1077992&r1=1077991&r2=1077992&view=diff
==============================================================================
---
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/ObjectUtils.java
(original)
+++
commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/ObjectUtils.java
Fri Mar 4 15:08:53 2011
@@ -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.exceptio
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 {
