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 * http://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 package org.apache.logging.log4j.core.lookup; 18 19 import org.apache.logging.log4j.core.LogEvent; 20 21 /** 22 * Lookup a String key to a String value. 23 * <p> 24 * This class represents the simplest form of a string to string map. 25 * It has a benefit over a map in that it can create the result on 26 * demand based on the key. 27 * <p> 28 * This class comes complete with various factory methods. 29 * If these do not suffice, you can subclass and implement your own matcher. 30 * <p> 31 * For example, it would be possible to implement a lookup that used the 32 * key as a primary key, and looked up the value on demand from the database 33 * 34 * @version $Id$ 35 */ 36 public interface StrLookup { 37 /** 38 * Looks up a String key to a String value. 39 * <p> 40 * The internal implementation may use any mechanism to return the value. 41 * The simplest implementation is to use a Map. However, virtually any 42 * implementation is possible. 43 * <p> 44 * For example, it would be possible to implement a lookup that used the 45 * key as a primary key, and looked up the value on demand from the database 46 * Or, a numeric based implementation could be created that treats the key 47 * as an integer, increments the value and return the result as a string - 48 * converting 1 to 2, 15 to 16 etc. 49 * <p> 50 * The {@link #lookup(String)} method always returns a String, regardless of 51 * the underlying data, by converting it as necessary. For example: 52 * <pre> 53 * Map<String, Object> map = new HashMap<String, Object>(); 54 * map.put("number", new Integer(2)); 55 * assertEquals("2", StrLookup.mapLookup(map).lookup("number")); 56 * </pre> 57 * @param key the key to be looked up, may be null 58 * @return the matching value, null if no match 59 */ 60 String lookup(String key); 61 62 /** 63 * Looks up a String key to a String value possibly using the current LogEvent. 64 * <p> 65 * The internal implementation may use any mechanism to return the value. 66 * The simplest implementation is to use a Map. However, virtually any 67 * implementation is possible. 68 * <p> 69 * For example, it would be possible to implement a lookup that used the 70 * key as a primary key, and looked up the value on demand from the database 71 * Or, a numeric based implementation could be created that treats the key 72 * as an integer, increments the value and return the result as a string - 73 * converting 1 to 2, 15 to 16 etc. 74 * <p> 75 * The {@link #lookup(String)} method always returns a String, regardless of 76 * the underlying data, by converting it as necessary. For example: 77 * <pre> 78 * Map<String, Object> map = new HashMap<String, Object>(); 79 * map.put("number", new Integer(2)); 80 * assertEquals("2", StrLookup.mapLookup(map).lookup("number")); 81 * </pre> 82 * @param event The current LogEvent. 83 * @param key the key to be looked up, may be null 84 * @return the matching value, null if no match 85 */ 86 String lookup(LogEvent event, String key); 87 }