Skip to content

Commit aad08e6

Browse files
ppkarwaszppkarwasz
committed
Adds documentation for the Configuration Converter API
1 parent 0a603ef commit aad08e6

File tree

8 files changed

+272
-0
lines changed

8 files changed

+272
-0
lines changed

‎log4j-converter-config/pom.xml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@
2929
<description>Converts various logging configuration formats to the Log4j Core 2.x format.</description>
3030

3131
<properties>
32+
<!-- This artifact is an API: we need to generate its Javadoc -->
33+
<maven.javadoc.skip>false</maven.javadoc.skip>
34+
3235
<!-- Remove after first release -->
3336
<bnd.baseline.fail.on.missing>false</bnd.baseline.fail.on.missing>
3437

‎pom.xml‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,9 @@
108108
<!-- project version -->
109109
<revision>0.3.0-SNAPSHOT</revision>
110110

111+
<!-- disable Javadoc generation. Can be overridden in child modules -->
112+
<maven.javadoc.skip>true</maven.javadoc.skip>
113+
111114
<!-- disable `maven-site-plugin`-->
112115
<maven.site.skip>true</maven.site.skip>
113116
<maven.site.deploy.skip>true</maven.site.deploy.skip>
@@ -187,6 +190,98 @@
187190
</executions>
188191
</plugin>
189192

193+
<!-- ███████ ████████ █████ ██████ ████████ ███████ ██ ████████ ███████
194+
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
195+
███████ ██ ███████ ██████ ██ ███████ ██ ██ █████
196+
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
197+
███████ ██ ██ ██ ██ ██ ██ ███████ ██ ██ ███████
198+
199+
This section consists of plugins responsible for generating the site.
200+
Note that only this (i.e., the root) module is supposed to have a `site` goal, it is skipped for all other modules! -->
201+
202+
<!-- Remove the Maven Site Plugin execution -->
203+
<plugin>
204+
<groupId>org.apache.maven.plugins</groupId>
205+
<artifactId>maven-site-plugin</artifactId>
206+
<executions>
207+
<execution>
208+
<id>default-site</id>
209+
<phase>none</phase>
210+
</execution>
211+
</executions>
212+
</plugin>
213+
<!--
214+
~ JAVADOC GENERATION
215+
~ 1. Define `currentYear` property used by the `maven-javadoc-plugin` configuration
216+
-->
217+
<plugin>
218+
<groupId>org.codehaus.mojo</groupId>
219+
<artifactId>build-helper-maven-plugin</artifactId>
220+
<executions>
221+
<execution>
222+
<id>define-currentYear-property</id>
223+
<goals>
224+
<goal>timestamp-property</goal>
225+
</goals>
226+
<phase>pre-site</phase>
227+
<inherited>false</inherited>
228+
<configuration>
229+
<name>currentYear</name>
230+
<pattern>yyyy</pattern>
231+
<locale>en_US</locale>
232+
</configuration>
233+
</execution>
234+
</executions>
235+
</plugin>
236+
<!-- 2. Generate the JavaDoc -->
237+
<plugin>
238+
<groupId>org.apache.maven.plugins</groupId>
239+
<artifactId>maven-javadoc-plugin</artifactId>
240+
<executions>
241+
<execution>
242+
<id>generate-site-javadoc</id>
243+
<goals>
244+
<goal>javadoc-no-fork</goal>
245+
</goals>
246+
<phase>pre-site</phase>
247+
<configuration combine.self="override">
248+
<!-- `notimestamp` avoids `diff` noise and is required for reproducible builds: https://maven.apache.org/guides/mini/guide-reproducible-builds.html -->
249+
<notimestamp>true</notimestamp>
250+
<skip>${maven.javadoc.skip}</skip>
251+
<bottom><![CDATA[<p align="center">
252+
Copyright &copy; {inceptionYear}-{currentYear} {organizationName}.
253+
All Rights Reserved.<br/>
254+
Apache, Log4j, and the Apache feather logo are trademarks or registered trademarks of {organizationName}.
255+
Oracle and Java are registered trademarks of Oracle and/or its affiliates.
256+
Other names may be trademarks of their respective owners.
257+
</p>]]></bottom>
258+
</configuration>
259+
</execution>
260+
</executions>
261+
</plugin>
262+
<!-- 3. Move the JavaDoc to the main module -->
263+
<plugin>
264+
<groupId>org.apache.maven.plugins</groupId>
265+
<artifactId>maven-resources-plugin</artifactId>
266+
<executions>
267+
<execution>
268+
<id>copy-javadoc</id>
269+
<goals>
270+
<goal>copy-resources</goal>
271+
</goals>
272+
<phase>pre-site</phase>
273+
<configuration>
274+
<outputDirectory>${maven.multiModuleProjectDirectory}/target/site/javadoc/${project.artifactId}</outputDirectory>
275+
<resources>
276+
<resource>
277+
<directory>target/site/apidocs</directory>
278+
</resource>
279+
</resources>
280+
</configuration>
281+
</execution>
282+
</executions>
283+
</plugin>
284+
190285
</plugins>
191286
</build>
192287

‎src/changelog/.0.x.x/add-config-converter.xml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<entry xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
xmlns="https://logging.apache.org/xml/ns"
4+
xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-changelog-0.xsd"
5+
type="added">
6+
<description format="asciidoc">
7+
Add `log4j-codegen` tool to generate custom loggers.
8+
</description>
9+
</entry>

‎src/site/antora/antora.tmpl.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ asciidoc:
4444
project-id: "log4j-transform"
4545
java-target-version: "${maven.compiler.target}"
4646
java-compiler-version: "${minimalJavaBuildVersion}"
47+
examples-url: "https://github.com/apache/logging-log4j-transform/blob/main/src/site/antora/modules/ROOT/examples"
4748
logging-services-url: "https://logging.apache.org"
4849
nav:
4950
- modules/ROOT/nav.adoc

‎src/site/antora/antora.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ asciidoc:
4444
project-id: "log4j-transform"
4545
java-target-version: "8"
4646
java-compiler-version: "[17,18)"
47+
examples-url: "https://github.com/apache/logging-log4j-transform/blob/main/src/site/antora/modules/ROOT/examples"
4748
logging-services-url: "https://logging.apache.org"
4849
nav:
4950
- modules/ROOT/nav.adoc

‎src/site/antora/modules/ROOT/examples/log4j-converter-config/Main.java‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
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 example;
18+
19+
import java.io.IOException;
20+
import java.io.InputStream;
21+
import java.io.OutputStream;
22+
import java.nio.file.Files;
23+
import java.nio.file.Path;
24+
import java.nio.file.Paths;
25+
import org.apache.logging.converter.config.ConfigurationConverter;
26+
import org.apache.logging.converter.config.ConfigurationConverterException;
27+
28+
public final class Main {
29+
30+
public static void main(String[] args) {
31+
if (args.length != 4) {
32+
System.err.println("Usage: java -jar main.jar <inputFile> <inputFormat> <outputFile> <outputFormat>");
33+
System.exit(1);
34+
}
35+
try {
36+
convert(args[0], args[1], args[2], args[3]);
37+
} catch (ConfigurationConverterException | IOException e) {
38+
System.err.println("Failed to convert " + args[0] + " to " + args[2] + ".");
39+
e.printStackTrace(System.err);
40+
}
41+
}
42+
43+
// tag::convert[]
44+
private static void convert(String inputFile, String inputFormat, String outputFile, String outputFormat)
45+
throws ConfigurationConverterException, IOException {
46+
Path input = Paths.get(inputFile);
47+
Path output = Paths.get(outputFile);
48+
try (InputStream inputStream = Files.newInputStream(input);
49+
OutputStream outputStream = Files.newOutputStream(output)) {
50+
ConfigurationConverter converter = ConfigurationConverter.getInstance();
51+
converter.convert(inputStream, inputFormat, outputStream, outputFormat);
52+
}
53+
}
54+
// end::convert[]
55+
56+
private Main() {}
57+
}

‎src/site/antora/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
* Components
1919
** xref:cli.adoc[]
2020
** xref:log4j-transform-maven-plugin.adoc[]
21+
** xref:log4j-converter-config.adoc[]
2122
** xref:log4j-transform-maven-shade-plugin-extensions.adoc[]
2223
* xref:development.adoc[]
2324
* xref:release-notes.adoc[]

‎src/site/antora/modules/ROOT/pages/log4j-converter-config.adoc‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
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+
18+
= Log4j Configuration Converter API
19+
20+
To help users migrate between
21+
{logging-services-url}/log4j/2.x/manual/installation.html#concepts[logging implementations]
22+
the Log4j Configuration Converter offers a simple API to convert configuration files from one format to another.
23+
24+
[#api]
25+
== Using the API
26+
27+
The API is based on a single
28+
link:javadoc/log4j-converter-config/org/apache/logging/log4j/converter/config/ConfigurationConverter.html[`ConfigurationConverter`]
29+
interface.
30+
To use it, first import the `log4j-converter-config` artifact to your project.
31+
32+
[tabs]
33+
====
34+
Maven::
35+
+
36+
[source,xml,subs="+attributes"]
37+
----
38+
<plugin>
39+
<groupId>org.apache.logging.log4j</groupId>
40+
<artifactId>log4j-converter-config</artifactId>
41+
<version>{project-version}</version>
42+
</plugin>
43+
----
44+
45+
Gradle::
46+
+
47+
[source,groovy,subs="+attributes"]
48+
----
49+
implementation 'org.apache.logging.log4j:log4j-converter-config:{project-version}'
50+
----
51+
====
52+
53+
You can access the main functionality of the library through the
54+
link:javadoc/log4j-converter-config/org/apache/logging/converter/config/ConfigurationConverter.html#convert(java.io.InputStream,java.lang.String,java.io.OutputStream,java.lang.String)[ConfigurationConverter.convert()]
55+
method, as shown in the example below:
56+
57+
.Snippet from a {examples-url}/log4j-converter-config/Main.java[`Main.java`] CLI example
58+
[source,java,indent=0]
59+
----
60+
include::example$log4j-converter-config/Main.java[tag=convert]
61+
----
62+
63+
[#formats]
64+
== Supported configuration formats
65+
66+
The configuration converter is extensible by third-parties using the
67+
link:javadoc/log4j-converter-config/org/apache/logging/converter/config/spi/ConfigurationParser.html[`ConfigurationParser`]
68+
and
69+
link:javadoc/log4j-converter-config/org/apache/logging/converter/config/spi/ConfigurationWriter.html[`ConfigurationWriter`]
70+
interfaces from the
71+
link:javadoc/log4j-converter-config/org/apache/logging/converter/config/spi/package-summary.html[`o.a.l.l.converter.config.spi`]
72+
package.
73+
74+
The library provides an out-of-the-box support for the following configuration formats
75+
76+
.List of supported configuration formats
77+
[%header,cols="2h,1m,1,1"]
78+
|===
79+
| Format name | Format id | Parsing support | Writing support
80+
81+
| {logging-services-url}/log4j/2.x/manual/configuration.html#xml[Log4j Core 2 XML]
82+
| v2:xml
83+
| yes
84+
| yes
85+
86+
| {logging-services-url}/log4j/2.x/manual/configuration.html#json[Log4j Core 2 JSON]
87+
| v2:json
88+
| yes
89+
| yes
90+
91+
| {logging-services-url}/log4j/2.x/manual/configuration.html#yaml[Log4j Core 2 YAML]
92+
| v2:yaml
93+
| yes
94+
| yes
95+
96+
| {logging-services-url}/log4j/2.x/manual/configuration.html#xml[Log4j Core 2 Properties]
97+
| v2:properties
98+
| yes
99+
| no
100+
101+
| {logging-services-url}/log4j/2.x/manual/configuration.html#xml[Log4j Core 3 Properties]
102+
| v3:properties
103+
| yes
104+
| yes
105+
|===

0 commit comments

Comments
 (0)