Revamp the Web Applications page

log4j-jakarta-web/pom.xml

@@ -32,6 +32,7 @@
   <description>The Apache Log4j support for Jakarta EE 9+ web servlet containers</description>
 
   <properties>
+    <maven.javadoc.skip>false</maven.javadoc.skip>
 
     <!--
       ~ OSGi and JPMS options

src/site/antora/modules/ROOT/examples/manual/appenders/servlet-appender.json

@@ -0,0 +1,23 @@
+{
+  "Configuration": {
+    "Appenders": {
+      // tag::servlet[]
+      "Servlet": {
+        "name": "SERVLET",
+        "PatternLayout": {
+          "pattern": "%m%n",
+          "alwaysWriteExceptions": false // <1>
+        }
+      }
+      // end::servlet[]
+    },
+    "Loggers": {
+      "Root": {
+        "level": "INFO",
+        "AppenderRef": {
+          "ref": "SERVLET"
+        }
+      }
+    }
+  }
+}

src/site/antora/modules/ROOT/examples/manual/appenders/servlet-appender.properties

@@ -0,0 +1,28 @@
+#
+# 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.
+#
+##
+# tag::servlet[]
+appender.0.type = Servlet
+appender.0.name = SERVLET
+appender.0.layout.type = PatternLayout
+appender.0.layout.pattern = %m%n
+# <1>
+appender.0.layout.alwaysWriteExceptions = false
+# end::servlet[]
+
+rootLogger.level = INFO
+rootLogger.appenderRef.0.ref = SERVLET

src/site/antora/modules/ROOT/examples/manual/appenders/servlet-appender.xml

@@ -0,0 +1,34 @@
+<?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">
+  <Appenders>
+    <!-- tag::servlet[] -->
+    <Servlet name="SERVLET">
+      <PatternLayout pattern="%m%n" alwaysWriteExceptions="false"/> <!--1-->
+    </Servlet>
+    <!-- end::servlet[] -->
+  </Appenders>
+  <Loggers>
+    <Root level="INFO">
+      <AppenderRef ref="SERVLET"/>
+    </Root>
+  </Loggers>
+</Configuration>

src/site/antora/modules/ROOT/examples/manual/appenders/servlet-appender.yaml

@@ -0,0 +1,30 @@
+#
+# 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:
+  Appenders:
+    # tag::servlet[]
+    Servlet:
+      name: "SERVLET"
+      PatternLayout:
+        pattern: "%m%n"
+        alwaysWriteExceptions: false # <1>
+    # end::servlet[]
+  Loggers:
+    Root:
+      level: "INFO"
+      AppenderRef:
+        ref: "SERVLET"

src/site/antora/modules/ROOT/examples/manual/webapp/AsyncServlet.java

@@ -0,0 +1,59 @@
+/*
+ * 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 javax.servlet.AsyncContext;
+import javax.servlet.annotation.WebServlet;
+import javax.servlet.http.HttpServlet;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+import org.apache.logging.log4j.web.Log4jWebSupport;
+import org.apache.logging.log4j.web.WebLoggerContextUtils;
+
+@WebServlet(urlPatterns = "/async/*", asyncSupported = true)
+public class AsyncServlet extends HttpServlet {
+
+    private final Logger logger = LogManager.getLogger();
+
+    @Override
+    protected void doGet(HttpServletRequest req, HttpServletResponse resp) {
+        // tag::manual[]
+        AsyncContext asyncContext = req.startAsync();
+        Log4jWebSupport webSupport = WebLoggerContextUtils.getWebLifeCycle(getServletContext());
+        asyncContext.start(() -> {
+            try {
+                webSupport.setLoggerContext();
+                // Put your logic here
+            } finally {
+                webSupport.clearLoggerContext();
+            }
+        });
+        // end::manual[]
+    }
+
+    @Override
+    protected void doPost(HttpServletRequest req, HttpServletResponse resp) {
+        // tag::automatic[]
+        AsyncContext asyncContext = req.startAsync();
+        asyncContext.start(WebLoggerContextUtils.wrapExecutionContext(getServletContext(), () -> {
+            // Put your logic here
+        }));
+        // end::automatic[]
+    }
+}

src/site/antora/modules/ROOT/examples/manual/webapp/jndi.xml

@@ -0,0 +1,37 @@
+<?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.
+  -->
+<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
+         version="5.0">
+  <!-- tag::jndi[] -->
+  <context-param>
+    <param-name>isLog4jContextSelectorNamed</param-name>
+    <param-value>true</param-value>
+  </context-param>
+  <context-param>
+    <param-name>log4jContextName</param-name>
+    <param-value>your_application_name</param-value>
+  </context-param>
+  <env-entry>
+    <env-entry-name>log4j/context-name</env-entry-name>
+    <env-entry-value>your_application_name</env-entry-value>
+    <env-entry-type>java.lang.String</env-entry-type>
+  </env-entry>
+  <!-- end::jndi[] -->
+</web-app>

src/site/antora/modules/ROOT/examples/manual/webapp/log4j2-single.json

@@ -0,0 +1,48 @@
+{
+  "Configuration": {
+    "Appenders": {
+      // tag::global[]
+      "File": {
+        "name": "GLOBAL",
+        "fileName": "logs/global.log",
+        "JsonTemplateLayout": {
+          "EventTemplateAdditionalField": {
+            "key": "contextName",
+            "value": "$${web:contextName}"
+          }
+        }
+      },
+      // end::global[]
+      // tag::routing[]
+      "Routing": {
+        "name": "ROUTING",
+        "Routes": {
+          "pattern": "$${web:contextName:-common}",
+          "Route": {
+            "File": {
+              "name": "${web:contextName:-common}",
+              "fileName": "logs/${web:contextName:-common}.log",
+              "PatternLayout": {
+                "pattern": "d [%t] %-5p %c - %m%n"
+              }
+            }
+          }
+        }
+      }
+      // end::routing[]
+    },
+    "Loggers": {
+      "Route": {
+        "level": "INFO",
+        "AppenderRef": [
+          {
+            "ref": "GLOBAL"
+          },
+          {
+            "ref": "ROUTING"
+          }
+        ]
+      }
+    }
+  }
+}

src/site/antora/modules/ROOT/examples/manual/webapp/log4j2-single.properties

@@ -0,0 +1,41 @@
+#
+# 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.
+#
+##
+# tag::global[]
+appender.0.type = File
+appender.0.name = GLOBAL
+appender.0.fileName = logs/global
+appender.0.layout.type = JsonTemplateLayout
+appender.0.layout.0.type = EventTemplateAdditionalField
+appender.0.layout.0.key = contextName
+appender.0.layout.0.value = $${web:contextName}
+# end::global[]
+# tag::routing[]
+appender.1.type = Routing
+appender.1.name = ROUTING
+appender.1.route.type = Routes
+appender.1.route.pattern = $${web:contextName:-common}
+appender.1.route.0.type = Route
+appender.1.route.0.appender.type = File
+appender.1.route.0.appender.name = ${web:contextName:-common}
+appender.1.route.0.appender.fileName = logs/${web:contextName:-common}.log
+appender.1.route.0.appender.layout.type = PatternLayout
+appender.1.route.0.appender.layout.pattern = %d [%t] %-5p %c - %m%n
+# end::routing[]
+rootLogger.level = INFO
+rootLogger.appenderRef.0.ref = GLOBAL
+rootLogger.appenderRef.1.ref = ROUTING

src/site/antora/modules/ROOT/examples/manual/webapp/log4j2-single.xml

@@ -0,0 +1,49 @@
+<?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">
+  <Appenders>
+    <!-- tag::global[] -->
+    <File name="GLOBAL" fileName="logs/global.log">
+      <JsonTemplateLayout>
+        <EventTemplateAdditionalField key="contextName"
+                                      value="$${web:contextName}"/>
+      </JsonTemplateLayout>
+    </File>
+    <!-- end::global[] -->
+    <!-- tag::routing[] -->
+    <Routing name="ROUTING">
+      <Routes pattern="$${web:contextName:-common}">
+        <Route>
+          <File name="${web:contextName:-common}"
+                fileName="logs/${web:contextName:-common}.log">
+            <PatternLayout pattern="%d [%t] %-5p %c - %m%n"/>
+          </File>
+        </Route>
+      </Routes>
+    </Routing>
+    <!-- end::routing[] -->
+  </Appenders>
+  <Loggers>
+    <Root level="INFO">
+      <AppenderRef ref="GLOBAL"/>
+      <AppenderRef ref="ROUTING"/>
+    </Root>
+  </Loggers>
+</Configuration>