Adds a log4j-transform-cli tool

antora-playbook.yaml

@@ -25,6 +25,7 @@ content:
     - url: .
       branches: HEAD
       start_paths:
+        - log4j-transform-cli/target/generated-site/antora
         - target/generated-site/antora
       edit_url:
 

log4j-converter-config/src/main/java/org/apache/logging/converter/config/ConfigurationConverter.java

@@ -18,6 +18,7 @@
 
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.util.Map;
 import java.util.Set;
 import org.apache.logging.converter.config.internal.DefaultConfigurationConverter;
 
@@ -55,4 +56,12 @@ void convert(InputStream inputStream, String inputFormat, OutputStream outputStr
      * Returns the list of supported output formats.
      */
     Set<String> getSupportedOutputFormats();
+
+    /**
+     * Associates each supported format symbol with a description.
+     * <p>
+     *     For self-documentation purposes.
+     * </p>
+     */
+    Map<String, String> getFormatDescriptions();
 }

log4j-converter-config/src/main/java/org/apache/logging/converter/config/internal/DefaultConfigurationConverter.java

@@ -54,6 +54,7 @@ public final class DefaultConfigurationConverter implements ConfigurationConvert
 
     private final Map<String, ConfigurationParser> parsers = new HashMap<>();
     private final Map<String, ConfigurationWriter> writers = new HashMap<>();
+    private final Map<String, String> descriptions = new HashMap<>();
 
     private DefaultConfigurationConverter() {
         ServiceLoader.load(ConfigurationParser.class).forEach(parser -> parsers.put(parser.getInputFormat(), parser));
@@ -62,6 +63,10 @@ private DefaultConfigurationConverter() {
             parsers.put(mapper.getInputFormat(), mapper);
             writers.put(mapper.getOutputFormat(), mapper);
         });
+        parsers.values()
+                .forEach(parser -> descriptions.put(parser.getInputFormat(), parser.getInputFormatDescription()));
+        writers.values()
+                .forEach(writer -> descriptions.put(writer.getOutputFormat(), writer.getOutputFormatDescription()));
     }
 
     @Override
@@ -98,4 +103,9 @@ public Set<String> getSupportedInputFormats() {
     public Set<String> getSupportedOutputFormats() {
         return Collections.unmodifiableSet(writers.keySet());
     }
+
+    @Override
+    public Map<String, String> getFormatDescriptions() {
+        return Collections.unmodifiableMap(descriptions);
+    }
 }

log4j-converter-config/src/main/java/org/apache/logging/converter/config/internal/v1/PropertiesV1ConfigurationParser.java

@@ -56,6 +56,11 @@ public String getInputFormat() {
         return LOG4J_V1_PROPERTIES_FORMAT;
     }
 
+    @Override
+    public String getInputFormatDescription() {
+        return "Log4j 1 Properties configuration file format.";
+    }
+
     @Override
     public ConfigurationNode parse(InputStream inputStream) throws IOException {
         Properties properties = new Properties();

log4j-converter-config/src/main/java/org/apache/logging/converter/config/internal/v1/XmlV1ConfigurationParser.java

@@ -61,6 +61,11 @@ public String getInputFormat() {
         return LOG4J_V1_XML_FORMAT;
     }
 
+    @Override
+    public String getInputFormatDescription() {
+        return "Log4j 1 XML configuration file format.";
+    }
+
     @Override
     public ConfigurationNode parse(InputStream inputStream) throws IOException {
         DocumentBuilder documentBuilder = XmlUtils.createDocumentBuilderV1();

log4j-converter-config/src/main/java/org/apache/logging/converter/config/internal/v2/JsonConfigurationMapper.java

@@ -34,4 +34,9 @@ public JsonConfigurationMapper() {
     public String getFormat() {
         return LOG4J_V2_JSON_FORMAT;
     }
+
+    @Override
+    public String getFormatDescription() {
+        return "Log4j Core 2 JSON configuration format.";
+    }
 }

log4j-converter-config/src/main/java/org/apache/logging/converter/config/internal/v2/PropertiesV2ConfigurationParser.java

@@ -70,6 +70,11 @@ public String getInputFormat() {
         return LOG4J_V2_PROPERTIES_FORMAT;
     }
 
+    @Override
+    public String getInputFormatDescription() {
+        return "Log4j Core 2 Properties configuration format.";
+    }
+
     @Override
     public ConfigurationNode parse(InputStream inputStream) throws IOException {
         Properties rootProperties = new Properties();

log4j-converter-config/src/main/java/org/apache/logging/converter/config/internal/v2/XmlConfigurationMapper.java

@@ -108,6 +108,11 @@ public String getFormat() {
         return LOG4J_V2_XML_FORMAT;
     }
 
+    @Override
+    public String getFormatDescription() {
+        return "Log4j Core 2 XML configuration format.";
+    }
+
     private static XMLStreamWriter createStreamWriter(OutputStream outputStream) throws IOException {
         XMLOutputFactory outputFactory = XMLOutputFactory.newFactory();
         try {

log4j-converter-config/src/main/java/org/apache/logging/converter/config/internal/v2/YamlConfigurationMapper.java

@@ -40,4 +40,9 @@ public YamlConfigurationMapper() {
     public String getFormat() {
         return LOG4J_V2_YAML_FORMAT;
     }
+
+    @Override
+    public String getFormatDescription() {
+        return "Log4j Core 2 YAML configuration format.";
+    }
 }

log4j-converter-config/src/main/java/org/apache/logging/converter/config/internal/v3/PropertiesV3ConfigurationMapper.java

@@ -44,6 +44,11 @@ public String getFormat() {
         return LOG4J_V3_PROPERTIES_FORMAT;
     }
 
+    @Override
+    public String getFormatDescription() {
+        return "Log4j Core 3 Properties configuration format.";
+    }
+
     @Override
     public ConfigurationNode parse(InputStream inputStream) throws IOException {
         return super.parse(inputStream);

log4j-converter-config/src/main/java/org/apache/logging/converter/config/spi/ConfigurationMapper.java

@@ -35,13 +35,28 @@ public interface ConfigurationMapper extends ConfigurationParser, ConfigurationW
      */
     String getFormat();
 
+    /**
+     * A description of the supported format for self-documentation purposes.
+     */
+    String getFormatDescription();
+
     @Override
     default String getInputFormat() {
         return getFormat();
     }
 
+    @Override
+    default String getInputFormatDescription() {
+        return getFormatDescription();
+    }
+
     @Override
     default String getOutputFormat() {
         return getFormat();
     }
+
+    @Override
+    default String getOutputFormatDescription() {
+        return getFormatDescription();
+    }
 }

log4j-converter-config/src/main/java/org/apache/logging/converter/config/spi/ConfigurationParser.java

@@ -37,6 +37,11 @@ public interface ConfigurationParser {
      */
     String getInputFormat();
 
+    /**
+     * A description of the supported format for self-documentation purposes.
+     */
+    String getInputFormatDescription();
+
     /**
      * Parses a configuration file into a tree of configuration nodes.
      * <p>

log4j-converter-config/src/main/java/org/apache/logging/converter/config/spi/ConfigurationWriter.java

@@ -37,6 +37,11 @@ public interface ConfigurationWriter {
      */
     String getOutputFormat();
 
+    /**
+     * A description of the supported format for self-documentation purposes.
+     */
+    String getOutputFormatDescription();
+
     /**
      * Write a tree of configuration nodes to a configuration file.
      * <p>

log4j-transform-cli/.picocli-application-activator

@@ -0,0 +1,17 @@
+#
+# 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.
+#
+This file activates the `picocli` profile

log4j-transform-cli/pom.xml

@@ -0,0 +1,131 @@
+<?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.
+  -->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>org.apache.logging.log4j</groupId>
+    <artifactId>log4j-transform-parent</artifactId>
+    <version>${revision}</version>
+    <relativePath>../log4j-transform-parent</relativePath>
+  </parent>
+
+  <artifactId>log4j-transform-cli</artifactId>
+  <name>Apache Log4j Transform CLI</name>
+  <description>The Apache Log4j Transform CLI tool provides access to other Log4j Transform modules such as conversion
+    between
+    configuration formats and plugin descriptors.</description>
+
+  <properties>
+    <!-- Remove after first release -->
+    <bnd.baseline.fail.on.missing>false</bnd.baseline.fail.on.missing>
+
+    <!-- Dependency versions -->
+    <commons-cli.version>1.9.0</commons-cli.version>
+
+    <!-- Main class -->
+    <Main-Class>org.apache.logging.log4j.transform.cli.Main</Main-Class>
+  </properties>
+
+  <dependencies>
+
+    <dependency>
+      <groupId>commons-cli</groupId>
+      <artifactId>commons-cli</artifactId>
+      <version>${commons-cli.version}</version>
+    </dependency>
+
+    <dependency>
+      <groupId>info.picocli</groupId>
+      <artifactId>picocli</artifactId>
+    </dependency>
+
+    <dependency>
+      <groupId>org.apache.logging.log4j</groupId>
+      <artifactId>log4j-converter-config</artifactId>
+    </dependency>
+
+  </dependencies>
+
+  <build>
+    <plugins>
+
+      <!--
+        ~ SITE section
+        ~
+        ~ Since currently the website is built using `./mvnw install && ./mvnw site`, we need to bind these plugins
+        ~ to the default lifecycle.
+        ~ Plugins in the site lifecycle will be executed **after** those of the project's reactor and therefore their
+        ~ result will be ignored.
+        -->
+
+      <!-- Copies the `antora.yml` file to the generated Antora directory structure -->
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-resources-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>copy-antora</id>
+            <goals>
+              <goal>copy-resources</goal>
+            </goals>
+            <phase>process-resources</phase>
+            <configuration>
+              <outputDirectory>target/generated-site/antora</outputDirectory>
+              <resources>
+                <resource>
+                  <directory>src/antora</directory>
+                </resource>
+              </resources>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+      <!-- Generates the man pages for the commands -->
+      <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>exec-maven-plugin</artifactId>
+        <dependencies>
+          <dependency>
+            <groupId>info.picocli</groupId>
+            <artifactId>picocli-codegen</artifactId>
+            <version>${picocli.version}</version>
+          </dependency>
+        </dependencies>
+        <executions>
+          <execution>
+            <id>generate-man-pages</id>
+            <goals>
+              <goal>java</goal>
+            </goals>
+            <phase>process-classes</phase>
+            <configuration>
+              <includePluginDependencies>true</includePluginDependencies>
+              <mainClass>picocli.codegen.docgen.manpage.ManPageGenerator</mainClass>
+              <arguments>
+                <arg>-d</arg>
+                <arg>${project.build.directory}/generated-site/antora/modules/ROOT/partials</arg>
+                <arg>org.apache.logging.log4j.transform.cli.ConfigurationFileCommands</arg>
+              </arguments>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+
+    </plugins>
+  </build>
+</project>

log4j-transform-cli/src/antora/antora.yml

@@ -0,0 +1,24 @@
+#
+# 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.
+#
+
+#
+# This Antora module is only used as a container for automatically generated `partials`
+#
+
+name: cli
+title: Log4j Transform CLI Tools
+version: ~

log4j-transform-cli/src/antora/modules/ROOT/partials/config-file-convert.adoc

@@ -0,0 +1,21 @@
+////
+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
+
+    https://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.
+////
+
+= config-file-convert(1)
+
+This is a dummy file to help validation in an IDE.
+Its content will be generated by `picocli-codegen`.