1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache license, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * https://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the license for the specific language governing permissions and 15 * limitations under the license. 16 */ 17 18 package org.apache.commons.text.lookup; 19 20 import java.util.function.UnaryOperator; 21 22 /** 23 * Lookups a String key for a String value. 24 * <p> 25 * This class represents the simplest form of a string to string map. It has a benefit over a map in that it can create 26 * the result on demand based on the key. 27 * </p> 28 * <p> 29 * For example, it would be possible to implement a lookup that used the key as a primary key, and looked up the value 30 * on demand from the database. 31 * </p> 32 * 33 * @since 1.3 34 */ 35 @FunctionalInterface 36 public interface StringLookup extends UnaryOperator<String> { 37 38 /** 39 * Looks up a String key to provide a String value. 40 * <p> 41 * The internal implementation may use any mechanism to return the value. The simplest implementation is to use a 42 * Map. However, virtually any implementation is possible. 43 * </p> 44 * <p> 45 * For example, it would be possible to implement a lookup that used the key as a primary key, and looked up the 46 * value on demand from the database Or, a numeric based implementation could be created that treats the key as an 47 * integer, increments the value and return the result as a string - converting 1 to 2, 15 to 16 etc. 48 * </p> 49 * <p> 50 * This method always returns a String, regardless of the underlying data, by converting it as necessary. For 51 * example: 52 * </p> 53 * 54 * <pre> 55 * Map<String, Object> map = new HashMap<String, Object>(); 56 * map.put("number", Integer.valueOf(2)); 57 * assertEquals("2", StringLookupFactory.mapStringLookup(map).lookup("number")); 58 * </pre> 59 * 60 * @param key the key to look up, may be null. 61 * @return The matching value, null if no match. 62 * @since 1.14.0 63 */ 64 @Override 65 default String apply(final String key) { 66 return lookup(key); 67 } 68 69 /** 70 * Looks up a String key to provide a String value. 71 * <p> 72 * The internal implementation may use any mechanism to return the value. The simplest implementation is to use a 73 * Map. However, virtually any implementation is possible. 74 * </p> 75 * <p> 76 * For example, it would be possible to implement a lookup that used the key as a primary key, and looked up the 77 * value on demand from the database Or, a numeric based implementation could be created that treats the key as an 78 * integer, increments the value and return the result as a string - converting 1 to 2, 15 to 16 etc. 79 * </p> 80 * <p> 81 * This method always returns a String, regardless of the underlying data, by converting it as necessary. For 82 * example: 83 * </p> 84 * 85 * <pre> 86 * Map<String, Object> map = new HashMap<String, Object>(); 87 * map.put("number", Integer.valueOf(2)); 88 * assertEquals("2", StringLookupFactory.mapStringLookup(map).lookup("number")); 89 * </pre> 90 * 91 * @param key the key to look up, may be null. 92 * @return The matching value, null if no match. 93 * @deprecated Use {@link #apply(String)}. 94 */ 95 @Deprecated 96 String lookup(String key); 97 }