4.x - Externalize and compile documentation java snippets

docs/pom.xml

@@ -32,13 +32,38 @@
     <properties>
         <helidon.services.skip>true</helidon.services.skip>
         <helidon.sitegen.skip>false</helidon.sitegen.skip>
+        <version.lib.jbatch-api>2.1.0</version.lib.jbatch-api>
+        <version.lib.jbatch.container>2.1.0</version.lib.jbatch.container>
     </properties>
 
     <dependencies>
         <dependency>
             <groupId>io.helidon</groupId>
             <artifactId>helidon-all</artifactId>
             <type>pom</type>
+            <optional>true</optional>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.activemq</groupId>
+            <artifactId>activemq-client</artifactId>
+            <optional>true</optional>
+        </dependency>
+        <dependency>
+            <groupId>com.oracle.oci.sdk</groupId>
+            <artifactId>oci-java-sdk-objectstorage</artifactId>
+            <optional>true</optional>
+        </dependency>
+        <dependency>
+            <groupId>jakarta.batch</groupId>
+            <artifactId>jakarta.batch-api</artifactId>
+            <version>${version.lib.jbatch-api}</version>
+            <optional>true</optional>
+        </dependency>
+        <dependency>
+            <groupId>com.ibm.jbatch</groupId>
+            <artifactId>com.ibm.jbatch.spi</artifactId>
+            <version>${version.lib.jbatch.container}</version>
+            <optional>true</optional>
         </dependency>
     </dependencies>
 
@@ -69,6 +94,22 @@
                     <siteArchiveSkip>${helidon.sitegen.skip}</siteArchiveSkip>
                 </configuration>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <proc>none</proc>
+                </configuration>
+                <executions>
+                    <execution>
+                        <id>default-compile</id>
+                        <phase>compile</phase>
+                        <goals>
+                            <goal>compile</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
         </plugins>
     </build>
 

docs/src/main/asciidoc/about/benefits.adoc

@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2023 Oracle and/or its affiliates.
+    Copyright (c) 2023, 2024 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -90,4 +90,4 @@ applications to consume and produce messages with those providers
 keys, PKI certificates, and other secrets
 * Micrometer Metrics, for monitoring Helidon applications using
 Micrometer
-* Neo4j, for using a graph database from within Helidon applications
+* Neo4j, for using a graph database from within Helidon applications

docs/src/main/asciidoc/about/doc_overview.adoc

@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2018, 2023 Oracle and/or its affiliates.
+    Copyright (c) 2018, 2024 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -125,18 +125,18 @@ xref:{rootdir}/se/config/introduction.adoc[Helidon Config]
 .Training and Certification
 [icon=model_training]
 --
-
 
-Training:  
+
+Training:
  https://learn.oracle.com/ols/learning-path/become-a-helidon-microservices-developer-professional/88258/114512[Become a Helidon Microservices Developer Professional]
- 
-Certification: 
+
+Certification:
   https://learn.oracle.com/ols/learning-path/become-a-helidon-microservices-developer-professional/88258/114512[Helidon Microservices Developer Professional (1Z0-1113)]
-
-New to Helidon? Check out https://a.co/d/0niQnwC[Beginning Helidon] to learn more about building cloud-native microservices with Helidon.  
+
+New to Helidon? Check out https://a.co/d/0niQnwC[Beginning Helidon] to learn more about building cloud-native microservices with Helidon.
+
 
 
-
 --
 
 //Get Involved
@@ -156,7 +156,7 @@ Public Slack workspace: https://slack.helidon.io/
 
 Twitter account: https://twitter.com/helidon_project
 
-YouTube channel: https://www.youtube.com/channel/UChg00-uTTrCMmPsuzUNaZsA
+YouTube channel: https://youtube.helidon.io
 
 Stack Overflow tag: https://stackoverflow.com/tags/helidon
 --

docs/src/main/asciidoc/about/intro.adoc

@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2023 Oracle and/or its affiliates.
+    Copyright (c) 2023, 2024 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -21,6 +21,7 @@
 :keywords: helidon, java, microservices, Helidon Níma, Project Níma
 :rootdir: {docdir}/..
 
+include::{rootdir}/includes/attributes.adoc[]
 
 
 == What's New in This Release
@@ -52,18 +53,13 @@ To give a very simple example of the differences between Helidon 3 SE and Helido
 .Helidon 3
 [source,java]
 ----
-
-request.content().as(JsonObject.class)
-        	.thenAccept(jo -> doSomething(jo, response));
-
+include::{sourcedir}/about/IntroSnippets.java[tag=snippet_1, indent=0]
 ----
 
 .Helidon 4
 [source,java]
 ----
-
-doSomething(request.content().as(JsonObject.class), response);
-
+include::{sourcedir}/about/IntroSnippets.java[tag=snippet_2, indent=0]
 ----
 
 

docs/src/main/asciidoc/about/introduction.adoc

@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2018, 2023 Oracle and/or its affiliates.
+    Copyright (c) 2018, 2024 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -71,25 +71,13 @@ To help illustrate the differences, below are two samples implementing a simple
 .Helidon SE sample
 [source,java]
 ----
-Routing routing = Routing.builder()
-    .get("/hello", 
-        (req, res) -> res.send("Hello World"))
-    .build();
-
-WebServer.create(routing)
-    .start();
+include::{sourcedir}/about/IntroductionSnippets.java[tag=snippet_1, indent=0]
 ----
 
 .Helidon MP sample
 [source,java]
 ----
-@Path("hello")
-public class HelloWorld {
-    @GET
-    public String hello() {
-        return "Hello World";
-    }
-}
+include::{sourcedir}/about/IntroductionSnippets.java[tag=snippet_2, indent=0]
 ----
 
 Even though Helidon MP supports Jakarta EE APIs it does not require
@@ -160,4 +148,4 @@ To upgrade from Helidon 1.x to 2.x:
 Choose a Helidon flavor to explore and start using it. Check out the following:
 
 - xref:{rootdir}/se/introduction.adoc[Helidon SE Documentation]
-- xref:{rootdir}/mp/introduction.adoc[Helidon MP Documentation]
+- xref:{rootdir}/mp/introduction.adoc[Helidon MP Documentation]

docs/src/main/asciidoc/includes/attributes.adoc

@@ -26,6 +26,8 @@ ifndef::attributes-included[]
 :helidon-version: 4.0.0-SNAPSHOT
 :helidon-version-is-release: false
 
+:sourcedir: {rootdir}/../java/io/helidon/docs
+
 ifeval::["{helidon-version-is-release}" != "true"]
 :helidon-github-tree-url: https://github.com/oracle/helidon/tree/main
 endif::[]
@@ -51,7 +53,7 @@ endif::[]
 :version-lib-microprofile-reactive-messaging-api: 3.0
 :version-lib-microprofile-rs-operators-api: 3.0
 :version-lib-microprofile-rest-client: 3.0
-:version.lib.microprofile-telemetry-tck: 1.0
+:version-lib-microprofile-telemetry-tck: 1.0
 :version-lib-microprofile-telemetry: 1.0
 :version-lib-microprofile-tracing: 3.0
 
@@ -212,6 +214,7 @@ endif::[]
 :micrometer-javadoc-base-url: {javadoc-base-url}/io.helidon.integrations.micrometer
 :prometheus-javadoc-base-url: {javadoc-base-url}/io.helidon.metrics.prometheus
 :mp-cors-javadoc-base-url: {javadoc-base-url}/io.helidon.microprofile.cors
+:mp-server-javadoc-base-url: {javadoc-base-url}/io.helidon.microprofile.server
 :mp-tyrus-javadoc-base-url: {javadoc-base-url}/io.helidon.microprofile.tyrus
 :mp-restclient-javadoc-base-url: {javadoc-base-url}/io.helidon.microprofile.restclient
 :openapi-javadoc-base-url: {javadoc-base-url}/io.helidon.openapi

docs/src/main/asciidoc/includes/cron.adoc

@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2021, 2023 Oracle and/or its affiliates.
+    Copyright (c) 2021, 2024 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -46,7 +46,7 @@ ifndef::rootdir[:rootdir: {docdir}/..]
 | LIST      | \d+,\d+(,\d+)*        | 1,2,3,4   | list of constants
 | RANGE     | \d+-\d+               | 15-30     | range of values from-to
 | WILDCARD  | \*                    | *         | all values withing the field
-| INCREMENT | \d+\/\d+              | 0/5       | inital number / increments, 2/5 means 2,7,9,11,16,...
+| INCREMENT | \d+\/\d+              | 0/5       | initial number / increments, 2/5 means 2,7,9,11,16,...
 | ANY       | \?                    | ?         | any day(apply only to day-of-week and day-of-month)
 | NTH       | \#                    | 1#3       | nth day of the month, 2#3 means third monday of the month
 | LAST      | \d*L(\+\d+\|\-\d+)?   | 3L-3      | last day of the month in day-of-month or last nth day in the day-of-week
@@ -61,4 +61,4 @@ ifndef::rootdir[:rootdir: {docdir}/..]
 | 0/2 * * * * ? *       | Every 2 seconds
 | 0 45 9 ? * *          | Every day at 9:45
 | 0 15 8 ? * MON-FRI    | Every workday at 8:15
-|=======================================================================================================================
+|=======================================================================================================================

docs/src/main/asciidoc/includes/graphql.adoc

@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2020, 2023 Oracle and/or its affiliates.
+    Copyright (c) 2020, 2024 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -43,4 +43,4 @@ The following configuration keys can be used to set up GraphQL invocation:
 |`graphql.exception-white-list` |{nbsp} |Array of checked exception classes that should return default error message
 |`graphql.exception-black-list` |{nbsp} |Array of unchecked exception classes that should return message to caller (instead of default error message)
 
-|===
+|===

docs/src/main/asciidoc/includes/guides/maven-build.adoc

@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2020, 2023 Oracle and/or its affiliates.
+    Copyright (c) 2020, 2024 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -38,14 +38,14 @@ use a Helidon application POM as their parent. This parent POM provides the foll
 
 If you want to use your own parent POM, then take a look at the
 link:{helidon-github-tree-url}/examples/quickstarts/helidon-standalone-quickstart-{flavor-lc}[standalone quickstart example].
-This example has a stand-alone POM that you can pattern your own application POM after.
+This example has a standalone POM that you can pattern your own application POM after.
 
 For more details on Helidon application POMs see the
 link:{helidon-github-tree-url}/docs-internal/application-pom.md[Helidon's Application POMS]
 
 == Dependency Management
 
-In Maven you use Dependency Management to manage the versions of the
+In Maven, you use Dependency Management to manage the versions of the
 dependencies used by your project so that you do not need to specify
 versions when declaring project dependencies.
 
@@ -113,17 +113,21 @@ You can override many of the plugin attributes by passing a system property to t
 `mvn` command:
 
 [source, bash]
+----
 mvn -Djlink.image.addClassDataSharingArchive=false package
+----
 
 === Set Property in pom.xml
 
 Or you can set the properties in your project's pom.xml:
 
 [source, xml]
+----
 <properties>
     <jlink.image.addClassDataSharingArchive>false</jlink.image.addClassDataSharingArchive>
     <native.image.reportExceptionStackTraces>true</native.image.reportExceptionStackTraces>
 </properties>
+----
 
 === Override Plugin Configuration using `pluginManagement`
 
@@ -150,4 +154,4 @@ For full control you can override the plugin's configuration using `pluginManage
             </plugins>
         </pluginManagement>
     </build>
-----
+----

docs/src/main/asciidoc/includes/guides/metrics.adoc

@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2021, 2023 Oracle and/or its affiliates.
+    Copyright (c) 2021, 2024 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -430,11 +430,11 @@ docker build -t helidon-metrics-{flavor-lc} .
 kind: Service
 apiVersion: v1
 metadata:
-  name: helidon-metrics // <1>
+  name: helidon-metrics # <1>
   labels:
     app: helidon-metrics
   annotations:
-    prometheus.io/scrape: true // <2>
+    prometheus.io/scrape: "true" # <2>
 spec:
   type: NodePort
   selector:
@@ -449,7 +449,7 @@ apiVersion: apps/v1
 metadata:
   name: helidon-metrics
 spec:
-  replicas: 1 // <3>
+  replicas: 1 # <3>
   selector:
     matchLabels:
       app: helidon-metrics
@@ -486,7 +486,7 @@ kubectl get service/helidon-metrics
 [source,bash]
 ----
 NAME             TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
-helidon-metrics   NodePort   10.99.159.2   <none>        8080:31143/TCP   8s // <1>
+helidon-metrics   NodePort   10.99.159.2   <none>        8080:31143/TCP   8s # <1>
 ----
 <1> A service of type `NodePort` that serves the default routes on port `31143`.
 
@@ -520,12 +520,12 @@ metrics-prometheus-server-5fc5dc86cb-79lk4   2/2     Running   0          46s
 ----
 
 [source,bash]
-.Create a port-forward so you can access the server URL:
+.Create a port-forward, so you can access the server URL:
 ----
 kubectl --namespace default port-forward $POD_NAME 7090:9090
 ----
 
-Now open your browser and navigate to `http://localhost:7090/targets`.  Search for helidon on the page and you will see your
+Now open your browser and navigate to `http://localhost:7090/targets`.  Search for helidon on the page, and you will see your
 Helidon application as one of the Prometheus targets.
 
 ==== Final Cleanup