Adds a log4j-transform-cli tool

This PR adds a simple `picocli`-based tool to access the Configuration Converter API from the command line.
Currently, two commands are available:

- `configFile listFormats` lists the available configuration file formats.
- `configFile convert` converts configuration files from one format to another (e.g., a Log4j 1 Properties file to a Log4j 2 Core XML file).

Part of apache/logging-log4j2#3220

Author: ppkarwasz

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);