rewrote Markers

pom.xml

@@ -605,6 +605,23 @@
         </configuration>
       </plugin>
 
+      <!--
+        ~ Adds Antora examples to the list of checked files
+        -->
+      <plugin>
+        <groupId>com.diffplug.spotless</groupId>
+        <artifactId>spotless-maven-plugin</artifactId>
+        <configuration>
+          <java>
+            <includes>
+              <include>src/main/java/**/*.java</include>
+              <include>src/test/java/**/*.java</include>
+              <include>src/site/antora/modules/ROOT/examples/**/*.java</include>
+            </includes>
+          </java>
+        </configuration>
+      </plugin>
+
       <!-- ███████ ████████  █████  ██████  ████████        ███████ ██ ████████ ███████
            ██         ██    ██   ██ ██   ██    ██    ██     ██      ██    ██    ██
            ███████    ██    ███████ ██████     ██           ███████ ██    ██    █████

src/site/antora/antora.tmpl.yml

@@ -39,6 +39,7 @@ start_page: index.adoc
 asciidoc:
   attributes:
     # Commons
+    antora-examples-url: "https://raw.githubusercontent.com/apache/logging-log4j2/2.x/src/site/antora/modules/ROOT/examples"
     project-github-url: "${scm.url}"
     project-name: "Log4j"
     project-id: "log4j"

src/site/antora/antora.yml

@@ -39,7 +39,8 @@ start_page: index.adoc
 asciidoc:
   attributes:
     # Commons
-    project-github-url: "https://github.com/apache/logging-log4j2"
+    antora-examples-url: "https://raw.githubusercontent.com/apache/logging-log4j2/2.x/src/site/antora/modules/ROOT/examples"
+    project-github-url: "https://github.com/apache/logging-log4j2/"
     project-name: "Log4j"
     project-id: "log4j"
     java-target-version: "8"

src/site/antora/modules/ROOT/examples/manual/markers/MarkerExample.java

@@ -0,0 +1,63 @@
+/*
+ * 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;
+import org.apache.logging.log4j.Marker;
+import org.apache.logging.log4j.MarkerManager;
+
+public final class MarkerExample {
+
+    private static final Logger logger = LogManager.getLogger("example.MarkerExample");
+    // tag::create-marker[]
+    private static final Marker SQL_MARKER = MarkerManager.getMarker("SQL");
+    // end::create-marker[]
+    // tag::create-marker-parent[]
+    private static final Marker QUERY_MARKER =
+            MarkerManager.getMarker("SQL_QUERY").addParents(SQL_MARKER);
+    private static final Marker UPDATE_MARKER =
+            MarkerManager.getMarker("UPDATE").addParents(SQL_MARKER);
+    // end::create-marker-parent[]
+
+    public static void main(final String[] args) {
+        doQuery("my_table");
+        doQueryParent("my_table");
+        doUpdate("my_table", "column", "value");
+    }
+
+    public static void doQuery(String table) {
+        // Do business logic here
+        // tag::use-marker[]
+        logger.debug(SQL_MARKER, "SELECT * FROM {}", table);
+        // end::use-marker[]
+    }
+
+    public static void doQueryParent(String table) {
+        // Do business logic here
+        // tag::use-marker-parent[]
+        logger.debug(QUERY_MARKER, "SELECT * FROM {}", table);
+        // end::use-marker-parent[]
+    }
+
+    public static void doUpdate(String table, String column, String value) {
+        // Do business logic here
+        // tag::use-marker-parent[]
+        logger.debug(UPDATE_MARKER, "UPDATE {} SET {} = {}", table, column, value);
+        // end::use-marker-parent[]
+    }
+}

src/site/antora/modules/ROOT/examples/manual/markers/log4j2.json

@@ -0,0 +1,31 @@
+{
+  "Configuration": {
+    "Appenders": {
+      "Console": {
+        "name": "SQL_LOG",
+        "PatternLayout": {
+          "pattern": "%d{HH:mm:ss.SSS} (%marker) %m%n"
+        }
+      }
+    },
+    "Loggers": {
+      "Root": {
+        "level": "INFO"
+      },
+      // tag::logger[]
+      "Logger": {
+        "name": "example",
+        "level": "ALL", // <1>
+        "AppenderRef": {
+          "ref": "SQL_LOG",
+          "MarkerFilter": { // <2>
+            "marker": "SQL",
+            "onMatch": "ACCEPT",
+            "onMismatch": "DENY"
+          }
+        }
+      }
+      // end::logger[]
+    }
+  }
+}

src/site/antora/modules/ROOT/examples/manual/markers/log4j2.properties

@@ -0,0 +1,34 @@
+#
+# 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.
+#
+appender.0.type = Console
+appender.0.name = SQL_LOG
+appender.0.layout.type = PatternLayout
+appender.0.layout.pattern = %d{HH:mm:ss.SSS} (%marker) %m%n
+
+rootLogger.level = INFO
+
+# tag::logger[]
+logger.0.name = example
+# <1>
+logger.0.level = ALL
+logger.0.appenderRef.0.ref = SQL_LOG
+# <2>
+logger.0.appenderRef.0.filter.type = MarkerFilter
+logger.0.appenderRef.0.filter.marker = SQL
+logger.0.appenderRef.0.filter.onMatch = ACCEPT
+logger.0.appenderRef.0.filter.onMismatch = DENY
+# end::logger[]

src/site/antora/modules/ROOT/examples/manual/markers/log4j2.xml

@@ -0,0 +1,43 @@
+<?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>
+    <Console name="SQL_LOG">
+      <PatternLayout pattern="%d{HH:mm:ss.SSS} (%marker) %m%n"/>
+    </Console>
+  </appenders>
+
+  <loggers>
+    <root level="INFO"/>
+    <!-- tag::logger[] -->
+    <logger name="example" level="ALL"><!--1-->
+      <AppenderRef ref="SQL_LOG">
+        <MarkerFilter marker="SQL"
+                      onMatch="ACCEPT"
+                      onMismatch="DENY"/><!--2-->
+      </AppenderRef>
+    </logger>
+    <!-- end::logger[] -->
+  </loggers>
+
+</Configuration>

src/site/antora/modules/ROOT/examples/manual/markers/log4j2.yaml

@@ -0,0 +1,36 @@
+#
+# 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:
+    Console:
+      name: "SQL_LOG"
+      PatternLayout:
+        pattern: "%d{HH:mm:ss.SSS} (%marker) %m%n"
+  Loggers:
+    Root:
+      level: "INFO"
+    # tag::logger[]
+    Logger:
+      name: "example"
+      level: "ALL" # <1>
+      AppenderRef:
+        ref: "SQL_LOG"
+        MarkerFilter: # <2>
+          marker: "SQL"
+          onMatch: "ACCEPT"
+          onMismatch: DENY
+    # end::logger[]

src/site/antora/modules/ROOT/examples/manual/markers/marker-filtering.log

@@ -0,0 +1,23 @@
+#
+# 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::use-marker[]
+10:42:30.982 (SQL) SELECT * FROM my_table
+# end::use-marker[]
+# tag::use-marker-parent[]
+10:42:30.982 (SQL_QUERY[ SQL ]) SELECT * FROM my_table
+10:42:30.982 (SQL_UPDATE[ SQL ]) UPDATE my_table SET column = value
+# end::use-marker-parent[]