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