001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 *
019 */
020 package org.apache.directory.shared.ldap.util;
021
022
023 import java.io.Serializable;
024
025
026 /**
027 * <p>
028 * Operations on <code>Object</code>.
029 * </p>
030 * <p>
031 * This class tries to handle <code>null</code> input gracefully. An exception
032 * will generally not be thrown for a <code>null</code> input. Each method
033 * documents its behaviour in more detail.
034 * </p>
035 *
036 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
037 */
038 public class ObjectUtils
039 {
040
041 /**
042 * <p>
043 * Singleton used as a <code>null</code> placeholder where
044 * <code>null</code> has another meaning.
045 * </p>
046 * <p>
047 * For example, in a <code>HashMap</code> the
048 * {@link java.util.HashMap#get(java.lang.Object)} method returns
049 * <code>null</code> if the <code>Map</code> contains <code>null</code>
050 * or if there is no matching key. The <code>Null</code> placeholder can
051 * be used to distinguish between these two cases.
052 * </p>
053 * <p>
054 * Another example is <code>Hashtable</code>, where <code>null</code>
055 * cannot be stored.
056 * </p>
057 * <p>
058 * This instance is Serializable.
059 * </p>
060 */
061 public static final Null NULL = new Null();
062
063
064 /**
065 * <p>
066 * <code>ObjectUtils</code> instances should NOT be constructed in
067 * standard programming. Instead, the class should be used as
068 * <code>ObjectUtils.defaultIfNull("a","b");</code>.
069 * </p>
070 * <p>
071 * This constructor is public to permit tools that require a JavaBean
072 * instance to operate.
073 * </p>
074 */
075 public ObjectUtils()
076 {
077 }
078
079
080 // Defaulting
081 // -----------------------------------------------------------------------
082 /**
083 * <p>
084 * Returns a default value if the object passed is <code>null</code>.
085 * </p>
086 *
087 * <pre>
088 * ObjectUtils.defaultIfNull(null, null) = null
089 * ObjectUtils.defaultIfNull(null, "") = ""
090 * ObjectUtils.defaultIfNull(null, "zz") = "zz"
091 * ObjectUtils.defaultIfNull("abc", *) = "abc"
092 * ObjectUtils.defaultIfNull(Boolean.TRUE, *) = Boolean.TRUE
093 * </pre>
094 *
095 * @param object
096 * the <code>Object</code> to test, may be <code>null</code>
097 * @param defaultValue
098 * the default value to return, may be <code>null</code>
099 * @return <code>object</code> if it is not <code>null</code>,
100 * defaultValue otherwise
101 */
102 public static Object defaultIfNull( Object object, Object defaultValue )
103 {
104 return ( object != null ? object : defaultValue );
105 }
106
107
108 /**
109 * <p>
110 * Compares two objects for equality, where either one or both objects may
111 * be <code>null</code>.
112 * </p>
113 *
114 * <pre>
115 * ObjectUtils.equals(null, null) = true
116 * ObjectUtils.equals(null, "") = false
117 * ObjectUtils.equals("", null) = false
118 * ObjectUtils.equals("", "") = true
119 * ObjectUtils.equals(Boolean.TRUE, null) = false
120 * ObjectUtils.equals(Boolean.TRUE, "true") = false
121 * ObjectUtils.equals(Boolean.TRUE, Boolean.TRUE) = true
122 * ObjectUtils.equals(Boolean.TRUE, Boolean.FALSE) = false
123 * </pre>
124 *
125 * @param object1
126 * the first object, may be <code>null</code>
127 * @param object2
128 * the second object, may be <code>null</code>
129 * @return <code>true</code> if the values of both objects are the same
130 */
131 public static boolean equals( Object object1, Object object2 )
132 {
133 if ( object1 == object2 )
134 {
135 return true;
136 }
137 if ( ( object1 == null ) || ( object2 == null ) )
138 {
139 return false;
140 }
141 return object1.equals( object2 );
142 }
143
144
145 /**
146 * <p>
147 * Gets the hash code of an object returning zero when the object is
148 * <code>null</code>.
149 * </p>
150 *
151 * <pre>
152 * ObjectUtils.hashCode(null) = 0
153 * ObjectUtils.hashCode(obj) = obj.hashCode()
154 * </pre>
155 *
156 * @param obj
157 * the object to obtain the hash code of, may be
158 * <code>null</code>
159 * @return the hash code of the object, or zero if null
160 * @since 2.1
161 */
162 public static int hashCode( Object obj )
163 {
164 return ( ( obj == null ) ? 0 : obj.hashCode() );
165 }
166
167
168 // Identity ToString
169 // -----------------------------------------------------------------------
170 /**
171 * <p>
172 * Gets the toString that would be produced by <code>Object</code> if a
173 * class did not override toString itself. <code>null</code> will return
174 * <code>null</code>.
175 * </p>
176 *
177 * <pre>
178 * ObjectUtils.identityToString(null) = null
179 * ObjectUtils.identityToString("") = "java.lang.String@1e23"
180 * ObjectUtils.identityToString(Boolean.TRUE) = "java.lang.Boolean@7fa"
181 * </pre>
182 *
183 * @param object
184 * the object to create a toString for, may be <code>null</code>
185 * @return the default toString text, or <code>null</code> if
186 * <code>null</code> passed in
187 */
188 public static String identityToString( Object object )
189 {
190 if ( object == null )
191 {
192 return null;
193 }
194 return appendIdentityToString( null, object ).toString();
195 }
196
197
198 /**
199 * <p>
200 * Appends the toString that would be produced by <code>Object</code> if a
201 * class did not override toString itself. <code>null</code> will return
202 * <code>null</code>.
203 * </p>
204 *
205 * <pre>
206 * ObjectUtils.appendIdentityToString(*, null) = null
207 * ObjectUtils.appendIdentityToString(null, "") = "java.lang.String@1e23"
208 * ObjectUtils.appendIdentityToString(null, Boolean.TRUE) = "java.lang.Boolean@7fa"
209 * ObjectUtils.appendIdentityToString(buf, Boolean.TRUE) = buf.append("java.lang.Boolean@7fa")
210 * </pre>
211 *
212 * @param buffer
213 * the buffer to append to, may be <code>null</code>
214 * @param object
215 * the object to create a toString for, may be <code>null</code>
216 * @return the default toString text, or <code>null</code> if
217 * <code>null</code> passed in
218 * @since 2.0
219 */
220 public static StringBuffer appendIdentityToString( StringBuffer buffer, Object object )
221 {
222 if ( object == null )
223 {
224 return null;
225 }
226 if ( buffer == null )
227 {
228 buffer = new StringBuffer();
229 }
230 return buffer.append( object.getClass().getName() ).append( '@' ).append(
231 Integer.toHexString( System.identityHashCode( object ) ) );
232 }
233
234
235 // ToString
236 // -----------------------------------------------------------------------
237 /**
238 * <p>
239 * Gets the <code>toString</code> of an <code>Object</code> returning an
240 * empty string ("") if <code>null</code> input.
241 * </p>
242 *
243 * <pre>
244 * ObjectUtils.toString(null) = ""
245 * ObjectUtils.toString("") = ""
246 * ObjectUtils.toString("bat") = "bat"
247 * ObjectUtils.toString(Boolean.TRUE) = "true"
248 * </pre>
249 *
250 * @see String#valueOf(Object)
251 * @param obj
252 * the Object to <code>toString</code>, may be null
253 * @return the passed in Object's toString, or nullStr if <code>null</code>
254 * input
255 * @since 2.0
256 */
257 public static String toString( Object obj )
258 {
259 return ( obj == null ? "" : obj.toString() );
260 }
261
262
263 /**
264 * <p>
265 * Gets the <code>toString</code> of an <code>Object</code> returning a
266 * specified text if <code>null</code> input.
267 * </p>
268 *
269 * <pre>
270 * ObjectUtils.toString(null, null) = null
271 * ObjectUtils.toString(null, "null") = "null"
272 * ObjectUtils.toString("", "null") = ""
273 * ObjectUtils.toString("bat", "null") = "bat"
274 * ObjectUtils.toString(Boolean.TRUE, "null") = "true"
275 * </pre>
276 *
277 * @see String#valueOf(Object)
278 * @param obj
279 * the Object to <code>toString</code>, may be null
280 * @param nullStr
281 * the String to return if <code>null</code> input, may be null
282 * @return the passed in Object's toString, or nullStr if <code>null</code>
283 * input
284 * @since 2.0
285 */
286 public static String toString( Object obj, String nullStr )
287 {
288 return ( obj == null ? nullStr : obj.toString() );
289 }
290
291 // Null
292 // -----------------------------------------------------------------------
293 /**
294 * <p>
295 * Class used as a null placeholder where <code>null</code> has another
296 * meaning.
297 * </p>
298 * <p>
299 * For example, in a <code>HashMap</code> the
300 * {@link java.util.HashMap#get(java.lang.Object)} method returns
301 * <code>null</code> if the <code>Map</code> contains <code>null</code>
302 * or if there is no matching key. The <code>Null</code> placeholder can
303 * be used to distinguish between these two cases.
304 * </p>
305 * <p>
306 * Another example is <code>Hashtable</code>, where <code>null</code>
307 * cannot be stored.
308 * </p>
309 */
310 public static class Null implements Serializable
311 {
312 // declare serialization compatibility with Commons Lang 1.0
313 private static final long serialVersionUID = 7092611880189329093L;
314
315
316 /**
317 * Restricted constructor - singleton.
318 */
319 Null()
320 {
321 }
322
323
324 /**
325 * <p>
326 * Ensure singleton.
327 * </p>
328 *
329 * @return the singleton value
330 */
331 private Object readResolve()
332 {
333 return ObjectUtils.NULL;
334 }
335 }
336
337 }