diff --git a/CHANGELOG.md b/CHANGELOG.md index 78f073814..9ad0c8e99 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/fj-doc-guide/src/main/docs/asciidoc/chapters/08_1_eager-startup.adoc b/fj-doc-guide/src/main/docs/asciidoc/chapters/08_1_eager-startup.adoc new file mode 100644 index 000000000..10b2b8abc --- /dev/null +++ b/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]. diff --git a/fj-doc-guide/src/main/docs/asciidoc/chapters/08_doc-optmization.adoc b/fj-doc-guide/src/main/docs/asciidoc/chapters/08_doc-optmization.adoc new file mode 100644 index 000000000..8122d7a21 --- /dev/null +++ b/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. diff --git a/fj-doc-guide/src/main/docs/asciidoc/chapters/08_doc-playground.adoc b/fj-doc-guide/src/main/docs/asciidoc/chapters/09_doc-playground.adoc similarity index 100% rename from fj-doc-guide/src/main/docs/asciidoc/chapters/08_doc-playground.adoc rename to fj-doc-guide/src/main/docs/asciidoc/chapters/09_doc-playground.adoc diff --git a/fj-doc-guide/src/main/docs/asciidoc/index.adoc b/fj-doc-guide/src/main/docs/asciidoc/index.adoc index f60eae25c..60d28107a 100644 --- a/fj-doc-guide/src/main/docs/asciidoc/index.adoc +++ b/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[] \ No newline at end of file +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[] diff --git a/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/AddVenusFacade.java b/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/AddVenusFacade.java index 024418cf9..7b58c30d5 100644 --- a/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/AddVenusFacade.java +++ b/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" ) ) { diff --git a/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/FlavourContext.java b/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/FlavourContext.java index 2bba60da4..4195bd630 100644 --- a/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/FlavourContext.java +++ b/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() ); + } + } diff --git a/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/VenusContext.java b/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/VenusContext.java index 5540e7456..ff25a29c5 100644 --- a/fj-doc-maven-plugin/src/main/java/org/fugerit/java/doc/project/facade/VenusContext.java +++ b/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() { diff --git a/fj-doc-maven-plugin/src/main/resources/config/flavour/flavour_versions_default.properties b/fj-doc-maven-plugin/src/main/resources/config/flavour/flavour_versions_default.properties index 85506be5d..2283194db 100644 --- a/fj-doc-maven-plugin/src/main/resources/config/flavour/flavour_versions_default.properties +++ b/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 diff --git a/fj-doc-maven-plugin/src/main/resources/config/template/flavour/flavour-macro.ftl b/fj-doc-maven-plugin/src/main/resources/config/template/flavour/flavour-macro.ftl index a085a2f43..bb933859c 100644 --- a/fj-doc-maven-plugin/src/main/resources/config/template/flavour/flavour-macro.ftl +++ b/fj-doc-maven-plugin/src/main/resources/config/template/flavour/flavour-macro.ftl @@ -3,10 +3,15 @@ <#macro toProjectPackage context>${context.groupId}.${context.artifactId?replace("-","")} <#macro createDocumentProcess context exceptionType> + // creates the doc helper + DocHelper docHelper = new DocHelper(); + <@createDocumentProcessNoHelper context=context exceptionType=exceptionType/> + + +<#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 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" @@ -14,9 +19,12 @@ <#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 context.addLombok > + log.info( "processDocument handlerId : {}", handlerId ); + 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) { diff --git a/fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3-fm-yml.ftl b/fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3-fm-yml.ftl index 7fb49d373..4c4aa6822 100644 --- a/fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3-fm-yml.ftl +++ b/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 \ No newline at end of file + 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 \ No newline at end of file diff --git a/fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3/AppInit.ftl b/fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3/AppInit.ftl index 9e8f07ff1..6a834b1ee 100644 --- a/fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3/AppInit.ftl +++ b/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() ); } } diff --git a/fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3/DocHelper.ftl b/fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3/DocHelper.ftl new file mode 100644 index 000000000..e42b0a65b --- /dev/null +++ b/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; } + +} diff --git a/fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3/DocResource.ftl b/fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3/DocResource.ftl index 0b5610a34..3b2248eba 100644 --- a/fj-doc-maven-plugin/src/main/resources/config/template/flavour/quarkus-3/DocResource.ftl +++ b/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"/>