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 * @author Apache Software Foundation 35 * @version $Id$ 36 */ 37 public interface StrLookup { 38 /** 39 * Looks up a String key to a String value. 40 * <p> 41 * The internal implementation may use any mechanism to return the value. 42 * The simplest implementation is to use a Map. However, virtually any 43 * implementation is possible. 44 * <p> 45 * For example, it would be possible to implement a lookup that used the 46 * key as a primary key, and looked up the value on demand from the database 47 * Or, a numeric based implementation could be created that treats the key 48 * as an integer, increments the value and return the result as a string - 49 * converting 1 to 2, 15 to 16 etc. 50 * <p> 51 * The {@link #lookup(String)} method always returns a String, regardless of 52 * the underlying data, by converting it as necessary. For example: 53 * <pre> 54 * Map<String, Object> map = new HashMap<String, Object>(); 55 * map.put("number", new Integer(2)); 56 * assertEquals("2", StrLookup.mapLookup(map).lookup("number")); 57 * </pre> 58 * @param key the key to be looked up, may be null 59 * @return the matching value, null if no match 60 */ 61 String lookup(String key); 62 63 /** 64 * Looks up a String key to a String value possibly using the current LogEvent. 65 * <p> 66 * The internal implementation may use any mechanism to return the value. 67 * The simplest implementation is to use a Map. However, virtually any 68 * implementation is possible. 69 * <p> 70 * For example, it would be possible to implement a lookup that used the 71 * key as a primary key, and looked up the value on demand from the database 72 * Or, a numeric based implementation could be created that treats the key 73 * as an integer, increments the value and return the result as a string - 74 * converting 1 to 2, 15 to 16 etc. 75 * <p> 76 * The {@link #lookup(String)} method always returns a String, regardless of 77 * the underlying data, by converting it as necessary. For example: 78 * <pre> 79 * Map<String, Object> map = new HashMap<String, Object>(); 80 * map.put("number", new Integer(2)); 81 * assertEquals("2", StrLookup.mapLookup(map).lookup("number")); 82 * </pre> 83 * @param event The current LogEvent. 84 * @param key the key to be looked up, may be null 85 * @return the matching value, null if no match 86 */ 87 String lookup(LogEvent event, String key); 88 }