Revamp the Extending, Plugins, Architecture, and Programmatic configuration pages

src/site/antora/modules/ROOT/examples/manual/customconfig/ConfigurationBuilder/log4j2.json

@@ -0,0 +1,18 @@
+{
+  "Configuration": {
+    "Appenders": {
+      "Console": {
+        "name": "CONSOLE",
+        "JsonTemplateLayout": {}
+      }
+    },
+    "Loggers": {
+      "Root": {
+        "level": "WARN",
+        "AppenderRef": {
+          "ref": "CONSOLE"
+        }
+      }
+    }
+  }
+}

src/site/antora/modules/ROOT/examples/manual/customconfig/ConfigurationBuilder/log4j2.properties

@@ -0,0 +1,22 @@
+#
+# 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 = CONSOLE
+appender.0.layout.type = JsonTemplateLayout
+
+rootLogger.level = WARN
+rootLogger.appenderRef.0.ref = CONSOLE

src/site/antora/modules/ROOT/examples/manual/customconfig/ConfigurationBuilder/log4j2.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">
+
+  <Appenders>
+    <Console name="CONSOLE">
+      <JsonTemplateLayout/>
+    </Console>
+  </Appenders>
+
+  <Loggers>
+    <Root level="WARN">
+      <AppenderRef ref="CONSOLE"/>
+    </Root>
+  </Loggers>
+
+</Configuration>

src/site/antora/modules/ROOT/examples/manual/customconfig/ConfigurationBuilder/log4j2.yaml

@@ -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.
+#
+Configuration:
+
+  Appenders:
+    Console:
+      name: "CONSOLE"
+      JsonTemplateLayout: {}
+
+  Loggers:
+    Root:
+      level: "WARN"
+      AppenderRef:
+        ref: "CONSOLE"

src/site/antora/modules/ROOT/examples/manual/customconfig/ExampleConfiguration.java

@@ -0,0 +1,47 @@
+/*
+ * 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 com.example;
+
+import org.apache.logging.log4j.Level;
+import org.apache.logging.log4j.core.Appender;
+import org.apache.logging.log4j.core.LoggerContext;
+import org.apache.logging.log4j.core.config.AppenderRef;
+import org.apache.logging.log4j.core.config.ConfigurationSource;
+import org.apache.logging.log4j.core.config.LoggerConfig;
+
+public class ExampleConfiguration extends XmlConfiguration {
+
+    public ExampleConfiguration(LoggerContext loggerContext, ConfigurationSource configSource) {
+        super(loggerContext, configSource);
+    }
+
+    @Override
+    protected void doConfigure() {
+        Appender appender = createAppender("ExampleAppender");
+        appender.start();
+        addAppender(appender);
+        LoggerConfig loggerConfig = LoggerConfig.newBuilder()
+                .withConfig(this)
+                .withAdditivity(false)
+                .withLevel(Level.INFO)
+                .withLoggerName("com.example")
+                .withRefs(new AppenderRef[] {AppenderRef.createAppenderRef("ExampleAppender", null, null)})
+                .build();
+        loggerConfig.addAppender(appender, null, null);
+        addLogger("com.example", loggerConfig);
+    }
+}

src/site/antora/modules/ROOT/examples/manual/customconfig/ExampleConfigurationFactory.java

@@ -0,0 +1,46 @@
+/*
+ * 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 com.example;
+
+import org.apache.logging.log4j.core.LoggerContext;
+import org.apache.logging.log4j.core.config.Configuration;
+import org.apache.logging.log4j.core.config.ConfigurationFactory;
+import org.apache.logging.log4j.core.config.ConfigurationSource;
+import org.apache.logging.log4j.core.config.Order;
+import org.apache.logging.log4j.core.config.plugins.Plugin;
+
+// tag::class[]
+@Order(100)
+@Plugin(name = "ExampleConfigurationFactory", category = ConfigurationFactory.CATEGORY)
+public class ExampleConfigurationFactory extends ConfigurationFactory {
+
+    @Override
+    public Configuration getConfiguration(LoggerContext loggerContext, ConfigurationSource source) { // <1>
+        // Return a `Configuration`...
+    }
+
+    @Override
+    public Configuration getConfiguration(LoggerContext loggerContext, String name, URI configLocation) {
+        // Return a `Configuration`...
+    }
+
+    @Override
+    public String[] getSupportedTypes() {
+        return new String[] {"*"};
+    }
+}
+// end::class[]

src/site/antora/modules/ROOT/examples/manual/customconfig/Usage.java

@@ -0,0 +1,90 @@
+/*
+ * 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 com.example;
+
+import java.net.URI;
+import java.util.Arrays;
+import org.apache.logging.log4j.Level;
+import org.apache.logging.log4j.core.LoggerContext;
+import org.apache.logging.log4j.core.config.AbstractConfiguration;
+import org.apache.logging.log4j.core.config.Configuration;
+import org.apache.logging.log4j.core.config.ConfigurationFactory;
+import org.apache.logging.log4j.core.config.Configurator;
+import org.apache.logging.log4j.core.config.builder.api.ConfigurationBuilder;
+import org.apache.logging.log4j.core.config.builder.api.ConfigurationBuilderFactory;
+import org.apache.logging.log4j.core.config.builder.impl.BuiltConfiguration;
+import org.apache.logging.log4j.core.config.composite.CompositeConfiguration;
+
+final class Usage {
+
+    private static Configuration createConfiguration() {
+        // tag::createConfiguration[]
+        ConfigurationBuilder<BuiltConfiguration> configBuilder =
+                ConfigurationBuilderFactory.newConfigurationBuilder(); // <1>
+        Configuration configuration = configBuilder
+                .add(
+                        configBuilder // <2>
+                                .newAppender("CONSOLE", "List")
+                                .add(configBuilder.newLayout("JsonTemplateLayout")))
+                .add(
+                        configBuilder // <3>
+                                .newRootLogger(Level.WARN)
+                                .add(configBuilder.newAppenderRef("CONSOLE")))
+                .build(false); // <4>
+        // end::createConfiguration[]
+    }
+
+    private static void useConfiguration() {
+        // tag::useConfiguration[]
+        Configuration configuration = createConfiguration();
+        try (LoggerContext loggerContext = Configurator.initialize(configuration)) {
+            // Use `LoggerContext`...
+        }
+        // end::useConfiguration[]
+    }
+
+    private static void reconfigureActiveLoggerContext() {
+        // tag::reconfigureActiveLoggerContext[]
+        Configuration configuration = createConfiguration();
+        Configurator.reconfigure(configuration);
+        // end::reconfigureActiveLoggerContext[]
+    }
+
+    private static Configuration loadConfigurationFile() {
+        // tag::loadConfigurationFile[]
+        ConfigurationFactory.getInstance()
+                .getConfiguration(
+                        null, // <1>
+                        null, // <2>
+                        URI.create("uri://to/my/log4j2.xml")); // <3>
+        // end::loadConfigurationFile[]
+    }
+
+    private static Configuration combineConfigurations() {
+        // tag::combineConfigurations[]
+        ConfigurationFactory configFactory = ConfigurationFactory.getInstance();
+        AbstractConfiguration commonConfig = (AbstractConfiguration) // <2>
+                configFactory.getConfiguration(null, null, URI.create("classpath:log4j2-common.xml")); // <1>
+        AbstractConfiguration appConfig = (AbstractConfiguration) // <2>
+                configFactory.getConfiguration(null, null, URI.create("classpath:log4j2-app.xml")); // <1>
+        AbstractConfiguration runtimeConfig = ConfigurationBuilderFactory.newConfigurationBuilder()
+                // ...
+                .build(false); // <3>
+        return new CompositeConfiguration(Arrays.asList(commonConfig, appConfig, runtimeConfig)); // <4>
+        // end::combineConfigurations[]
+    }
+}

src/site/antora/modules/ROOT/pages/manual/api.adoc

@@ -85,6 +85,11 @@ include::partial$manual/api-best-practice-use-supplier.adoc[]
 link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`]s are the primary entry point for logging.
 In this section we will introduce you to further details about ``Logger``s.
 
+[TIP]
+====
+Refer to xref:manual/architecture.adoc[] to see where ``Logger``s stand in the big picture.
+====
+
 [#logger-names]
 === Logger names