- /* ====================================================================
- * The Apache Software License, Version 1.1
- *
- * Copyright (c) 2002-2003 The Apache Software Foundation. All rights
- * reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * 1. Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *
- * 2. Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in
- * the documentation and/or other materials provided with the
- * distribution.
- *
- * 3. The end-user documentation included with the redistribution, if
- * any, must include the following acknowledgement:
- * "This product includes software developed by the
- * Apache Software Foundation (http://www.apache.org/)."
- * Alternately, this acknowledgement may appear in the software itself,
- * if and wherever such third-party acknowledgements normally appear.
- *
- * 4. The names "The Jakarta Project", "Commons", and "Apache Software
- * Foundation" must not be used to endorse or promote products derived
- * from this software without prior written permission. For written
- * permission, please contact apache@apache.org.
- *
- * 5. Products derived from this software may not be called "Apache"
- * nor may "Apache" appear in their names without prior written
- * permission of the Apache Software Foundation.
- *
- * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
- * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
- * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
- * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
- * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
- * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
- * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- * SUCH DAMAGE.
- * ====================================================================
- *
- * This software consists of voluntary contributions made by many
- * individuals on behalf of the Apache Software Foundation. For more
- * information on the Apache Software Foundation, please see
- * <http://www.apache.org/>.
- */
- package org.apache.commons.lang;
-
- import java.io.Serializable;
-
- /**
- * <p>Operations on <code>Object</code>.</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.
- * Each method documents its behaviour in more detail.</p>
- *
- * @author <a href="mailto:nissim@nksystems.com">Nissim Karpenstein</a>
- * @author <a href="mailto:janekdb@yahoo.co.uk">Janek Bogucki</a>
- * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
- * @author Stephen Colebourne
- * @author Gary Gregory
- * @since 1.0
- * @version $Id: ObjectUtils.java,v 1.21 2003/08/22 17:25:33 ggregory Exp $
- */
- public class ObjectUtils {
-
- /**
- * <p>Singleton used as a <code>null</code> placeholder where
- * <code>null</code> has another meaning.</p>
- *
- * <p>For example, in a <code>HashMap</code> 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>
- *
- * <p>Another example is <code>Hashtable</code>, where <code>null</code>
- * cannot be stored.</p>
- *
- * <p>This instance is Serializable.</p>
- */
- 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>This constructor is public to permit tools that require a JavaBean instance
- * to operate.</p>
- */
- public ObjectUtils() {
- }
-
- // Defaulting
- //-----------------------------------------------------------------------
- /**
- * <p>Returns a default value if the object passed is
- * <code>null</code>.</p>
- *
- * <pre>
- * ObjectUtils.defaultIfNull(null, null) = null
- * ObjectUtils.defaultIfNull(null, "") = ""
- * ObjectUtils.defaultIfNull(null, "zz") = "zz"
- * ObjectUtils.defaultIfNull("abc", *) = "abc"
- * 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
- */
- public static Object defaultIfNull(Object object, Object defaultValue) {
- return (object != null ? object : defaultValue);
- }
-
- /**
- * <p>Compares two objects for equality, where either one or both
- * objects may be <code>null</code>.</p>
- *
- * <pre>
- * 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
- * </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
- */
- public static boolean equals(Object object1, Object object2) {
- if (object1 == object2) {
- return true;
- }
- if ((object1 == null) || (object2 == null)) {
- return false;
- }
- return object1.equals(object2);
- }
-
- // 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>
- *
- * <pre>
- * ObjectUtils.identityToString(null) = null
- * ObjectUtils.identityToString("") = "java.lang.String@1e23"
- * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa"
- * </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
- */
- public static String identityToString(Object object) {
- if (object == null) {
- return null;
- }
- return appendIdentityToString(null, object).toString();
- }
-
- /**
- * <p>Appends 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>
- *
- * <pre>
- * ObjectUtils.appendIdentityToString(*, null) = null
- * ObjectUtils.appendIdentityToString(null, "") = "java.lang.String@1e23"
- * ObjectUtils.appendIdentityToString(null, Boolean.TRUE) = "java.lang.Boolean@7fa"
- * ObjectUtils.appendIdentityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa")
- * </pre>
- *
- * @param buffer the buffer to append to, may be <code>null</code>
- * @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
- * @since 2.0
- */
- public static StringBuffer appendIdentityToString(StringBuffer buffer, Object object) {
- if (object == null) {
- return null;
- }
- if (buffer == null) {
- buffer = new StringBuffer();
- }
- return buffer
- .append(object.getClass().getName())
- .append('@')
- .append(Integer.toHexString(System.identityHashCode(object)));
- }
-
- // ToString
- //-----------------------------------------------------------------------
- /**
- * <p>Gets the <code>toString</code> of an <code>Object</code> returning
- * an empty string ("") if <code>null</code> input.</p>
- *
- * <pre>
- * ObjectUtils.toString(null) = ""
- * ObjectUtils.toString("") = ""
- * ObjectUtils.toString("bat") = "bat"
- * ObjectUtils.toString(Boolean.TRUE) = "true"
- * </pre>
- *
- * @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
- * @since 2.0
- */
- public static String toString(Object obj) {
- return (obj == null ? "" : obj.toString());
- }
-
- /**
- * <p>Gets the <code>toString</code> of an <code>Object</code> returning
- * a specified text if <code>null</code> input.</p>
- *
- * <pre>
- * ObjectUtils.toString(null, null) = null
- * ObjectUtils.toString(null, "null") = "null"
- * ObjectUtils.toString("", "null") = ""
- * ObjectUtils.toString("bat", "null") = "bat"
- * ObjectUtils.toString(Boolean.TRUE, "null") = "true"
- * </pre>
- *
- * @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
- * @since 2.0
- */
- public static String toString(Object obj, String nullStr) {
- return (obj == null ? nullStr : obj.toString());
- }
-
- // Null
- //-----------------------------------------------------------------------
- /**
- * <p>Class used as a null placeholder where <code>null</code>
- * has another meaning.</p>
- *
- * <p>For example, in a <code>HashMap</code> 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>
- *
- * <p>Another example is <code>Hashtable</code>, where <code>null</code>
- * cannot be stored.</p>
- */
- public static class Null implements Serializable {
- // declare serialization compatability with Commons Lang 1.0
- private static final long serialVersionUID = 7092611880189329093L;
-
- /**
- * Restricted constructor - singleton.
- */
- Null() {
- }
-
- /**
- * <p>Ensure singleton.</p>
- *
- * @return the singleton value
- */
- private Object readResolve() {
- return ObjectUtils.NULL;
- }
- }
-
- }