Introduce log4j-docgen-type-target-template argument to ApirefMacro

apache · Mar 21, 2024 · cb98f92 · cb98f92
1 parent 982e613
commit cb98f92
Show file tree

Hide file tree

Showing 5 changed files with 50 additions and 24 deletions.
diff --git a/log4j-docgen-asciidoctor-extension/pom.xml b/log4j-docgen-asciidoctor-extension/pom.xml
@@ -42,6 +42,11 @@
       <artifactId>log4j-docgen</artifactId>
     </dependency>
 
+    <dependency>
+      <groupId>org.apache.logging.log4j</groupId>
+      <artifactId>log4j-tools-internal-freemarker-util</artifactId>
+    </dependency>
+
     <dependency>
       <groupId>org.jspecify</groupId>
       <artifactId>jspecify</artifactId>

diff --git a/...ctor-extension/src/main/java/org/apache/logging/log4j/docgen/asciidoctor/ApirefMacro.java b/...ctor-extension/src/main/java/org/apache/logging/log4j/docgen/asciidoctor/ApirefMacro.java
@@ -16,6 +16,8 @@
  */
 package org.apache.logging.log4j.docgen.asciidoctor;
 
+import static java.util.Collections.singletonMap;
+
 import java.io.IOException;
 import java.io.UncheckedIOException;
 import java.nio.file.FileSystems;
@@ -36,6 +38,7 @@
 import org.apache.logging.log4j.docgen.generator.internal.ArtifactSourcedType;
 import org.apache.logging.log4j.docgen.generator.internal.TypeLookup;
 import org.apache.logging.log4j.docgen.io.stax.PluginBundleStaxReader;
+import org.apache.logging.log4j.tools.internal.freemarker.util.FreeMarkerUtils;
 import org.asciidoctor.ast.PhraseNode;
 import org.asciidoctor.ast.StructuralNode;
 import org.asciidoctor.extension.Format;
@@ -59,7 +62,7 @@ public final class ApirefMacro extends InlineMacroProcessor {
 
     private TypeLookup lookup;
 
-    private String typeTemplateTarget;
+    private String typeTargetTemplate;
 
     private boolean packageNameStripped;
 
@@ -97,14 +100,8 @@ private PhraseNode createPhraseNode(
     }
 
     private String createTypeTemplateTargetPath(final ArtifactSourcedType sourcedType) {
-        final String groupId = or(sourcedType.groupId, "unknown-groupId");
-        final String artifactId = or(sourcedType.artifactId, "unknown-artifactId");
-        final String version = or(sourcedType.version, "unknown-version");
-        return typeTemplateTarget
-                .replaceAll("%g", groupId)
-                .replaceAll("%a", artifactId)
-                .replaceAll("%v", version)
-                .replaceAll("%c", sourcedType.type.getClassName());
+        final Map<String, ArtifactSourcedType> templateData = singletonMap("sourcedType", sourcedType);
+        return FreeMarkerUtils.renderString(typeTargetTemplate, templateData);
     }
 
     private static String or(@Nullable final String value, final String fallback) {
@@ -116,7 +113,7 @@ private void initialize(final StructuralNode node) {
             LOGGER.fine("Initializing...");
             lookup = createTypeLookup(node);
             final Map<String, Object> documentAttributes = node.getDocument().getAttributes();
-            typeTemplateTarget = getStringAttribute(documentAttributes, attributeName("type-template-target"), null);
+            typeTargetTemplate = getStringAttribute(documentAttributes, attributeName("type-target-template"), null);
             packageNameStripped =
                     isBooleanAttributeProvided(documentAttributes, attributeName("package-name-stripped"));
             initialized = true;

diff --git a/...-extension/src/test/java/org/apache/logging/log4j/docgen/asciidoctor/ApirefMacroTest.java b/...-extension/src/test/java/org/apache/logging/log4j/docgen/asciidoctor/ApirefMacroTest.java
@@ -31,7 +31,9 @@ class ApirefMacroTest {
 
     private final AttributesBuilder attributesBuilder = Attributes.builder()
             .attribute("log4j-docgen-descriptor-directory", "src/test/resources/" + TEST_NAME + "/plugins.xml")
-            .attribute("log4j-docgen-type-template-target", "%g/%a/%c.html");
+            .attribute(
+                    "log4j-docgen-type-target-template",
+                    "#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}_${sourcedType.type.className?replace('.', '-')}");
 
     @Test
     void unlabeled_unknown_class() {
@@ -53,7 +55,7 @@ void labeled_unknown_class() {
     void unlabeled_known_class() {
         assertConversion(
                 "apiref:example.MyAppender[]",
-                "<a href=\"com.example.groupId/example-artifactId/example.MyAppender.html\">MyAppender</a>");
+                "<a href=\"#com-example-groupId_example-artifactId_example-MyAppender\">MyAppender</a>");
     }
 
     @Test
@@ -66,7 +68,7 @@ void unlabeled_known_excluded_class() {
     void labeled_known_class() {
         assertConversion(
                 "apiref:example.MyAppender[foo]",
-                "<a href=\"com.example.groupId/example-artifactId/example.MyAppender.html\">foo</a>");
+                "<a href=\"#com-example-groupId_example-artifactId_example-MyAppender\">foo</a>");
     }
 
     private void assertConversion(final String asciiDoc, final String expectedOutput) {

diff --git a/...rc/main/java/org/apache/logging/log4j/tools/internal/freemarker/util/FreeMarkerUtils.java b/...rc/main/java/org/apache/logging/log4j/tools/internal/freemarker/util/FreeMarkerUtils.java
@@ -26,7 +26,10 @@
 import freemarker.template.Version;
 import java.io.BufferedWriter;
 import java.io.IOException;
+import java.io.StringReader;
+import java.io.StringWriter;
 import java.io.UncheckedIOException;
+import java.io.Writer;
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
@@ -39,20 +42,21 @@ public final class FreeMarkerUtils {
 
     private static final String CHARSET_NAME = CHARSET.name();
 
+    private static final Version CONFIGURATION_VERSION = Configuration.VERSION_2_3_29;
+
     private FreeMarkerUtils() {}
 
     @SuppressFBWarnings("DMI_HARDCODED_ABSOLUTE_FILENAME")
     private static Configuration createConfiguration(final Path templateDirectory) {
-        final Version configurationVersion = Configuration.VERSION_2_3_29;
-        final Configuration configuration = new Configuration(configurationVersion);
+        final Configuration configuration = new Configuration(CONFIGURATION_VERSION);
         configuration.setDefaultEncoding(CHARSET_NAME);
         configuration.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
         try {
             configuration.setTemplateLoader(new FileTemplateLoader(templateDirectory.toFile()));
         } catch (final IOException error) {
             throw new UncheckedIOException(error);
         }
-        final DefaultObjectWrapperBuilder objectWrapperBuilder = new DefaultObjectWrapperBuilder(configurationVersion);
+        final DefaultObjectWrapperBuilder objectWrapperBuilder = new DefaultObjectWrapperBuilder(CONFIGURATION_VERSION);
         objectWrapperBuilder.setExposeFields(true);
         final DefaultObjectWrapper objectWrapper = objectWrapperBuilder.build();
         configuration.setObjectWrapper(objectWrapper);
@@ -83,4 +87,23 @@ public static void render(
             throw new RuntimeException(message, error);
         }
     }
+
+    @SuppressFBWarnings("TEMPLATE_INJECTION_FREEMARKER")
+    public static String renderString(final String templateString, final Object templateData) {
+        final Configuration configuration = new Configuration(CONFIGURATION_VERSION);
+        final DefaultObjectWrapperBuilder objectWrapperBuilder = new DefaultObjectWrapperBuilder(CONFIGURATION_VERSION);
+        objectWrapperBuilder.setExposeFields(true);
+        final DefaultObjectWrapper objectWrapper = objectWrapperBuilder.build();
+        configuration.setObjectWrapper(objectWrapper);
+        try {
+            final Template template =
+                    new Template("ephemeralInlineTemplate", new StringReader(templateString), configuration);
+            final Writer templateWriter = new StringWriter();
+            template.process(templateData, templateWriter);
+            return templateWriter.toString();
+        } catch (final Exception error) {
+            final String message = String.format("failed rendering template `%s`", templateString);
+            throw new RuntimeException(message, error);
+        }
+    }
 }
diff --git a/src/site/_log4j-docgen-asciidoctor-extension.adoc b/src/site/_log4j-docgen-asciidoctor-extension.adoc
@@ -50,14 +50,13 @@ That is, if `true`, `apiref:some.unknown.Class[]` will be converted to `<code>Cl
 Note that this only applies to types where the label is not provided.
 This flag is disabled by default.
 
-`log4j-docgen-type-template-target`::
-The target file path of individual types documented, e.g., `../../%g/%a/%c.html`.
-Certain directives are subject to substitution:
-
-* `%a` – artifact ID, if the type is provided with an artifact origin; `unknown-artifactId`, otherwise
-* `%c` – class name
-* `%g` – group ID, if the type is provided with an artifact origin; `unknown-groupId`, otherwise
-* `%v` – version, if the type is provided with an artifact origin; `unknown-version`, otherwise
+`log4j-docgen-type-target-template`::
+The FreeMarker template to produce the link target for individual types documented, for instance:
++
+[source]
+----
+#${sourcedType.groupId?replace('.', '-')}_${sourcedType.artifactId?replace('.', '-')}_${sourcedType.type.className?replace('.', '-')
+----
 
 +
 This attribute is *required*.