View Javadoc

    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&lt;String, Object&gt; map = new HashMap&lt;String, Object&gt;();
    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&lt;String, Object&gt; map = new HashMap&lt;String, Object&gt;();
    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 }