General tidy-up and more JavaDocs

Author: JonathanGiles

aspire4j/aspire4j-extensions-azure-eventhubs/src/main/java/com/microsoft/aspire/extensions/azure/storage/resources/AzureEventHubsResource.java

@@ -2,7 +2,10 @@
 
 import com.microsoft.aspire.resources.AzureBicepResource;
 import com.microsoft.aspire.resources.traits.ResourceWithEndpoints;
+import com.microsoft.aspire.utils.templates.TemplateDescriptor;
+import com.microsoft.aspire.utils.templates.TemplateDescriptorsBuilder;
 import com.microsoft.aspire.utils.templates.TemplateEngine;
+import com.microsoft.aspire.utils.templates.TemplateFileOutput;
 
 import java.util.List;
 import java.util.Map;
@@ -25,9 +28,8 @@ public List<TemplateFileOutput> processTemplate() {
             .with("eventhubns.module.bicep", "${name}.module.bicep")
             .build();
 
-        List<TemplateFileOutput> templateOutput = TemplateEngine.process(AzureEventHubsResource.class, templateFiles, Map.of(
-            "name", getName()
-        ));
+        List<TemplateFileOutput> templateOutput = TemplateEngine.getTemplateEngine()
+            .process(AzureEventHubsResource.class, templateFiles, Map.of("name", getName()));
 
         // we know that we need to get the output filename from the first element, and set that as the path
         // FIXME we need a better way of determining the output path of the template

aspire4j/aspire4j-extensions-azure-openai/src/main/java/com/microsoft/aspire/extensions/azure/openai/resources/AzureOpenAIResource.java

@@ -5,7 +5,10 @@
 import com.microsoft.aspire.resources.references.ReferenceExpression;
 import com.microsoft.aspire.resources.traits.ResourceWithConnectionString;
 import com.microsoft.aspire.resources.traits.ResourceWithEndpoints;
+import com.microsoft.aspire.utils.templates.TemplateDescriptor;
+import com.microsoft.aspire.utils.templates.TemplateDescriptorsBuilder;
 import com.microsoft.aspire.utils.templates.TemplateEngine;
+import com.microsoft.aspire.utils.templates.TemplateFileOutput;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -39,9 +42,8 @@ public List<TemplateFileOutput> processTemplate() {
             .with("openai.module.bicep", "${name}.module.bicep")
             .build();
 
-        List<TemplateFileOutput> templateOutput = TemplateEngine.process(AzureOpenAIResource.class, templateFiles, Map.of(
-            "name", getName()
-        ));
+        List<TemplateFileOutput> templateOutput = TemplateEngine.getTemplateEngine()
+            .process(AzureOpenAIResource.class, templateFiles, Map.of("name", getName()));
 
         // we know that we need to get the output filename from the first element, and set that as the path
         // FIXME we need a better way of determining the output path of the template

aspire4j/aspire4j-extensions-azure-storage/src/main/java/com/microsoft/aspire/extensions/azure/storage/resources/AzureStorageResource.java

@@ -4,7 +4,10 @@
 import com.microsoft.aspire.resources.AzureBicepResource;
 import com.microsoft.aspire.resources.ResourceType;
 import com.microsoft.aspire.resources.traits.ResourceWithEndpoints;
+import com.microsoft.aspire.utils.templates.TemplateDescriptor;
+import com.microsoft.aspire.utils.templates.TemplateDescriptorsBuilder;
 import com.microsoft.aspire.utils.templates.TemplateEngine;
+import com.microsoft.aspire.utils.templates.TemplateFileOutput;
 
 import java.util.List;
 import java.util.Map;
@@ -54,9 +57,8 @@ public List<TemplateFileOutput> processTemplate() {
             .with("storage.module.bicep", "${name}.module.bicep")
             .build();
 
-        List<TemplateFileOutput> templateOutput = TemplateEngine.process(AzureStorageResource.class, templateFiles, Map.of(
-            "name", getName()
-        ));
+        List<TemplateFileOutput> templateOutput = TemplateEngine.getTemplateEngine()
+            .process(AzureStorageResource.class, templateFiles, Map.of("name", getName()));
 
         // we know that we need to get the output filename from the first element, and set that as the path
         // FIXME we need a better way of determining the output path of the template

aspire4j/aspire4j-extensions-dotnet/src/main/java/com/microsoft/aspire/extensions/dotnet/resources/Project.java

@@ -8,7 +8,6 @@
 import com.microsoft.aspire.resources.Resource;
 import com.microsoft.aspire.resources.ResourceType;
 import com.microsoft.aspire.utils.json.RelativePath;
-import com.microsoft.aspire.utils.json.RelativePathSerializer;
 import com.microsoft.aspire.resources.traits.ResourceWithArguments;
 import com.microsoft.aspire.resources.traits.ResourceWithEndpoints;
 import com.microsoft.aspire.resources.traits.ResourceWithEnvironment;
@@ -62,7 +61,6 @@ public class Project<T extends Project<T>> extends Resource<T>
     @NotNull(message = "Project.path cannot be null")
     @NotEmpty(message = "Project.path cannot be an empty string")
     @JsonProperty("path")
-    @JsonSerialize(using = RelativePathSerializer.class)
     @RelativePath
     private String path;
 

aspire4j/aspire4j-extensions-spring/src/main/java/com/microsoft/aspire/extensions/spring/resources/EurekaServiceDiscovery.java

@@ -4,7 +4,10 @@
 import com.microsoft.aspire.resources.traits.ResourceWithEndpoints;
 import com.microsoft.aspire.resources.traits.ResourceWithTemplate;
 import com.microsoft.aspire.utils.FileUtilities;
+import com.microsoft.aspire.utils.templates.TemplateDescriptor;
+import com.microsoft.aspire.utils.templates.TemplateDescriptorsBuilder;
 import com.microsoft.aspire.utils.templates.TemplateEngine;
+import com.microsoft.aspire.utils.templates.TemplateFileOutput;
 
 import java.nio.file.Path;
 import java.util.HashMap;
@@ -56,7 +59,8 @@ public List<TemplateFileOutput> processTemplate() {
             .with("application.yaml", "src/main/resources/application.yaml")
             .build();
 
-        List<TemplateFileOutput> templateOutput = TemplateEngine.process(EurekaServiceDiscovery.class, templateFiles, properties);
+        List<TemplateFileOutput> templateOutput = TemplateEngine.getTemplateEngine()
+            .process(EurekaServiceDiscovery.class, templateFiles, properties);
 
         // Important - as noted in the javadoc - from the perspective of the API below, the paths are relative to the
         // directory in which azd is running, NOT the output directory. These paths will then be transformed at

aspire4j/aspire4j-extensions-spring/src/main/java/com/microsoft/aspire/extensions/spring/resources/SpringProject.java

@@ -2,7 +2,6 @@
 
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonProperty;
-import com.fasterxml.jackson.databind.annotation.JsonSerialize;
 import com.microsoft.aspire.DistributedApplication;
 import com.microsoft.aspire.extensions.spring.implementation.SpringDeploymentStrategy;
 import com.microsoft.aspire.extensions.spring.implementation.SpringIntrospector;
@@ -13,8 +12,10 @@
 import com.microsoft.aspire.resources.traits.ResourceWithTemplate;
 import com.microsoft.aspire.utils.FileUtilities;
 import com.microsoft.aspire.utils.json.RelativePath;
-import com.microsoft.aspire.utils.json.RelativePathSerializer;
+import com.microsoft.aspire.utils.templates.TemplateDescriptor;
+import com.microsoft.aspire.utils.templates.TemplateDescriptorsBuilder;
 import com.microsoft.aspire.utils.templates.TemplateEngine;
+import com.microsoft.aspire.utils.templates.TemplateFileOutput;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.NotEmpty;
 import jakarta.validation.constraints.NotNull;
@@ -36,7 +37,6 @@ public class SpringProject extends Container<SpringProject>
     @NotNull(message = "Project.path cannot be null")
     @NotEmpty(message = "Project.path cannot be an empty string")
     @JsonProperty("path")
-    @JsonSerialize(using = RelativePathSerializer.class)
     @RelativePath
     private String path;
 
@@ -177,7 +177,8 @@ public List<TemplateFileOutput> processTemplate() {
                     .with("JAVA_TOOL_OPTIONS.delim")
                     .build();
 
-            List<TemplateFileOutput> templateOutput = TemplateEngine.process(SpringProject.class, templateFiles, properties);
+            List<TemplateFileOutput> templateOutput = TemplateEngine.getTemplateEngine()
+                .process(SpringProject.class, templateFiles, properties);
 
             // Important - as noted in the javadoc - from the perspective of the API below, the paths are relative to the
             // directory in which azd is running, NOT the output directory. These paths will then be transformed at

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/ManifestGenerator.java

@@ -11,10 +11,12 @@
 import java.util.logging.Logger;
 
 import com.fasterxml.jackson.databind.module.SimpleModule;
-import com.microsoft.aspire.utils.json.CustomSerializerModifier;
+import com.microsoft.aspire.implementation.utils.json.RelativePathModule;
+import com.microsoft.aspire.implementation.utils.json.CustomSerializerModifier;
 import com.microsoft.aspire.resources.traits.ResourceWithLifecycle;
 import com.microsoft.aspire.resources.traits.ResourceWithTemplate;
 import com.microsoft.aspire.utils.FileUtilities;
+import com.microsoft.aspire.utils.templates.TemplateFileOutput;
 import jakarta.validation.ConstraintViolation;
 import jakarta.validation.Validation;
 import jakarta.validation.Validator;
@@ -86,6 +88,7 @@ private void writeManifest(DistributedApplication app) {
         SimpleModule module = new SimpleModule();
         module.setSerializerModifier(new CustomSerializerModifier());
         objectMapper.registerModule(module);
+        objectMapper.registerModule(new RelativePathModule());
 
         printAnnotations(System.out, app);
 
@@ -98,7 +101,7 @@ private void writeManifest(DistributedApplication app) {
         LOGGER.info("Manifest written to file");
     }
 
-    private void writeTemplateFile(ResourceWithTemplate.TemplateFileOutput templateFile) {
+    private void writeTemplateFile(TemplateFileOutput templateFile) {
         try {
             Path path = Paths.get(outputPath.toString() + "/" + templateFile.filename());
 

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/implementation/TemplateStrings.java

@@ -45,6 +45,6 @@ public static String evaluateConnectionString(String resourceName) {
     }
 
     public static String evaluate(String template, Map<String, Object> context) {
-        return TemplateEngine.getTemplateEngine().processTemplate(template, context);
+        return TemplateEngine.getTemplateEngine().process(template, context);
     }
 }

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/utils/json/CustomSerializerModifier.java renamed to aspire4j/aspire4j/src/main/java/com/microsoft/aspire/implementation/utils/json/CustomSerializerModifier.java

@@ -1,9 +1,10 @@
-package com.microsoft.aspire.utils.json;
+package com.microsoft.aspire.implementation.utils.json;
 
 import com.fasterxml.jackson.databind.BeanDescription;
 import com.fasterxml.jackson.databind.JsonSerializer;
 import com.fasterxml.jackson.databind.SerializationConfig;
 import com.fasterxml.jackson.databind.ser.BeanSerializerModifier;
+import com.microsoft.aspire.utils.json.CustomSerialize;
 
 import java.lang.annotation.Annotation;
 

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/implementation/utils/json/RelativePathModule.java

@@ -0,0 +1,47 @@
+package com.microsoft.aspire.implementation.utils.json;
+
+import com.fasterxml.jackson.core.Version;
+import com.fasterxml.jackson.databind.*;
+import com.fasterxml.jackson.databind.Module;
+import com.fasterxml.jackson.databind.introspect.Annotated;
+import com.fasterxml.jackson.databind.introspect.AnnotatedMember;
+import com.fasterxml.jackson.databind.introspect.JacksonAnnotationIntrospector;
+import com.fasterxml.jackson.databind.ser.Serializers;
+import com.fasterxml.jackson.databind.module.SimpleSerializers;
+import com.microsoft.aspire.utils.json.RelativePath;
+
+public class RelativePathModule extends Module {
+
+    @Override
+    public String getModuleName() {
+        return "RelativePathModule";
+    }
+
+    @Override
+    public Version version() {
+        return Version.unknownVersion();
+    }
+
+    @Override
+    public void setupModule(SetupContext context) {
+        context.addSerializers(new SimpleSerializers() {
+            @Override
+            public JsonSerializer<?> findSerializer(SerializationConfig config, JavaType type, BeanDescription beanDesc) {
+                if (beanDesc.getClassAnnotations().has(RelativePath.class)) {
+                    return new RelativePathSerializer();
+                }
+                return super.findSerializer(config, type, beanDesc);
+            }
+        });
+
+        context.insertAnnotationIntrospector(new JacksonAnnotationIntrospector() {
+            @Override
+            protected boolean _isIgnorable(Annotated a) {
+                if (a.hasAnnotation(RelativePath.class)) {
+                    return false; // Ensure fields with @RelativePath are not ignored
+                }
+                return super._isIgnorable(a);
+            }
+        });
+    }
+}

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/utils/json/RelativePathSerializer.java renamed to aspire4j/aspire4j/src/main/java/com/microsoft/aspire/implementation/utils/json/RelativePathSerializer.java

@@ -1,11 +1,12 @@
-package com.microsoft.aspire.utils.json;
+package com.microsoft.aspire.implementation.utils.json;
 
 import com.fasterxml.jackson.core.JsonGenerator;
 import com.fasterxml.jackson.databind.BeanProperty;
 import com.fasterxml.jackson.databind.JsonSerializer;
 import com.fasterxml.jackson.databind.SerializerProvider;
 import com.fasterxml.jackson.databind.ser.ContextualSerializer;
 import com.microsoft.aspire.utils.FileUtilities;
+import com.microsoft.aspire.utils.json.RelativePath;
 
 import java.io.IOException;
 import java.nio.file.Path;
@@ -42,7 +43,6 @@ public void serialize(String value, JsonGenerator gen, SerializerProvider serial
             // When the path is output to the aspire-manifest.json file, the path will transform based on the relative
             // location of the output directory to the root directory. This way, when azd picks up the manifest file,
             // the paths remain correct.
-//            gen.writeString(FileUtilities.getOutputRelativePath(value).toString());
             gen.writeString(FileUtilities.convertRootRelativePathToOutputPath(value).toString());
         } else {
             gen.writeString(value);

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/utils/json/ResourceSerializer.java renamed to aspire4j/aspire4j/src/main/java/com/microsoft/aspire/implementation/utils/json/ResourceSerializer.java

@@ -1,4 +1,4 @@
-package com.microsoft.aspire.utils.json;
+package com.microsoft.aspire.implementation.utils.json;
 
 import com.fasterxml.jackson.core.JsonGenerator;
 import com.fasterxml.jackson.databind.BeanDescription;

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/DockerFile.java

@@ -6,7 +6,7 @@
 import com.fasterxml.jackson.databind.annotation.JsonSerialize;
 import com.microsoft.aspire.resources.annotations.KeyValueAnnotation;
 import com.microsoft.aspire.utils.json.RelativePath;
-import com.microsoft.aspire.utils.json.RelativePathSerializer;
+import com.microsoft.aspire.implementation.utils.json.RelativePathSerializer;
 import com.microsoft.aspire.resources.traits.ResourceWithEndpoints;
 import com.microsoft.aspire.resources.traits.ResourceWithEnvironment;
 import jakarta.validation.constraints.NotEmpty;

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/Resource.java

@@ -5,7 +5,7 @@
 import com.fasterxml.jackson.annotation.JsonPropertyOrder;
 import com.microsoft.aspire.resources.annotations.ResourceAnnotation;
 import com.microsoft.aspire.utils.json.CustomSerialize;
-import com.microsoft.aspire.utils.json.ResourceSerializer;
+import com.microsoft.aspire.implementation.utils.json.ResourceSerializer;
 import com.microsoft.aspire.resources.traits.*;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.NotEmpty;

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/traits/ResourceWithTemplate.java

@@ -1,9 +1,8 @@
 package com.microsoft.aspire.resources.traits;
 
 import com.microsoft.aspire.resources.Resource;
+import com.microsoft.aspire.utils.templates.TemplateFileOutput;
 
-import java.nio.file.Path;
-import java.util.ArrayList;
 import java.util.List;
 
 /**
@@ -16,78 +15,9 @@
  */
 public interface ResourceWithTemplate<T extends Resource<T> & ResourceWithTemplate<T>> extends SelfAware<T> {
 
+    /**
+     * Processes the template associated with this resource.
+     * @return A list of template file outputs.
+     */
     List<TemplateFileOutput> processTemplate();
-
-    class TemplateDescriptor {
-        private final String inputFilename;
-        private final String outputFilename;
-
-        public TemplateDescriptor(String inputFilename, String outputFilename) {
-            this.inputFilename = inputFilename;
-            this.outputFilename = outputFilename;
-        }
-
-        public String getInputFilename() {
-            return inputFilename;
-        }
-
-        public String getOutputFilename() {
-            return outputFilename;
-        }
-    }
-
-    class TemplateDescriptorsBuilder {
-        final String templatePath;
-        final String outputRootPath;
-
-        final List<TemplateDescriptor> templateDescriptors;
-
-        private TemplateDescriptorsBuilder(String templatePath, String outputRootPath) {
-            this.templatePath = templatePath;
-            this.outputRootPath = outputRootPath;
-            this.templateDescriptors = new ArrayList<>();
-        }
-
-        /**
-         * Begins the process of specifying template files to be processed, which will be written to the root of the
-         * user-specified output directory by default.
-         * @param templatePath      The path to the template files, relative to the root of the jar file / the resources
-         *                          directory.
-         * @return A new TemplateDescriptorsBuilder instance that can then be used to specify the template files to be
-         * processed.
-         */
-        public static TemplateDescriptorsBuilder begin(String templatePath) {
-            return begin(templatePath, "");
-        }
-
-        /**
-         * Begins the process of specifying template files to be processed.
-         * @param templatePath      The path to the template files, relative to the root of the jar file / the resources
-         *                          directory.
-         * @param outputRootPath    The root path where the output files will be written to, relative to the
-         *                          user-specified output directory.
-         * @return A new TemplateDescriptorsBuilder instance that can then be used to specify the template files to be
-         * processed.
-         */
-        public static TemplateDescriptorsBuilder begin(String templatePath, String outputRootPath) {
-            return new TemplateDescriptorsBuilder(templatePath, outputRootPath);
-        }
-
-        public TemplateDescriptorsBuilder with(String inputFilename) {
-            templateDescriptors.add(new TemplateDescriptor(templatePath + inputFilename, outputRootPath + inputFilename));
-            return this;
-        }
-
-        public TemplateDescriptorsBuilder with(String inputFilename, String outputFilename) {
-            templateDescriptors.add(new TemplateDescriptor(templatePath + inputFilename, outputRootPath + outputFilename));
-            return this;
-        }
-
-        public List<TemplateDescriptor> build() {
-            return templateDescriptors;
-        }
-    }
-
-    // FIXME at some point string content won't be sufficient, and we will want to support binary content too
-    record TemplateFileOutput(String filename, String content) {    }
 }