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, &quot;&quot;)        = &quot;&quot;
090         *  ObjectUtils.defaultIfNull(null, &quot;zz&quot;)      = &quot;zz&quot;
091         *  ObjectUtils.defaultIfNull(&quot;abc&quot;, *)        = &quot;abc&quot;
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, &quot;&quot;)                    = false
117         *  ObjectUtils.equals(&quot;&quot;, null)                    = false
118         *  ObjectUtils.equals(&quot;&quot;, &quot;&quot;)                      = true
119         *  ObjectUtils.equals(Boolean.TRUE, null)          = false
120         *  ObjectUtils.equals(Boolean.TRUE, &quot;true&quot;)        = 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(&quot;&quot;)           = &quot;java.lang.String@1e23&quot;
180         *  ObjectUtils.identityToString(Boolean.TRUE) = &quot;java.lang.Boolean@7fa&quot;
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, &quot;&quot;)           = &quot;java.lang.String@1e23&quot;
208         *  ObjectUtils.appendIdentityToString(null, Boolean.TRUE) = &quot;java.lang.Boolean@7fa&quot;
209         *  ObjectUtils.appendIdentityToString(buf, Boolean.TRUE)  = buf.append(&quot;java.lang.Boolean@7fa&quot;)
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)         = &quot;&quot;
245         *  ObjectUtils.toString(&quot;&quot;)           = &quot;&quot;
246         *  ObjectUtils.toString(&quot;bat&quot;)        = &quot;bat&quot;
247         *  ObjectUtils.toString(Boolean.TRUE) = &quot;true&quot;
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, &quot;null&quot;)         = &quot;null&quot;
272         *  ObjectUtils.toString(&quot;&quot;, &quot;null&quot;)           = &quot;&quot;
273         *  ObjectUtils.toString(&quot;bat&quot;, &quot;null&quot;)        = &quot;bat&quot;
274         *  ObjectUtils.toString(Boolean.TRUE, &quot;null&quot;) = &quot;true&quot;
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    }