Qute: introduce a new strategy to handle duplicate template paths

mkouba · mkouba · commit f3e77fe4513c · 2025-04-24T12:25:27.000+02:00
- resolves quarkusio#43906
diff --git a/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/EffectiveTemplatePathsBuildItem.java b/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/EffectiveTemplatePathsBuildItem.java
@@ -0,0 +1,26 @@
+package io.quarkus.qute.deployment;
+
+import java.util.List;
+
+import io.quarkus.builder.item.SimpleBuildItem;
+import io.quarkus.qute.runtime.QuteConfig;
+
+/**
+ * This build item represents all template paths of an application.
+ * <p>
+ * If {@link QuteConfig.DuplicitTemplateStrategy#PRIORITIZE} is used then duplicit template paths with lower priority are not
+ * included.
+ */
+public final class EffectiveTemplatePathsBuildItem extends SimpleBuildItem {
+
+    private final List<TemplatePathBuildItem> templatePaths;
+
+    EffectiveTemplatePathsBuildItem(List<TemplatePathBuildItem> templatePaths) {
+        this.templatePaths = templatePaths;
+    }
+
+    public List<TemplatePathBuildItem> getTemplatePaths() {
+        return templatePaths;
+    }
+
+}
diff --git a/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/QuteDevModeProcessor.java b/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/QuteDevModeProcessor.java
@@ -2,7 +2,6 @@
 
 import java.lang.reflect.Modifier;
 import java.util.HashMap;
-import java.util.List;
 import java.util.Map;
 import java.util.function.Predicate;
 
@@ -27,10 +26,10 @@
 public class QuteDevModeProcessor {
 
     @BuildStep
-    void collectGeneratedContents(List<TemplatePathBuildItem> templatePaths,
+    void collectGeneratedContents(EffectiveTemplatePathsBuildItem effectiveTemplatePaths,
             BuildProducer<ValidationErrorBuildItem> errors) {
         Map<String, String> contents = new HashMap<>();
-        for (TemplatePathBuildItem template : templatePaths) {
+        for (TemplatePathBuildItem template : effectiveTemplatePaths.getTemplatePaths()) {
             if (!template.isFileBased()) {
                 contents.put(template.getPath(), template.getContent());
             }
diff --git a/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/QuteProcessor.java b/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/QuteProcessor.java
diff --git a/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/TemplatePathBuildItem.java b/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/TemplatePathBuildItem.java
@@ -4,17 +4,38 @@
 import java.util.Objects;
 
 import io.quarkus.builder.item.MultiBuildItem;
+import io.quarkus.qute.runtime.QuteConfig;
 
 /**
  * Discovered template.
  * <p>
  * Templates backed by files located in a template root are discovered automatically. Furthermore, extensions can produce this
  * build item in order to provide a template that is not backed by a file.
  *
+ * <h2>Warning</h2>
+ *
+ * Extensions should never <i>consume</i> this build item directly. However, they may consume the
+ * {@link EffectiveTemplatePathsBuildItem} instead.
+ *
  * @see TemplateRootBuildItem
  */
 public final class TemplatePathBuildItem extends MultiBuildItem {
 
+    /**
+     * The priority used for templates from the root application archive.
+     */
+    public static final int ROOT_ARCHIVE_PRIORITY = 30;
+
+    /**
+     * The default priority used for templates that are not backed by a file.
+     */
+    public static final int BUILD_ITEM_PRIORITY = 20;
+
+    /**
+     * The priority used for templates from non-root application archives.
+     */
+    public static final int APP_ARCHIVE_PRIORITY = 10;
+
     /**
      *
      * @return a new builder instance
@@ -30,23 +51,27 @@ public static Builder builder() {
     private final Path fullPath;
     private final String extensionInfo;
 
+    private final int priority;
+
     /**
      *
      * @param path
      * @param fullPath
      * @param content
      * @deprecated Use the {@link #builder()} instead
      */
-    @Deprecated
+    @Deprecated(forRemoval = true, since = "3.13")
     public TemplatePathBuildItem(String path, Path fullPath, String content) {
-        this(Objects.requireNonNull(path), Objects.requireNonNull(content), Objects.requireNonNull(fullPath), null);
+        this(Objects.requireNonNull(path), Objects.requireNonNull(content), Objects.requireNonNull(fullPath), null,
+                BUILD_ITEM_PRIORITY);
     }
 
-    private TemplatePathBuildItem(String path, String content, Path fullPath, String extensionInfo) {
+    private TemplatePathBuildItem(String path, String content, Path fullPath, String extensionInfo, int priority) {
         this.path = path;
         this.content = content;
         this.fullPath = fullPath;
         this.extensionInfo = extensionInfo;
+        this.priority = priority;
     }
 
     /**
@@ -86,6 +111,15 @@ public String getExtensionInfo() {
         return extensionInfo;
     }
 
+    /**
+     * Templates with higher priority take precedence when duplicates are found.
+     *
+     * @return the priority
+     */
+    public int getPriority() {
+        return priority;
+    }
+
     /**
      *
      * @return {@code true} if it represents a user tag, {@code false} otherwise
@@ -111,7 +145,7 @@ public boolean isFileBased() {
     }
 
     public String getSourceInfo() {
-        return isFileBased() ? getFullPath().toString() : extensionInfo;
+        return (isFileBased() ? getFullPath().toString() : extensionInfo) + " [" + getPriority() + "]";
     }
 
     public static class Builder {
@@ -120,6 +154,7 @@ public static class Builder {
         private String content;
         private Path fullPath;
         private String extensionInfo;
+        private int priority = BUILD_ITEM_PRIORITY;
 
         /**
          * Set the path relative to the template root. The {@code /} is used as a path separator.
@@ -168,11 +203,23 @@ public Builder extensionInfo(String info) {
             return this;
         }
 
+        /**
+         * Set the priority of the template.
+         *
+         * @param priority
+         * @return self
+         * @see QuteConfig#duplicitTemplateStrategy()
+         */
+        public Builder priority(int priority) {
+            this.priority = priority;
+            return this;
+        }
+
         public TemplatePathBuildItem build() {
             if (fullPath == null && extensionInfo == null) {
                 throw new IllegalStateException("Templates that are not backed by a file must provide extension info");
             }
-            return new TemplatePathBuildItem(path, content, fullPath, extensionInfo);
+            return new TemplatePathBuildItem(path, content, fullPath, extensionInfo, priority);
         }
 
     }
diff --git a/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/devui/QuteDevUIProcessor.java b/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/devui/QuteDevUIProcessor.java
@@ -20,6 +20,7 @@
 import io.quarkus.devui.spi.page.Page;
 import io.quarkus.qute.ParameterDeclaration;
 import io.quarkus.qute.deployment.CheckedTemplateBuildItem;
+import io.quarkus.qute.deployment.EffectiveTemplatePathsBuildItem;
 import io.quarkus.qute.deployment.ImplicitValueResolverBuildItem;
 import io.quarkus.qute.deployment.TemplateDataBuildItem;
 import io.quarkus.qute.deployment.TemplateExtensionMethodBuildItem;
@@ -33,7 +34,7 @@ public class QuteDevUIProcessor {
 
     @BuildStep(onlyIf = IsDevelopment.class)
     public void pages(
-            List<TemplatePathBuildItem> templatePaths,
+            EffectiveTemplatePathsBuildItem effectiveTemplatePaths,
             List<CheckedTemplateBuildItem> checkedTemplates,
             TemplateVariantsBuildItem variants,
             TemplatesAnalysisBuildItem templatesAnalysis,
@@ -45,7 +46,7 @@ public void pages(
 
         CardPageBuildItem pageBuildItem = new CardPageBuildItem();
 
-        List<TemplatePathBuildItem> sortedTemplatePaths = templatePaths.stream()
+        List<TemplatePathBuildItem> sortedTemplatePaths = effectiveTemplatePaths.getTemplatePaths().stream()
                 .sorted(Comparator.comparing(tp -> tp.getPath().toLowerCase())).collect(Collectors.toList());
         pageBuildItem.addBuildTimeData("templates",
                 createTemplatesJson(sortedTemplatePaths, checkedTemplates, templatesAnalysis, variants));
diff --git a/extensions/qute/deployment/src/test/java/io/quarkus/qute/deployment/builditemtemplate/AdditionalTemplatePathDuplicatesResolvedTest.java b/extensions/qute/deployment/src/test/java/io/quarkus/qute/deployment/builditemtemplate/AdditionalTemplatePathDuplicatesResolvedTest.java
@@ -0,0 +1,58 @@
+package io.quarkus.qute.deployment.builditemtemplate;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.util.function.Consumer;
+
+import jakarta.inject.Inject;
+
+import org.jboss.shrinkwrap.api.asset.StringAsset;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import io.quarkus.builder.BuildChainBuilder;
+import io.quarkus.builder.BuildContext;
+import io.quarkus.builder.BuildStep;
+import io.quarkus.qute.Template;
+import io.quarkus.qute.deployment.TemplatePathBuildItem;
+import io.quarkus.test.QuarkusUnitTest;
+
+public class AdditionalTemplatePathDuplicatesResolvedTest {
+
+    @RegisterExtension
+    static final QuarkusUnitTest config = new QuarkusUnitTest()
+            .withApplicationRoot(root -> root
+                    .addAsResource(new StringAsset("Hi {name}!"), "templates/hi.txt"))
+            .addBuildChainCustomizer(buildCustomizer());
+
+    static Consumer<BuildChainBuilder> buildCustomizer() {
+        return new Consumer<BuildChainBuilder>() {
+            @Override
+            public void accept(BuildChainBuilder builder) {
+                builder.addBuildStep(new BuildStep() {
+                    @Override
+                    public void execute(BuildContext context) {
+                        context.produce(TemplatePathBuildItem.builder()
+                                .path("hi.txt")
+                                .extensionInfo("test-ext")
+                                .content("Hello {name}!")
+                                .priority(100)
+                                .build());
+                    }
+                }).produces(TemplatePathBuildItem.class)
+                        .build();
+
+            }
+        };
+    }
+
+    @Inject
+    Template hi;
+
+    @Test
+    public void testHi() {
+        // Build item with higher priority takes precedence
+        assertEquals("Hello Lu!", hi.data("name", "Lu").render());
+    }
+
+}
diff --git a/extensions/qute/deployment/src/test/java/io/quarkus/qute/deployment/builditemtemplate/AdditionalTemplatePathDuplicatesTest.java b/extensions/qute/deployment/src/test/java/io/quarkus/qute/deployment/builditemtemplate/AdditionalTemplatePathDuplicatesTest.java
@@ -20,6 +20,7 @@ public class AdditionalTemplatePathDuplicatesTest {
     static final QuarkusUnitTest config = new QuarkusUnitTest()
             .withApplicationRoot(root -> root
                     .addAsResource(new StringAsset("Hi {name}!"), "templates/hi.txt"))
+            .overrideConfigKey("quarkus.qute.duplicit-template-strategy", "fail")
             .addBuildChainCustomizer(buildCustomizer())
             .setExpectedException(IllegalStateException.class, true);
 
diff --git a/extensions/qute/deployment/src/test/java/io/quarkus/qute/deployment/scanning/DuplicateTemplatesResolvedTest.java b/extensions/qute/deployment/src/test/java/io/quarkus/qute/deployment/scanning/DuplicateTemplatesResolvedTest.java
@@ -0,0 +1,31 @@
+package io.quarkus.qute.deployment.scanning;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import jakarta.inject.Inject;
+
+import org.jboss.shrinkwrap.api.asset.StringAsset;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import io.quarkus.qute.Template;
+import io.quarkus.test.QuarkusUnitTest;
+
+public class DuplicateTemplatesResolvedTest {
+
+    @RegisterExtension
+    static final QuarkusUnitTest config = new QuarkusUnitTest()
+            .withApplicationRoot(root -> root.addAsResource(new StringAsset("Hello!"), "templates/hello.html"))
+            .withAdditionalDependency(
+                    d -> d.addAsResource(new StringAsset("Hi!"), "templates/hello.html"));
+
+    @Inject
+    Template hello;
+
+    @Test
+    public void testHello() {
+        // Root archive takes precedence
+        assertEquals("Hello!", hello.render());
+    }
+
+}
diff --git a/extensions/qute/deployment/src/test/java/io/quarkus/qute/deployment/scanning/MultipleTemplatesDirectoryDuplicateFoundTest.java b/extensions/qute/deployment/src/test/java/io/quarkus/qute/deployment/scanning/MultipleTemplatesDirectoryDuplicateFoundTest.java
@@ -17,6 +17,7 @@ public class MultipleTemplatesDirectoryDuplicateFoundTest {
             .withApplicationRoot(root -> root.addAsResource(new StringAsset("Hello!"), "templates/hello.html"))
             .withAdditionalDependency(
                     d -> d.addAsResource(new StringAsset("Hi!"), "templates/hello.html"))
+            .overrideConfigKey("quarkus.qute.duplicit-template-strategy", "fail")
             .assertException(t -> {
                 Throwable e = t;
                 IllegalStateException ise = null;
diff --git a/extensions/qute/runtime/src/main/java/io/quarkus/qute/runtime/EngineProducer.java b/extensions/qute/runtime/src/main/java/io/quarkus/qute/runtime/EngineProducer.java
@@ -82,7 +82,6 @@ public class EngineProducer {
 
     private final Engine engine;
     private final ContentTypes contentTypes;
-    private final List<String> tags;
     private final List<String> suffixes;
     private final Set<String> templateRoots;
     private final Map<String, String> templateContents;
@@ -100,7 +99,6 @@ public EngineProducer(QuteContext context, QuteConfig config, QuteRuntimeConfig
         this.suffixes = config.suffixes();
         this.templateRoots = context.getTemplateRoots();
         this.templateContents = Map.copyOf(context.getTemplateContents());
-        this.tags = context.getTags();
         this.defaultLocale = locales.defaultLocale().orElse(Locale.getDefault());
         this.defaultCharset = config.defaultCharset();
         this.container = Arc.container();
@@ -112,7 +110,8 @@ public EngineProducer(QuteContext context, QuteConfig config, QuteRuntimeConfig
         }
         this.templatePathExcludes = excludesBuilder.build();
 
-        LOGGER.debugf("Initializing Qute [templates: %s, tags: %s, resolvers: %s", context.getTemplatePaths(), tags,
+        LOGGER.debugf("Initializing Qute [templates: %s, tags: %s, resolvers: %s", context.getTemplatePaths(),
+                context.getTags(),
                 context.getResolverClasses());
 
         EngineBuilder builder = Engine.builder();
@@ -219,7 +218,7 @@ public EngineProducer(QuteContext context, QuteConfig config, QuteRuntimeConfig
             LOGGER.debugf("Added generated value resolver: %s", resolverClass);
         }
         // Add tags
-        for (String tag : tags) {
+        for (String tag : context.getTags()) {
             // Strip suffix, item.html -> item
             String tagName = tag.contains(".") ? tag.substring(0, tag.indexOf('.')) : tag;
             String tagTemplateId = TAGS + tagName;
@@ -375,7 +374,27 @@ private Optional<TemplateLocation> locate(String path) {
         if (isExcluded(path)) {
             return Optional.empty();
         }
-        // First try to locate file-based templates
+        // First try the template contents, i.e. templates not backed by files
+        LOGGER.debugf("Locate template contents for %s", path);
+        String content = templateContents.get(path);
+        if (content == null) {
+            // Try path with suffixes
+            for (String suffix : suffixes) {
+                String pathWithSuffix = path + "." + suffix;
+                if (isExcluded(pathWithSuffix)) {
+                    continue;
+                }
+                content = templateContents.get(pathWithSuffix);
+                if (content != null) {
+                    break;
+                }
+            }
+        }
+        if (content != null) {
+            return Optional.of(new ContentTemplateLocation(content, createVariant(path)));
+        }
+
+        // Then try to locate file-based templates
         for (String templateRoot : templateRoots) {
             URL resource = null;
             String templatePath = templateRoot + path;
@@ -399,25 +418,7 @@ private Optional<TemplateLocation> locate(String path) {
                 return Optional.of(new ResourceTemplateLocation(resource, createVariant(templatePath)));
             }
         }
-        // Then try the template contents
-        LOGGER.debugf("Locate template contents for %s", path);
-        String content = templateContents.get(path);
-        if (content == null) {
-            // Try path with suffixes
-            for (String suffix : suffixes) {
-                String pathWithSuffix = path + "." + suffix;
-                if (isExcluded(pathWithSuffix)) {
-                    continue;
-                }
-                content = templateContents.get(pathWithSuffix);
-                if (content != null) {
-                    break;
-                }
-            }
-        }
-        if (content != null) {
-            return Optional.of(new ContentTemplateLocation(content, createVariant(path)));
-        }
+
         return Optional.empty();
     }
 
diff --git a/extensions/qute/runtime/src/main/java/io/quarkus/qute/runtime/QuteConfig.java b/extensions/qute/runtime/src/main/java/io/quarkus/qute/runtime/QuteConfig.java
