KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > lang > ObjectUtils


1 /*
2  * Copyright 2002-2005 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.lang;
17
18 import java.io.Serializable JavaDoc;
19
20 /**
21  * <p>Operations on <code>Object</code>.</p>
22  *
23  * <p>This class tries to handle <code>null</code> input gracefully.
24  * An exception will generally not be thrown for a <code>null</code> input.
25  * Each method documents its behaviour in more detail.</p>
26  *
27  * @author <a HREF="mailto:nissim@nksystems.com">Nissim Karpenstein</a>
28  * @author <a HREF="mailto:janekdb@yahoo.co.uk">Janek Bogucki</a>
29  * @author <a HREF="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
30  * @author Stephen Colebourne
31  * @author Gary Gregory
32  * @author Mario Winterer
33  * @since 1.0
34  * @version $Id: ObjectUtils.java 161243 2005-04-14 04:30:28Z ggregory $
35  */
36 public class ObjectUtils {
37     
38     /**
39      * <p>Singleton used as a <code>null</code> placeholder where
40      * <code>null</code> has another meaning.</p>
41      *
42      * <p>For example, in a <code>HashMap</code> the
43      * {@link java.util.HashMap#get(java.lang.Object)} method returns
44      * <code>null</code> if the <code>Map</code> contains
45      * <code>null</code> or if there is no matching key. The
46      * <code>Null</code> placeholder can be used to distinguish between
47      * these two cases.</p>
48      *
49      * <p>Another example is <code>Hashtable</code>, where <code>null</code>
50      * cannot be stored.</p>
51      *
52      * <p>This instance is Serializable.</p>
53      */
54     public static final Null NULL = new Null();
55     
56     /**
57      * <p><code>ObjectUtils</code> instances should NOT be constructed in
58      * standard programming. Instead, the class should be used as
59      * <code>ObjectUtils.defaultIfNull("a","b");</code>.</p>
60      *
61      * <p>This constructor is public to permit tools that require a JavaBean instance
62      * to operate.</p>
63      */
64     public ObjectUtils() {
65     }
66
67     // Defaulting
68 //-----------------------------------------------------------------------
69 /**
70      * <p>Returns a default value if the object passed is
71      * <code>null</code>.</p>
72      *
73      * <pre>
74      * ObjectUtils.defaultIfNull(null, null) = null
75      * ObjectUtils.defaultIfNull(null, "") = ""
76      * ObjectUtils.defaultIfNull(null, "zz") = "zz"
77      * ObjectUtils.defaultIfNull("abc", *) = "abc"
78      * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE
79      * </pre>
80      *
81      * @param object the <code>Object</code> to test, may be <code>null</code>
82      * @param defaultValue the default value to return, may be <code>null</code>
83      * @return <code>object</code> if it is not <code>null</code>, defaultValue otherwise
84      */
85     public static Object JavaDoc defaultIfNull(Object JavaDoc object, Object JavaDoc defaultValue) {
86         return object != null ? object : defaultValue;
87     }
88
89     /**
90      * <p>Compares two objects for equality, where either one or both
91      * objects may be <code>null</code>.</p>
92      *
93      * <pre>
94      * ObjectUtils.equals(null, null) = true
95      * ObjectUtils.equals(null, "") = false
96      * ObjectUtils.equals("", null) = false
97      * ObjectUtils.equals("", "") = true
98      * ObjectUtils.equals(Boolean.TRUE, null) = false
99      * ObjectUtils.equals(Boolean.TRUE, "true") = false
100      * ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE) = true
101      * ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false
102      * </pre>
103      *
104      * @param object1 the first object, may be <code>null</code>
105      * @param object2 the second object, may be <code>null</code>
106      * @return <code>true</code> if the values of both objects are the same
107      */
108     public static boolean equals(Object JavaDoc object1, Object JavaDoc object2) {
109         if (object1 == object2) {
110             return true;
111         }
112         if ((object1 == null) || (object2 == null)) {
113             return false;
114         }
115         return object1.equals(object2);
116     }
117
118     /**
119      * <p>Gets the hash code of an object returning zero when the
120      * object is <code>null</code>.</p>
121      *
122      * <pre>
123      * ObjectUtils.hashCode(null) = 0
124      * ObjectUtils.hashCode(obj) = obj.hashCode()
125      * </pre>
126      *
127      * @param obj the object to obtain the hash code of, may be <code>null</code>
128      * @return the hash code of the object, or zero if null
129      * @since 2.1
130      */
131     public static int hashCode(Object JavaDoc obj) {
132         return (obj == null) ? 0 : obj.hashCode();
133     }
134
135     // Identity ToString
136 //-----------------------------------------------------------------------
137 /**
138      * <p>Gets the toString that would be produced by <code>Object</code>
139      * if a class did not override toString itself. <code>null</code>
140      * will return <code>null</code>.</p>
141      *
142      * <pre>
143      * ObjectUtils.identityToString(null) = null
144      * ObjectUtils.identityToString("") = "java.lang.String@1e23"
145      * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa"
146      * </pre>
147      *
148      * @param object the object to create a toString for, may be
149      * <code>null</code>
150      * @return the default toString text, or <code>null</code> if
151      * <code>null</code> passed in
152      */
153     public static String JavaDoc identityToString(Object JavaDoc object) {
154         if (object == null) {
155             return null;
156         }
157         return appendIdentityToString(null, object).toString();
158     }
159
160     /**
161      * <p>Appends the toString that would be produced by <code>Object</code>
162      * if a class did not override toString itself. <code>null</code>
163      * will return <code>null</code>.</p>
164      *
165      * <pre>
166      * ObjectUtils.appendIdentityToString(*, null) = null
167      * ObjectUtils.appendIdentityToString(null, "") = "java.lang.String@1e23"
168      * ObjectUtils.appendIdentityToString(null, Boolean.TRUE) = "java.lang.Boolean@7fa"
169      * ObjectUtils.appendIdentityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa")
170      * </pre>
171      *
172      * @param buffer the buffer to append to, may be <code>null</code>
173      * @param object the object to create a toString for, may be <code>null</code>
174      * @return the default toString text, or <code>null</code> if
175      * <code>null</code> passed in
176      * @since 2.0
177      */
178     public static StringBuffer JavaDoc appendIdentityToString(StringBuffer JavaDoc buffer, Object JavaDoc object) {
179         if (object == null) {
180             return null;
181         }
182         if (buffer == null) {
183             buffer = new StringBuffer JavaDoc();
184         }
185         return buffer
186             .append(object.getClass().getName())
187             .append('@')
188             .append(Integer.toHexString(System.identityHashCode(object)));
189     }
190
191     // ToString
192 //-----------------------------------------------------------------------
193 /**
194      * <p>Gets the <code>toString</code> of an <code>Object</code> returning
195      * an empty string ("") if <code>null</code> input.</p>
196      *
197      * <pre>
198      * ObjectUtils.toString(null) = ""
199      * ObjectUtils.toString("") = ""
200      * ObjectUtils.toString("bat") = "bat"
201      * ObjectUtils.toString(Boolean.TRUE) = "true"
202      * </pre>
203      *
204      * @see StringUtils#defaultString(String)
205      * @see String#valueOf(Object)
206      * @param obj the Object to <code>toString</code>, may be null
207      * @return the passed in Object's toString, or nullStr if <code>null</code> input
208      * @since 2.0
209      */
210     public static String JavaDoc toString(Object JavaDoc obj) {
211         return obj == null ? "" : obj.toString();
212     }
213
214     /**
215      * <p>Gets the <code>toString</code> of an <code>Object</code> returning
216      * a specified text if <code>null</code> input.</p>
217      *
218      * <pre>
219      * ObjectUtils.toString(null, null) = null
220      * ObjectUtils.toString(null, "null") = "null"
221      * ObjectUtils.toString("", "null") = ""
222      * ObjectUtils.toString("bat", "null") = "bat"
223      * ObjectUtils.toString(Boolean.TRUE, "null") = "true"
224      * </pre>
225      *
226      * @see StringUtils#defaultString(String,String)
227      * @see String#valueOf(Object)
228      * @param obj the Object to <code>toString</code>, may be null
229      * @param nullStr the String to return if <code>null</code> input, may be null
230      * @return the passed in Object's toString, or nullStr if <code>null</code> input
231      * @since 2.0
232      */
233     public static String JavaDoc toString(Object JavaDoc obj, String JavaDoc nullStr) {
234         return obj == null ? nullStr : obj.toString();
235     }
236
237     // Null
238 //-----------------------------------------------------------------------
239 /**
240      * <p>Class used as a null placeholder where <code>null</code>
241      * has another meaning.</p>
242      *
243      * <p>For example, in a <code>HashMap</code> the
244      * {@link java.util.HashMap#get(java.lang.Object)} method returns
245      * <code>null</code> if the <code>Map</code> contains
246      * <code>null</code> or if there is no matching key. The
247      * <code>Null</code> placeholder can be used to distinguish between
248      * these two cases.</p>
249      *
250      * <p>Another example is <code>Hashtable</code>, where <code>null</code>
251      * cannot be stored.</p>
252      */
253     public static class Null implements Serializable JavaDoc {
254         // declare serialization compatibility with Commons Lang 1.0
255 private static final long serialVersionUID = 7092611880189329093L;
256         
257         /**
258          * Restricted constructor - singleton.
259          */
260         Null() {
261         }
262         
263         /**
264          * <p>Ensure singleton.</p>
265          *
266          * @return the singleton value
267          */
268         private Object JavaDoc readResolve() {
269             return ObjectUtils.NULL;
270         }
271     }
272     
273 }
274
Popular Tags