Add putIfAbsent to MultiKeyMap

jdereg · jdereg · commit 7fb6c4e9af21 · 2025-07-06T18:56:07.000-04:00
diff --git a/changelog.md b/changelog.md
@@ -32,6 +32,7 @@
 >   * **Impact**: Minimal - fixes inconsistent behavior and provides migration path through feature options
 >   * **Rationale**: Eliminates confusion from mixed precision behavior and provides simple, memorable conversion rules
 > * Added `computeIfAbsent` support to `MultiKeyMap` for lazy value population
+> * Added `putIfAbsent` support to `MultiKeyMap` for atomic insert when key is missing or mapped to null
 
 #### 3.6.0
 > * **Feature Enhancement**: Added comprehensive `java.awt.Color` conversion support to `Converter`:
diff --git a/src/main/java/com/cedarsoftware/util/MultiKeyMap.java b/src/main/java/com/cedarsoftware/util/MultiKeyMap.java
@@ -1445,6 +1445,32 @@ public void putAll(Map<? extends Object, ? extends V> m) {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     * <p>
+     * Uses a double-check locking pattern to avoid unnecessary synchronization
+     * when a value is already present. If the key is absent or currently mapped
+     * to {@code null}, the provided value is stored.
+     *
+     * @see Map#putIfAbsent(Object, Object)
+     */
+    @Override
+    public V putIfAbsent(Object key, V value) {
+        V existing = get(key);
+        if (existing != null) {
+            return existing;
+        }
+
+        synchronized (writeLock) {
+            existing = get(key);
+            if (existing == null) {
+                put(key, value);
+                return null;
+            }
+            return existing;
+        }
+    }
+
     /**
      * {@inheritDoc}
      * <p>
diff --git a/src/test/java/com/cedarsoftware/util/MultiKeyMapPutIfAbsentTest.java b/src/test/java/com/cedarsoftware/util/MultiKeyMapPutIfAbsentTest.java
@@ -0,0 +1,51 @@
+package com.cedarsoftware.util;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Tests for the putIfAbsent API on MultiKeyMap.
+ */
+class MultiKeyMapPutIfAbsentTest {
+
+    @Test
+    void testPutOnAbsentKey() {
+        MultiKeyMap<String> map = new MultiKeyMap<>(16);
+
+        assertNull(map.putIfAbsent("a", "value"));
+        assertEquals("value", map.get("a"));
+    }
+
+    @Test
+    void testNoOverwriteWhenPresent() {
+        MultiKeyMap<String> map = new MultiKeyMap<>(16);
+        map.put("existing", "value");
+
+        assertEquals("value", map.putIfAbsent("existing", "new"));
+        assertEquals("value", map.get("existing"));
+    }
+
+    @Test
+    void testReplaceNullValue() {
+        MultiKeyMap<String> map = new MultiKeyMap<>(16);
+        map.put("nullKey", (String) null);
+
+        assertNull(map.putIfAbsent("nullKey", "filled"));
+        assertEquals("filled", map.get("nullKey"));
+    }
+
+    @Test
+    void testMultiKeyArrayAndCollection() {
+        MultiKeyMap<String> map = new MultiKeyMap<>(16);
+
+        Object[] arrayKey = {"x", "y"};
+        assertNull(map.putIfAbsent(arrayKey, "array"));
+        assertEquals("array", map.get("x", "y"));
+
+        assertNull(map.putIfAbsent(Arrays.asList("a", "b"), "list"));
+        assertEquals("list", map.get("a", "b"));
+    }
+}
diff --git a/userguide.md b/userguide.md
@@ -2135,6 +2135,7 @@ A high-performance, thread-safe Map implementation that supports multi-dimension
 - **Map compatible**: Works with Map interface for existing code
 - **Escape hatch**: Force arrays to be single keys when needed
 - **computeIfAbsent support**: Lazily populate values when keys are missing
+- **putIfAbsent support**: Atomically add entries only when absent
 
 ### API Design Philosophy
 
@@ -2360,6 +2361,12 @@ String value = cache.computeIfAbsent(
         k -> loadFromStore((Object[]) k));
 ```
 
+**Atomic Insert with putIfAbsent:**
+```java
+MultiKeyMap<String> config = new MultiKeyMap<>();
+config.putIfAbsent(new Object[]{"env", "prod"}, "prodConfig");
+```
+
 This implementation provides a clean, efficient alternative to composite key objects and nested Maps, with excellent performance characteristics and a developer-friendly API.
 
 ---
