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 * <p>
29 * This class comes complete with various factory methods.
30 * If these do not suffice, you can subclass and implement your own matcher.
31 * </p>
32 * <p>
33 * For example, it would be possible to implement a lookup that used the
34 * key as a primary key, and looked up the value on demand from the database
35 * </p>
36 */
37 public interface StrLookup {
38
39 /**
40 * Main plugin category for StrLookup plugins.
41 *
42 * @since 2.1
43 */
44 String CATEGORY = "Lookup";
45
46 /**
47 * Looks up a String key to a String value.
48 * <p>
49 * The internal implementation may use any mechanism to return the value.
50 * The simplest implementation is to use a Map. However, virtually any
51 * implementation is possible.
52 * </p>
53 * <p>
54 * For example, it would be possible to implement a lookup that used the
55 * key as a primary key, and looked up the value on demand from the database
56 * Or, a numeric based implementation could be created that treats the key
57 * as an integer, increments the value and return the result as a string -
58 * converting 1 to 2, 15 to 16 etc.
59 * </p>
60 * <p>
61 * This method always returns a String, regardless of
62 * the underlying data, by converting it as necessary. For example:
63 * </p>
64 * <pre>
65 * Map<String, Object> map = new HashMap<String, Object>();
66 * map.put("number", new Integer(2));
67 * assertEquals("2", StrLookup.mapLookup(map).lookup("number"));
68 * </pre>
69 * @param key the key to be looked up, may be null
70 * @return the matching value, null if no match
71 */
72 String lookup(String key);
73
74 /**
75 * Looks up a String key to a String value possibly using the current LogEvent.
76 * <p>
77 * The internal implementation may use any mechanism to return the value.
78 * The simplest implementation is to use a Map. However, virtually any
79 * implementation is possible.
80 * </p>
81 * <p>
82 * For example, it would be possible to implement a lookup that used the
83 * key as a primary key, and looked up the value on demand from the database
84 * Or, a numeric based implementation could be created that treats the key
85 * as an integer, increments the value and return the result as a string -
86 * converting 1 to 2, 15 to 16 etc.
87 * </p>
88 * <p>
89 * This method always returns a String, regardless of
90 * the underlying data, by converting it as necessary. For example:
91 * </p>
92 * <pre>
93 * Map<String, Object> map = new HashMap<String, Object>();
94 * map.put("number", new Integer(2));
95 * assertEquals("2", StrLookup.mapLookup(map).lookup("number"));
96 * </pre>
97 * @param event The current LogEvent.
98 * @param key the key to be looked up, may be null
99 * @return the matching value, null if no match
100 */
101 String lookup(LogEvent event, String key);
102 }