[LANG-1331] ImmutablePair.nullPair()

src/changes/changes.xml

@@ -90,6 +90,7 @@ The <action> type attribute can be add,update,fix,remove.
     <action issue="LANG-1313" type="add" dev="pschumacher" due-to="Tomschi">Add ArchUtils - An utility class for the "os.arch" system property</action>
     <action issue="LANG-1272" type="add" dev="ebourg">Add shuffle methods to ArrayUtils</action>
     <action issue="LANG-1317" type="add" dev="pschumacher" due-to="Yasser Zamani">Add MethodUtils#findAnnotation and extend MethodUtils#getMethodsWithAnnotation for non-public, super-class and interface methods</action>
+    <action issue="LANG-1331" type="add" dev="ggregory">Add ImmutablePair.nullPair()</action>    
   </release>
 
   <release version="3.5" date="2016-10-13" description="New features including Java 9 detection">

src/main/java/org/apache/commons/lang3/tuple/ImmutablePair.java

@@ -33,9 +33,27 @@ package org.apache.commons.lang3.tuple;
  */
 public final class ImmutablePair<L, R> extends Pair<L, R> {
 
+    /**
+     * An immutable pair of nulls.
+     */
+    // This is not defined with generics to avoid warnings in call sites.
+    @SuppressWarnings("rawtypes")
+    private static final ImmutablePair NULL = ImmutablePair.of(null, null);
+
     /** Serialization version */
     private static final long serialVersionUID = 4954918890077093841L;
 
+    /** 
+     * Returns an immutable pair of nulls.
+     * 
+     * @return an immutable pair of nulls. 
+     * @since 3.6
+     */
+    @SuppressWarnings("rawtypes")
+    public static <L, R> ImmutablePair<L, R> nullPair() {
+        return NULL;
+    }
+    
     /** Left object */
     public final L left;
     /** Right object */

src/test/java/org/apache/commons/lang3/tuple/ImmutablePairTest.java

@@ -18,7 +18,9 @@ package org.apache.commons.lang3.tuple;
 
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
 import static org.junit.Assert.assertTrue;
 
 import java.io.ByteArrayInputStream;
@@ -76,7 +78,45 @@ public class ImmutablePairTest {
     public void testHashCode() throws Exception {
         assertEquals(ImmutablePair.of(null, "foo").hashCode(), ImmutablePair.of(null, "foo").hashCode());
     }
-
+    
+    @Test
+    public void testNullPairEquals() {
+        assertEquals(ImmutablePair.nullPair(), ImmutablePair.nullPair());
+    }
+        
+    @Test
+    public void testNullPairSame() {
+        assertSame(ImmutablePair.nullPair(), ImmutablePair.nullPair());
+    }
+        
+    @Test
+    public void testNullPairLeft() {
+        assertNull(ImmutablePair.nullPair().getLeft());
+    }
+        
+    @Test
+    public void testNullPairKey() {
+        assertNull(ImmutablePair.nullPair().getKey());
+    }
+        
+    @Test
+    public void testNullPairRight() {
+        assertNull(ImmutablePair.nullPair().getRight());
+    }
+        
+    @Test
+    public void testNullPairValue() {
+        assertNull(ImmutablePair.nullPair().getValue());
+    }
+        
+    @Test
+    public void testNullPairTyped() {
+        // No compiler warnings
+        // How do we assert that?
+        ImmutablePair<String, String> pair = ImmutablePair.nullPair();
+        assertNotNull(pair);
+    }
+        
     @Test
     public void testToString() throws Exception {
         assertEquals("(null,null)", ImmutablePair.of(null, null).toString());