Add Null placeholder singleton

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/lang/trunk@137044 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/lang/ObjectUtils.java

@@ -1,5 +1,3 @@
-package org.apache.commons.lang;
-
 /* ====================================================================
  * The Apache Software License, Version 1.1
  *
@@ -53,7 +51,9 @@ package org.apache.commons.lang;
  * information on the Apache Software Foundation, please see
  * <http://www.apache.org/>.
  */
+package org.apache.commons.lang;
 
+import java.io.Serializable;
 /**
  * Common <code>Object</code> manipulation routines.
  *
@@ -61,10 +61,24 @@ package org.apache.commons.lang;
  * @author <a href="mailto:janekdb@yahoo.co.uk">Janek Bogucki</a>
  * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
  * @author <a href="mailto:scolebourne@joda.org">Stephen Colebourne</a>
- * @version $Id: ObjectUtils.java,v 1.2 2002/09/18 19:49:08 scolebourne Exp $
+ * @version $Id: ObjectUtils.java,v 1.3 2002/09/18 20:11:53 scolebourne Exp $
  */
 public class ObjectUtils {
     
+    /**
+     * Singleton used as a null placeholder where null has another meaning.
+     * <p>
+     * For example, in a <code>HashMap</code> the get(key) method returns null 
+     * if the Map contains null or if there is no matching key. The Null 
+     * placeholder can be used to distinguish between these two cases.
+     * <p>
+     * Another example is <code>HashTable</code>, where <code>null</code> 
+     * cannot be stored.
+     * <p>
+     * This instance is Serializable.
+     */
+    public static final Null NULL = new Null();
+    
     /**
      * ObjectUtils instances should NOT be constructed in standard programming.
      * Instead, the class should be used as <code>ObjectUtils.defaultIfNull("a","b");</code>.
@@ -123,4 +137,29 @@ public class ObjectUtils {
             .toString();
     }
 
+    /**
+     * Class used as a null placeholder where null has another meaning.
+     * <p>
+     * For example, in a <code>HashMap</code> the get(key) method returns null 
+     * if the Map contains null or if there is no matching key. The Null 
+     * placeholder can be used to distinguish between these two cases.
+     * <p>
+     * Another example is <code>HashTable</code>, where <code>null</code> 
+     * cannot be stored.
+     */
+    public static class Null implements Serializable {
+        /**
+         * Restricted constructor - singleton
+         */
+        private Null() {
+        }
+        
+        /**
+         * Ensure singleton
+         */
+        private Object readResolve() {
+            return ObjectUtils.NULL;
+        }
+    }
+    
 }