Revamp the Lookups page

We revamp the `Lookups` page by:

* Adding information on different evaluation contexts supported by lookups.
* Adding a cheatsheet on which lookup is available in which evaluation context. E.g., using `$${sys:something}` on a per-event level is a major performance waster.
* Removing the description of the broken `jvmrunargs` lookup (see apache#2726).
* Improving the description of the `main` lookup by providing a code example that does not fail if the user switches logging implementations.
* Shortening and improving the description of other lookups.

log4j-core-test/src/test/java/org/apache/logging/log4j/core/lookup/MainInputArgumentsJmxLookupTest.java

@@ -18,6 +18,7 @@
 
 import static org.junit.jupiter.api.Assertions.assertNull;
 
+import java.util.Map;
 import org.junit.jupiter.api.Test;
 
 /**
@@ -36,15 +37,40 @@ public static void main(final String[] args) {
     @Test
     public void testMap() {
         final JmxRuntimeInputArgumentsLookup lookup = JmxRuntimeInputArgumentsLookup.JMX_SINGLETON;
-        assertNull(lookup.lookup(null));
-        assertNull(lookup.lookup("X"));
-        assertNull(lookup.lookup("foo.txt"));
+        String result2 = null;
+        if (null != null) {
+            final Map<String, String> map2 = lookup.getMap();
+            result2 = map2 == null ? null : map2.get(null);
+        }
+        assertNull(result2);
+        String result1 = null;
+        if ("X" != null) {
+            final Map<String, String> map1 = lookup.getMap();
+            result1 = map1 == null ? null : map1.get("X");
+        }
+        assertNull(result1);
+        String result = null;
+        if ("foo.txt" != null) {
+            final Map<String, String> map = lookup.getMap();
+            result = map == null ? null : map.get("foo.txt");
+        }
+        assertNull(result);
     }
 
     public void callFromMain() {
         final JmxRuntimeInputArgumentsLookup lookup = JmxRuntimeInputArgumentsLookup.JMX_SINGLETON;
-        assertNull(lookup.lookup(null));
-        assertNull(lookup.lookup("X"));
+        String result1 = null;
+        if (null != null) {
+            final Map<String, String> map1 = lookup.getMap();
+            result1 = map1 == null ? null : map1.get(null);
+        }
+        assertNull(result1);
+        String result = null;
+        if ("X" != null) {
+            final Map<String, String> map = lookup.getMap();
+            result = map == null ? null : map.get("X");
+        }
+        assertNull(result);
         // Eclipse adds -Dfile.encoding=Cp1252
         // assertEquals("--file", lookup.lookup("0"));
         // assertEquals("foo.txt", lookup.lookup("1"));

log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/AbstractLookup.java

@@ -16,6 +16,8 @@
  */
 package org.apache.logging.log4j.core.lookup;
 
+import org.apache.logging.log4j.core.LogEvent;
+
 /**
  * A default lookup for others to extend.
  *

log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/EnvironmentLookup.java

@@ -27,12 +27,12 @@ public class EnvironmentLookup extends AbstractLookup {
 
     /**
      * Looks up the value of the environment variable.
-     * @param event The current LogEvent (is ignored by this StrLookup).
+     *
      * @param key  the key to be looked up, may be null
      * @return The value of the environment variable.
      */
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         return System.getenv(key);
     }
 }

log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/JavaLookup.java

@@ -90,14 +90,12 @@ public String getVirtualMachine() {
     /**
      * Looks up the value of the environment variable.
      *
-     * @param event
-     *        The current LogEvent (is ignored by this StrLookup).
      * @param key
      *        the key to be looked up, may be null
      * @return The value of the environment variable.
      */
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         switch (key) {
             case "version":
                 return "Java version " + getSystemProperty("java.version");

log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/JmxRuntimeInputArgumentsLookup.java

@@ -48,12 +48,7 @@ public JmxRuntimeInputArgumentsLookup(final Map<String, String> map) {
     }
 
     @Override
-    public String lookup(final LogEvent event, final String key) {
-        return lookup(key);
-    }
-
-    @Override
-    public String lookup(final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         if (key == null) {
             return null;
         }

log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/JndiLookup.java

@@ -50,12 +50,11 @@ public JndiLookup() {
     /**
      * Looks up the value of the JNDI resource.
      *
-     * @param event The current LogEvent (is ignored by this StrLookup).
      * @param key the JNDI resource name to be looked up, may be null
      * @return The String value of the JNDI resource.
      */
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         if (key == null) {
             return null;
         }

log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/Log4jLookup.java

@@ -53,7 +53,7 @@ private static URI getParent(final URI uri) throws URISyntaxException {
     }
 
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         if (configuration != null) {
             final ConfigurationSource configSrc = configuration.getConfigurationSource();
             final File file = configSrc.getFile();

log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/LowerLookup.java

@@ -25,26 +25,16 @@
  * Converts values to lower case. The passed in "key" should be the value of another lookup.
  */
 @Plugin(name = "lower", category = StrLookup.CATEGORY)
-public class LowerLookup implements StrLookup {
+public class LowerLookup extends AbstractLookup {
 
     /**
      * Converts the "key" to lower case.
+     *
      * @param key  the key to be looked up, may be null
      * @return The value associated with the key.
      */
     @Override
-    public String lookup(final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         return key != null ? toRootLowerCase(key) : null;
     }
-
-    /**
-     * Converts the "key" to lower case.
-     * @param event The current LogEvent.
-     * @param key  the key to be looked up, may be null
-     * @return The value associated with the key.
-     */
-    @Override
-    public String lookup(final LogEvent event, final String key) {
-        return lookup(key);
-    }
 }

log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/MainMapLookup.java

@@ -82,7 +82,7 @@ public static void setMainArguments(final String... args) {
     }
 
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         return MAIN_SINGLETON.getMap().get(key);
     }
 

log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/ResourceBundleLookup.java

@@ -39,14 +39,12 @@ public class ResourceBundleLookup extends AbstractLookup {
      *
      * For example: "com.domain.messages:MyKey".
      *
-     * @param event
-     *            The current LogEvent.
      * @param key
      *            the key to be looked up, may be null
      * @return The value associated with the key.
      */
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         if (key == null) {
             return null;
         }

log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/StructuredDataLookup.java

@@ -24,7 +24,7 @@
  * Looks up keys from {@link org.apache.logging.log4j.message.StructuredDataMessage} log messages.
  */
 @Plugin(name = "sd", category = StrLookup.CATEGORY)
-public class StructuredDataLookup implements StrLookup {
+public class StructuredDataLookup extends AbstractLookup {
 
     /**
      * Key to obtain the id of a structured message.
@@ -36,16 +36,6 @@ public class StructuredDataLookup implements StrLookup {
      */
     public static final String TYPE_KEY = "type";
 
-    /**
-     * Returns {@code null}. This Lookup plugin does not make sense outside the context of a LogEvent.
-     * @param key  The key to be looked up, may be null.
-     * @return {@code null}
-     */
-    @Override
-    public String lookup(final String key) {
-        return null;
-    }
-
     /**
      * Looks up the value for the key using the data in the LogEvent.
      * @param event The current LogEvent.

log4j-docker/src/main/java/org/apache/logging/log4j/docker/DockerLookup.java

@@ -95,7 +95,7 @@ public DockerLookup() {
     }
 
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         if (container == null) {
             return null;
         }

log4j-jakarta-web/src/main/java/org/apache/logging/log4j/web/WebLookup.java

@@ -30,7 +30,7 @@ public class WebLookup extends AbstractLookup {
     private static final String INIT_PARAM_PREFIX = "initParam.";
 
     @Override
-    public String lookup(final LogEvent event, final String key) {
+    public String lookup(final LogEvent ignored, final String key) {
         final ServletContext ctx = WebLoggerContextUtils.getServletContext();
         if (ctx == null) {
             return null;

src/site/antora/modules/ROOT/examples/manual/lookups/MainArgsExample.java

@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package example;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+public final class MainArgsExample implements Runnable {
+
+    // tag::usage[]
+    private final Logger logger = LogManager.getLogger(); // <1>
+
+    public static void main(final String[] args) {
+        try { // <2>
+            Class.forName("org.apache.logging.log4j.core.lookup.MainMapLookup")
+                    .getDeclaredMethod("setMainArguments", String[].class)
+                    .invoke(null, (Object) args);
+        } catch (final ReflectiveOperationException e) {
+            // Log4j Core is not used.
+        }
+        new MainArgsExample().run();
+    }
+    // end::usage[]
+
+    @Override
+    public void run() {
+        logger.info("Hello `main` lookup!");
+    }
+}

src/site/antora/modules/ROOT/examples/manual/lookups/mainArgs.json

@@ -0,0 +1,31 @@
+{
+  "Configuration": {
+    "Properties": {
+      "Property": [ // <1>
+        {
+          "name": "--logfile",
+          "value": "logs/app.log"
+        },
+        {
+          "name": "--loglevel",
+          "value": "INFO"
+        }
+      ]
+    },
+    "Appenders": {
+      "File": {
+        "fileName": "${main:\\--logfile}", // <2>
+        "name": "FILE",
+        "JsonTemplateLayout": {}
+      }
+    },
+    "Loggers": {
+      "Root": {
+        "level": "${main:\\--loglevel", // <2>
+        "AppenderRef": {
+          "ref": "FILE"
+        }
+      }
+    }
+  }
+}

src/site/antora/modules/ROOT/examples/manual/lookups/mainArgs.properties

@@ -0,0 +1,29 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to you under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+##
+# <1>
+property.--logfile = logs/app.log
+property.--loglevel = INFO
+
+appender.0.type = File
+# <2>
+appender.0.fileName = ${main:\\--logfile}
+appender.0.name = FILE
+
+# <2>
+rootLogger.level = ${main:\\--loglevel}
+rootLogger.appenderRef.0.ref = FILE

src/site/antora/modules/ROOT/examples/manual/lookups/mainArgs.xml

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one or more
+  ~ contributor license agreements.  See the NOTICE file distributed with
+  ~ this work for additional information regarding copyright ownership.
+  ~ The ASF licenses this file to you under the Apache License, Version 2.0
+  ~ (the "License"); you may not use this file except in compliance with
+  ~ the License.  You may obtain a copy of the License at
+  ~
+  ~      http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+<Configuration xmlns="https://logging.apache.org/xml/ns"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+               xsi:schemaLocation="
+                   https://logging.apache.org/xml/ns
+                   https://logging.apache.org/xml/ns/log4j-config-2.xsd">
+  <Properties> <!--1-->
+    <Property name="--logfile" value="logs/app.log"/>
+    <Property name="--loglevel" value="INFO"/>
+  </Properties>
+  <Appenders>
+    <File fileName="${main:\--logfile}"
+          name="FILE"/> <!--2-->
+  </Appenders>
+  <Loggers>
+    <Root level="${main:\--loglevel}"> <!--2-->
+      <AppenderRef ref="FILE"/>
+    </Root>
+  </Loggers>
+</Configuration>