add missingLookupHandler in InterpolatorStringLookup

src/main/java/org/apache/commons/text/lookup/InterpolatorStringLookup.java

@@ -19,6 +19,7 @@
 import java.util.Collections;
 import java.util.Map;
 import java.util.Map.Entry;
+import java.util.function.BiPredicate;
 import java.util.stream.Collectors;
 
 /**
@@ -45,6 +46,9 @@ final class InterpolatorStringLookup extends AbstractStringLookup {
     /** The map of String lookups keyed by prefix. */
     private final Map<String, StringLookup> stringLookupMap;
 
+    /** The handler to determine whether to use {@link #defaultStringLookup} for prefix without corresponding lookup in {@link #stringLookupMap}. */
+    private final BiPredicate<String, String> missingLookupHandler;
+
     /**
      * Constructs an instance using only lookups that work without initial properties and are stateless.
      * <p>
@@ -62,10 +66,11 @@ final class InterpolatorStringLookup extends AbstractStringLookup {
      * @param defaultStringLookup the default string lookup.
      * @param addDefaultLookups whether the default lookups should be used.
      */
-    InterpolatorStringLookup(final Map<String, StringLookup> stringLookupMap, final StringLookup defaultStringLookup,
+    InterpolatorStringLookup(final Map<String, StringLookup> stringLookupMap, final StringLookup defaultStringLookup, BiPredicate<String, String> missingLookupHandler,
             final boolean addDefaultLookups) {
         this.defaultStringLookup = defaultStringLookup;
         this.stringLookupMap = stringLookupMap.entrySet().stream().collect(Collectors.toMap(e -> StringLookupFactory.toKey(e.getKey()), Entry::getValue));
+        this.missingLookupHandler = missingLookupHandler;
         if (addDefaultLookups) {
             StringLookupFactory.INSTANCE.addDefaultStringLookups(this.stringLookupMap);
         }
@@ -90,7 +95,7 @@ <V> InterpolatorStringLookup(final Map<String, V> defaultMap) {
      * @param defaultStringLookup the default lookup.
      */
     InterpolatorStringLookup(final StringLookup defaultStringLookup) {
-        this(Collections.emptyMap(), defaultStringLookup, true);
+        this(Collections.emptyMap(), defaultStringLookup, null, true);
     }
 
     /**
@@ -106,7 +111,10 @@ public Map<String, StringLookup> getStringLookupMap() {
      * Resolves the specified variable. This implementation will try to extract a variable prefix from the given
      * variable name (the first colon (':') is used as prefix separator). It then passes the name of the variable with
      * the prefix stripped to the lookup object registered for this prefix. If no prefix can be found or if the
-     * associated lookup object cannot resolve this variable, the default lookup object will be used.
+     * associated lookup object cannot resolve this variable, the default lookup object will be used. If the prefix
+     * can be found but no associated lookup can be found in {@link #stringLookupMap}, the {@link #missingLookupHandler}
+     * is used to determine whether to use the default lookup. if the {@link #missingLookupHandler} is null or returns
+     * {@code true}, the default lookup will be used.
      *
      * @param key the name of the variable whose value is to be looked up
      * @return The value of this variable or <strong>null</strong> if it cannot be resolved
@@ -125,6 +133,8 @@ public String lookup(String key) {
             String value = null;
             if (lookup != null) {
                 value = lookup.apply(name);
+            } else if (missingLookupHandler != null && !missingLookupHandler.test(prefix, key)) {
+                return null;
             }
 
             if (value != null) {

src/main/java/org/apache/commons/text/lookup/StringLookupFactory.java

@@ -27,6 +27,7 @@
 import java.util.Map;
 import java.util.Properties;
 import java.util.function.BiFunction;
+import java.util.function.BiPredicate;
 import java.util.function.Function;
 import java.util.function.Supplier;
 
@@ -1040,7 +1041,26 @@ public StringLookup interpolatorStringLookup() {
      */
     public StringLookup interpolatorStringLookup(final Map<String, StringLookup> stringLookupMap, final StringLookup defaultStringLookup,
             final boolean addDefaultLookups) {
-        return new InterpolatorStringLookup(stringLookupMap, defaultStringLookup, addDefaultLookups);
+        return new InterpolatorStringLookup(stringLookupMap, defaultStringLookup, null, addDefaultLookups);
+    }
+
+    /**
+     * Returns a new InterpolatorStringLookup. If {@code addDefaultLookups} is {@code true}, the configured {@link #addDefaultStringLookups(Map) default
+     * lookups} are included in addition to the ones provided in {@code stringLookupMap}. (See the class documentation for details on how default lookups are
+     * configured.)
+     *
+     * @param stringLookupMap     the map of string lookups.
+     * @param defaultStringLookup the default string lookup; this lookup is used when a variable cannot be resolved using the lookups in {@code stringLookupMap}
+     *                            or the configured default lookups (if enabled)
+     * @param missingLookupHandler the handler determines whether to use {@code defaultStringLookup} when no corresponding lookup found for a prefix
+     *                             in {@code stringLookupMap}, if it is null or returns {@code true}, the {@code defaultStringLookup} will be used.
+     * @param addDefaultLookups   whether to use default lookups as described above.
+     * @return a new InterpolatorStringLookup.
+     * @since 1.13.2
+     */
+    public StringLookup interpolatorStringLookup(final Map<String, StringLookup> stringLookupMap, final StringLookup defaultStringLookup,
+                                                 BiPredicate<String, String> missingLookupHandler, final boolean addDefaultLookups) {
+        return new InterpolatorStringLookup(stringLookupMap, defaultStringLookup, missingLookupHandler, addDefaultLookups);
     }
 
     /**

src/test/java/org/apache/commons/text/lookup/InterpolatorStringLookupTest.java

@@ -22,6 +22,7 @@
 import static org.junit.jupiter.api.Assertions.assertNull;
 
 import java.text.SimpleDateFormat;
+import java.util.Collections;
 import java.util.Date;
 import java.util.HashMap;
 import java.util.Map;
@@ -96,6 +97,42 @@ public void testLookup() {
         assertEquals(TESTVAL, value);
     }
 
+    @Test
+    public void testLookupMissingReturnTrue() {
+        final Map<String, String> map = new HashMap<>();
+        map.put(TESTKEY, TESTVAL);
+        final StringLookup lookup = new InterpolatorStringLookup(Collections.emptyMap(), StringLookupFactory.INSTANCE.mapStringLookup(map),
+                (prefix, key) -> true, true);
+        String value = lookup.lookup(TESTKEY);
+        assertEquals(TESTVAL, value);
+        value = lookup.lookup("ctx:" + TESTKEY);
+        assertEquals(TESTVAL, value);
+        value = lookup.lookup("sys:" + TESTKEY);
+        assertEquals(TESTVAL, value);
+        value = lookup.lookup("BadKey");
+        assertNull(value);
+        value = lookup.lookup("ctx:" + TESTKEY);
+        assertEquals(TESTVAL, value);
+    }
+
+    @Test
+    public void testLookupMissingReturnFalse() {
+        final Map<String, String> map = new HashMap<>();
+        map.put(TESTKEY, TESTVAL);
+        final StringLookup lookup = new InterpolatorStringLookup(Collections.emptyMap(), StringLookupFactory.INSTANCE.mapStringLookup(map),
+                (prefix, key) -> false, true);
+        String value = lookup.lookup(TESTKEY);
+        assertEquals(TESTVAL, value);
+        value = lookup.lookup("ctx:" + TESTKEY);
+        assertNull(value);
+        value = lookup.lookup("sys:" + TESTKEY);
+        assertEquals(TESTVAL, value);
+        value = lookup.lookup("BadKey");
+        assertNull(value);
+        value = lookup.lookup("ctx:" + TESTKEY);
+        assertNull(value);
+    }
+
     @Test
     public void testLookupKeys() {
         final InterpolatorStringLookup lookup = new InterpolatorStringLookup((Map<String, Object>) null);