Skip to content

Commit 466ac59

Browse files
vyppkarwasz
vy
and
ppkarwasz
authored
Revamp the Extending, Plugins, Architecture, and Programmatic configuration pages (#2696)
Co-authored-by: Piotr P. Karwasz <piotr.github@karwasz.org>
1 parent c977798 commit 466ac59

27 files changed

+2049
-1551
lines changed

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"Configuration": {
3+
"Appenders": {
4+
"Console": {
5+
"name": "CONSOLE",
6+
"JsonTemplateLayout": {}
7+
}
8+
},
9+
"Loggers": {
10+
"Root": {
11+
"level": "WARN",
12+
"AppenderRef": {
13+
"ref": "CONSOLE"
14+
}
15+
}
16+
}
17+
}
18+
}

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
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+
appender.0.type = Console
18+
appender.0.name = CONSOLE
19+
appender.0.layout.type = JsonTemplateLayout
20+
21+
rootLogger.level = WARN
22+
rootLogger.appenderRef.0.ref = CONSOLE

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
~ Licensed to the Apache Software Foundation (ASF) under one or more
4+
~ contributor license agreements. See the NOTICE file distributed with
5+
~ this work for additional information regarding copyright ownership.
6+
~ The ASF licenses this file to you under the Apache License, Version 2.0
7+
~ (the "License"); you may not use this file except in compliance with
8+
~ the License. You may obtain a copy of the License at
9+
~
10+
~ http://www.apache.org/licenses/LICENSE-2.0
11+
~
12+
~ Unless required by applicable law or agreed to in writing, software
13+
~ distributed under the License is distributed on an "AS IS" BASIS,
14+
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
~ See the License for the specific language governing permissions and
16+
~ limitations under the License.
17+
-->
18+
<Configuration xmlns="https://logging.apache.org/xml/ns"
19+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
20+
xsi:schemaLocation="
21+
https://logging.apache.org/xml/ns
22+
https://logging.apache.org/xml/ns/log4j-config-2.xsd">
23+
24+
<Appenders>
25+
<Console name="CONSOLE">
26+
<JsonTemplateLayout/>
27+
</Console>
28+
</Appenders>
29+
30+
<Loggers>
31+
<Root level="WARN">
32+
<AppenderRef ref="CONSOLE"/>
33+
</Root>
34+
</Loggers>
35+
36+
</Configuration>

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

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
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+
Configuration:
18+
19+
Appenders:
20+
Console:
21+
name: "CONSOLE"
22+
JsonTemplateLayout: {}
23+
24+
Loggers:
25+
Root:
26+
level: "WARN"
27+
AppenderRef:
28+
ref: "CONSOLE"

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

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
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 com.example;
18+
19+
import org.apache.logging.log4j.Level;
20+
import org.apache.logging.log4j.core.Appender;
21+
import org.apache.logging.log4j.core.LoggerContext;
22+
import org.apache.logging.log4j.core.config.AppenderRef;
23+
import org.apache.logging.log4j.core.config.ConfigurationSource;
24+
import org.apache.logging.log4j.core.config.LoggerConfig;
25+
26+
public class ExampleConfiguration extends XmlConfiguration {
27+
28+
public ExampleConfiguration(LoggerContext loggerContext, ConfigurationSource configSource) {
29+
super(loggerContext, configSource);
30+
}
31+
32+
@Override
33+
protected void doConfigure() {
34+
Appender appender = createAppender("ExampleAppender");
35+
appender.start();
36+
addAppender(appender);
37+
LoggerConfig loggerConfig = LoggerConfig.newBuilder()
38+
.withConfig(this)
39+
.withAdditivity(false)
40+
.withLevel(Level.INFO)
41+
.withLoggerName("com.example")
42+
.withRefs(new AppenderRef[] {AppenderRef.createAppenderRef("ExampleAppender", null, null)})
43+
.build();
44+
loggerConfig.addAppender(appender, null, null);
45+
addLogger("com.example", loggerConfig);
46+
}
47+
}

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

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
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 com.example;
18+
19+
import org.apache.logging.log4j.core.LoggerContext;
20+
import org.apache.logging.log4j.core.config.Configuration;
21+
import org.apache.logging.log4j.core.config.ConfigurationFactory;
22+
import org.apache.logging.log4j.core.config.ConfigurationSource;
23+
import org.apache.logging.log4j.core.config.Order;
24+
import org.apache.logging.log4j.core.config.plugins.Plugin;
25+
26+
// tag::class[]
27+
@Order(100)
28+
@Plugin(name = "ExampleConfigurationFactory", category = ConfigurationFactory.CATEGORY)
29+
public class ExampleConfigurationFactory extends ConfigurationFactory {
30+
31+
@Override
32+
public Configuration getConfiguration(LoggerContext loggerContext, ConfigurationSource source) { // <1>
33+
// Return a `Configuration`...
34+
}
35+
36+
@Override
37+
public Configuration getConfiguration(LoggerContext loggerContext, String name, URI configLocation) {
38+
// Return a `Configuration`...
39+
}
40+
41+
@Override
42+
public String[] getSupportedTypes() {
43+
return new String[] {"*"};
44+
}
45+
}
46+
// end::class[]

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

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
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 com.example;
18+
19+
import java.net.URI;
20+
import java.util.Arrays;
21+
import org.apache.logging.log4j.Level;
22+
import org.apache.logging.log4j.core.LoggerContext;
23+
import org.apache.logging.log4j.core.config.AbstractConfiguration;
24+
import org.apache.logging.log4j.core.config.Configuration;
25+
import org.apache.logging.log4j.core.config.ConfigurationFactory;
26+
import org.apache.logging.log4j.core.config.Configurator;
27+
import org.apache.logging.log4j.core.config.builder.api.ConfigurationBuilder;
28+
import org.apache.logging.log4j.core.config.builder.api.ConfigurationBuilderFactory;
29+
import org.apache.logging.log4j.core.config.builder.impl.BuiltConfiguration;
30+
import org.apache.logging.log4j.core.config.composite.CompositeConfiguration;
31+
32+
final class Usage {
33+
34+
private static Configuration createConfiguration() {
35+
// tag::createConfiguration[]
36+
ConfigurationBuilder<BuiltConfiguration> configBuilder =
37+
ConfigurationBuilderFactory.newConfigurationBuilder(); // <1>
38+
Configuration configuration = configBuilder
39+
.add(
40+
configBuilder // <2>
41+
.newAppender("CONSOLE", "List")
42+
.add(configBuilder.newLayout("JsonTemplateLayout")))
43+
.add(
44+
configBuilder // <3>
45+
.newRootLogger(Level.WARN)
46+
.add(configBuilder.newAppenderRef("CONSOLE")))
47+
.build(false); // <4>
48+
// end::createConfiguration[]
49+
}
50+
51+
private static void useConfiguration() {
52+
// tag::useConfiguration[]
53+
Configuration configuration = createConfiguration();
54+
try (LoggerContext loggerContext = Configurator.initialize(configuration)) {
55+
// Use `LoggerContext`...
56+
}
57+
// end::useConfiguration[]
58+
}
59+
60+
private static void reconfigureActiveLoggerContext() {
61+
// tag::reconfigureActiveLoggerContext[]
62+
Configuration configuration = createConfiguration();
63+
Configurator.reconfigure(configuration);
64+
// end::reconfigureActiveLoggerContext[]
65+
}
66+
67+
private static Configuration loadConfigurationFile() {
68+
// tag::loadConfigurationFile[]
69+
ConfigurationFactory.getInstance()
70+
.getConfiguration(
71+
null, // <1>
72+
null, // <2>
73+
URI.create("uri://to/my/log4j2.xml")); // <3>
74+
// end::loadConfigurationFile[]
75+
}
76+
77+
private static Configuration combineConfigurations() {
78+
// tag::combineConfigurations[]
79+
ConfigurationFactory configFactory = ConfigurationFactory.getInstance();
80+
AbstractConfiguration commonConfig = (AbstractConfiguration) // <2>
81+
configFactory.getConfiguration(null, null, URI.create("classpath:log4j2-common.xml")); // <1>
82+
AbstractConfiguration appConfig = (AbstractConfiguration) // <2>
83+
configFactory.getConfiguration(null, null, URI.create("classpath:log4j2-app.xml")); // <1>
84+
AbstractConfiguration runtimeConfig = ConfigurationBuilderFactory.newConfigurationBuilder()
85+
// ...
86+
.build(false); // <3>
87+
return new CompositeConfiguration(Arrays.asList(commonConfig, appConfig, runtimeConfig)); // <4>
88+
// end::combineConfigurations[]
89+
}
90+
}

‎src/site/antora/modules/ROOT/images/Log4jClasses.jpg

-30.7 KB
Binary file not shown.

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,11 @@ include::partial$manual/api-best-practice-use-supplier.adoc[]
8585
link:../javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`Logger`]s are the primary entry point for logging.
8686
In this section we will introduce you to further details about ``Logger``s.
8787
88+
[TIP]
89+
====
90+
Refer to xref:manual/architecture.adoc[] to see where ``Logger``s stand in the big picture.
91+
====
92+
8893
[#logger-names]
8994
=== Logger names
9095

0 commit comments

Comments
 (0)