270 documentation is there any way to reduce the handling time for th…

…e first request (#271)

* micronaut flavour version set to 4.7.2

* added documentation for eager startup #270

(added optimization chapter)

* [fj-doc-maven-plugin] goal init #270

flavour quarkus-3 added eager init example

CHANGELOG.md

@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - quarkus-version set to 3.17.4 across al the modules
+- [fj-doc-maven-plugin] micronaut flavour version set to 4.7.2
+- [fj-doc-maven-plugin] goal init, flavour quarkus-3 added eager init example #270
 
 ## [8.11.5] - 2024-12-06
 

fj-doc-guide/src/main/docs/asciidoc/chapters/08_1_eager-startup.adoc

@@ -0,0 +1,43 @@
+<<<
+[#doc-optimize-startup]
+== Eager vs Lazy initialization
+
+By default, Fugerit Venus Doc has a lazy initialization approach.
+
+In some situation it could be a good idea to have an eager (Ahead Of Time) initialization.
+
+This can be achieved using a built-in utility :
+
+_org.fugerit.java.doc.base.config.InitHandler_
+
+Here is an example of eager initialization based on Jakarta EE event API.
+
+[source,java]
+----
+package org.fugerit.java.doc.demo;
+
+import io.quarkus.runtime.StartupEvent;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.event.Observes;
+import jakarta.inject.Inject;
+import org.fugerit.java.doc.base.config.InitHandler;
+
+@ApplicationScoped
+public class AppInit {
+
+    @Inject
+    DocHelper docHelper;
+
+    void onStart(@Observes StartupEvent ev) {
+        /*
+         * This will initialize all the doc handlers using async mode.
+         * (use method InitHandler.initDocAll() for synced startup)
+         */
+        InitHandler.initDocAllAsync(
+                docHelper.getDocProcessConfig().getFacade().handlers() );
+    }
+
+}
+----
+
+NOTE: This will initialize all the doc handlers specified as arguments by trying to create a link:https://github.com/fugerit-org/fj-doc/blob/main/fj-doc-base/src/main/resources/config/init_doc/doc-init.xml[simple document].

fj-doc-guide/src/main/docs/asciidoc/chapters/08_doc-optmization.adoc

@@ -0,0 +1,5 @@
+<<<
+[#doc-optimization]
+== Optimizations
+
+In this chapter the main Venus optimizations ara described.

fj-doc-guide/src/main/docs/asciidoc/index.adoc

@@ -46,4 +46,9 @@ include::chapters/07_002_doc-faq-validate-document.adoc[]
 include::chapters/07_003_doc-faq-clean-source.adoc[]
 include::chapters/07_004_doc-faq-resize-xls.adoc[]
 include::chapters/07_005_doc-faq-kotlin-step.adoc[]
-include::chapters/07_006_doc-faq-endline-fop.adoc[]
+include::chapters/07_006_doc-faq-endline-fop.adoc[]
+
+include::chapters/08_doc-optmization.adoc[]
+include::chapters/08_1_eager-startup.adoc[]
+
+include::chapters/09_doc-playground.adoc[]

fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/AddVenusFacade.java

@@ -91,8 +91,12 @@ private static void addDocFacade( VenusContext context ) throws IOException, Tem
         DocConfigGenerator javaGenerator = new DocConfigGenerator( context );
         Properties generatorProps = new Properties();
         javaGenerator.init( sourceFolder, context.getDocConfigPackage()+"."+context.getDocConfigClass(), SimpleJavaGenerator.STYLE_CLASS, generatorProps);
-        javaGenerator.generate();
-        javaGenerator.write();
+        if ( javaGenerator.getJavaFile().exists() ) {
+            log.info( "DocHelper generator skip, already exists : {}", javaGenerator.getJavaFile().getCanonicalPath() );
+        } else {
+            javaGenerator.generate();
+            javaGenerator.write();
+        }
         // add sample structure
         addSampleStructure( context, configuration, data );
         if ( context.getModules().contains( "fj-doc-mod-fop" ) ) {

fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/FlavourContext.java

@@ -62,4 +62,8 @@ public boolean isAsciidocFreemarkerHandlerAvailable() {
         return VersionCheck.isMajorThan( this.getVersion(), VenusContext.VERSION_ASCIIDOC_FREEMARKER_HANDLER );
     }
 
+    public String getResourcePathFmConfigXml() {
+        return VenusContext.toResourcePathFmConfigXml( this.getArtifactId() );
+    }
+
 }

fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/VenusContext.java

@@ -19,6 +19,18 @@
 @ToString
 public class VenusContext {
 
+    public static String toArtificatIdForFolder( String artifactId ) {
+        return artifactId.toLowerCase();
+    }
+
+    public static String toArtificatIdForName( String artifactId ) {
+        return toArtificatIdForFolder( artifactId ).replace( "-", "" );
+    }
+
+    public static String toResourcePathFmConfigXml( String artifactId ) {
+        return toArtificatIdForFolder( artifactId )+"/fm-doc-process-config.xml";
+    }
+
     public static final String VERSION_ASCIIDOC_FREEMARKER_HANDLER = "8.8.6";
 
     public static final String VERSION_NA_VERIFY_PLUGIN = "8.7.2";
@@ -97,15 +109,15 @@ public String getGroupId() {
     }
 
     public String getArtificatIdForFolder() {
-        return this.getMavenModel().getArtifactId().toLowerCase();
+        return toArtificatIdForFolder( this.getMavenModel().getArtifactId() );
     }
 
     public String getArtificatIdForName() {
-        return this.getArtificatIdForFolder().replace( "-", "" ).toLowerCase();
+        return toArtificatIdForName( this.getMavenModel().getArtifactId() );
     }
 
     public String getResourcePathFmConfigXml() {
-        return this.getArtificatIdForFolder()+"/fm-doc-process-config.xml";
+        return toResourcePathFmConfigXml( this.getMavenModel().getArtifactId() );
     }
 
     public String getDocConfigPackage() {

fj-doc-maven-plugin/src/main/resources/config/flavour/flavour_versions_default.properties

@@ -1,6 +1,6 @@
 # default flavour versions
 quarkus-3=3.17.4
 quarkus-2=2.16.12.Final
-micronaut-4=4.7.1
+micronaut-4=4.7.2
 springboot-3=3.4.0
 openliberty=24.0.0.11

fj-doc-maven-plugin/src/main/resources/config/template/flavour/flavour-macro.ftl

@@ -3,20 +3,28 @@
 <#macro toProjectPackage context>${context.groupId}.${context.artifactId?replace("-","")}</#macro>
 
 <#macro createDocumentProcess context exceptionType>
+    // creates the doc helper
+    DocHelper docHelper = new DocHelper();
+    <@createDocumentProcessNoHelper context=context exceptionType=exceptionType/>
+</#macro>
+
+<#macro createDocumentProcessNoHelper context exceptionType>
     byte[] processDocument(String handlerId) {
         try (ByteArrayOutputStream baos = new ByteArrayOutputStream()) {
-            // creates the doc helper
-            DocHelper docHelper = new DocHelper();
+
             // create custom data for the fremarker template 'document.ftl'
             List<People> listPeople = Arrays.asList(new People("Luthien", "Tinuviel", "Queen"), new People("Thorin", "Oakshield", "King"));
             <#if context.modules?seq_contains("fj-doc-base-json")>// json source supported, if you want to try it, use the chainId "document-json"</#if>
             <#if context.modules?seq_contains("fj-doc-base-yaml")>// yaml source supported, if you want to try it, use the chainId "document-yaml"</#if>
             <#if context.modules?seq_contains("fj-doc-base-kotlin")>// kotlin source supported, if you want to try it,
             // use the chainId "document-kotlin" for FreeMarker + Kotlin
             // or "document-kotlin-pure" for pure Kotlin</#if>
+            <#if context.addLombok >
+            log.info( "processDocument handlerId : {}", handlerId );
+            </#if>
             String chainId = "document";
             // output generation
-            docHelper.getDocProcessConfig().fullProcess(chainId, DocProcessContext.newContext("listPeople", listPeople), handlerId, baos);
+            this.docHelper.getDocProcessConfig().fullProcess(chainId, DocProcessContext.newContext("listPeople", listPeople), handlerId, baos);
             // return the output
             return baos.toByteArray();
         } catch (Exception e) {

fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3-fm-yml.ftl

@@ -25,4 +25,6 @@ process:
   - from: flavour/${context.flavour}/AppInit.ftl
     to: ${context.projectFolder}/src/main/java/<@fhm.toProjectPackageFolder context=context/>/AppInit.java
   - from: flavour/${context.flavour}/DocResourceTest.ftl
-    to: ${context.projectFolder}/src/test/java/test/<@fhm.toProjectPackageFolder context=context/>/DocResourceTest.java
+    to: ${context.projectFolder}/src/test/java/test/<@fhm.toProjectPackageFolder context=context/>/DocResourceTest.java
+  - from: flavour/${context.flavour}/DocHelper.ftl
+    to: ${context.projectFolder}/src/main/java/<@fhm.toProjectPackageFolder context=context/>/DocHelper.java

fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3/AppInit.ftl

@@ -6,14 +6,25 @@ import jakarta.enterprise.context.ApplicationScoped;
 import jakarta.enterprise.event.Observes;
 import lombok.extern.slf4j.Slf4j;
 import io.quarkus.runtime.annotations.RegisterForReflection;
+import jakarta.inject.Inject;
+import org.fugerit.java.doc.base.config.InitHandler;
 
 @Slf4j
 @ApplicationScoped
 @RegisterForReflection( targets = { DocHelper.class, People.class } )
 public class AppInit {
 
+    @Inject
+    DocHelper docHelper;
+
     void onStart(@Observes StartupEvent ev) {
         log.info("The application is starting...");
+        /*
+         * This will initialize all the doc handlers using async mode.
+         * (use method InitHandler.initDocAll() for synced startup)
+         */
+        InitHandler.initDocAllAsync(
+        docHelper.getDocProcessConfig().getFacade().handlers() );
     }
 
 }

fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3/DocHelper.ftl

@@ -0,0 +1,15 @@
+<#import '../flavour-macro.ftl' as fhm>
+package <@fhm.toProjectPackage context=context/>;
+
+import org.fugerit.java.doc.freemarker.process.FreemarkerDocProcessConfig;
+import org.fugerit.java.doc.freemarker.process.FreemarkerDocProcessConfigFacade;
+import jakarta.enterprise.context.ApplicationScoped;
+
+@ApplicationScoped
+public class DocHelper {
+
+    private FreemarkerDocProcessConfig docProcessConfig = FreemarkerDocProcessConfigFacade.loadConfigSafe( "cl://${context.resourcePathFmConfigXml}" );
+
+    public FreemarkerDocProcessConfig getDocProcessConfig() { return this.docProcessConfig; }
+
+}

fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3/DocResource.ftl

@@ -6,6 +6,8 @@ import jakarta.ws.rs.Path;
 import jakarta.ws.rs.Produces;
 import jakarta.ws.rs.WebApplicationException;
 import jakarta.ws.rs.core.MediaType;
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
 import lombok.extern.slf4j.Slf4j;
 import org.fugerit.java.doc.base.config.DocConfig;
 import org.fugerit.java.doc.base.process.DocProcessContext;
@@ -20,10 +22,13 @@ import org.eclipse.microprofile.openapi.annotations.tags.Tag;
 import org.eclipse.microprofile.openapi.annotations.tags.Tags;
 
 @Slf4j
+@ApplicationScoped
 @Path("/doc")
 public class DocResource {
 
-    <@fhm.createDocumentProcess context=context exceptionType='WebApplicationException'/>
+    @Inject
+    DocHelper docHelper;
+    <@fhm.createDocumentProcessNoHelper context=context exceptionType='WebApplicationException'/>
 
     <@fhm.createQuarkusPath context=context outputMime="text/markdown" outputExtension="md" outputDescription="Markdown"/>