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 }