4.x - Externalize and compile documentation java snippets (helidon-io…

…#8294) Externalize and compile docs java snippets. Introduce conventions and style for Java snippets across all docs (see helidon-io#8294)
hrstoyanov · Feb 23, 2024 · 4b97644 · 4b97644
1 parent 6917e2a
commit 4b97644
Show file tree

Hide file tree

Showing 225 changed files with 14,241 additions and 8,538 deletions.
diff --git a/docs/pom.xml b/docs/pom.xml
@@ -32,13 +32,45 @@
     <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>
+        <!-- snippets dependencies -->
+        <dependency>
+            <groupId>org.apache.activemq</groupId>
+            <artifactId>activemq-client</artifactId>
+            <optional>true</optional>
+            <exclusions>
+                <exclusion>
+                    <groupId>*</groupId>
+                    <artifactId>*</artifactId>
+                </exclusion>
+            </exclusions>
+        </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 +101,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>compile-snippets</id>
+                        <phase>generate-sources</phase>
+                        <goals>
+                            <goal>compile</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
         </plugins>
     </build>
 

diff --git a/docs/src/main/asciidoc/about/additional_info.adoc b/docs/src/main/asciidoc/about/additional_info.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.
@@ -31,6 +31,6 @@ Here are some additional resources you can use to get started, get help, and to
 *	Medium publication: https://medium.com/helidon
 *	GitHub repository: https://github.com/helidon-io/helidon
 *	Public Slack workspace: https://slack.helidon.io/
-*	Twitter account: https://twitter.com/helidon_project 
-*	YouTube channel: https://www.youtube.com/channel/UChg00-uTTrCMmPsuzUNaZsA[https://www.youtube.com/channel/UChg00-uTTrCMmPsuzUNaZsA]
-*	Stack Overflow tag: https://stackoverflow.com/tags/helidon 
+*	Twitter account: https://twitter.com/helidon_project
+*	YouTube channel: https://youtube.helidon.io
+*	Stack Overflow tag: https://stackoverflow.com/tags/helidon
diff --git a/docs/src/main/asciidoc/about/benefits.adoc b/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
diff --git a/docs/src/main/asciidoc/about/doc_overview.adoc b/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
 --

diff --git a/docs/src/main/asciidoc/about/intro.adoc b/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&iacute;ma, Project N&iacute;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]
 ----
 
 

diff --git a/docs/src/main/asciidoc/about/introduction.adoc b/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]
diff --git a/docs/src/main/asciidoc/images/favicon.png b/docs/src/main/asciidoc/images/favicon.png
diff --git a/docs/src/main/asciidoc/includes/attributes.adoc b/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

diff --git a/docs/src/main/asciidoc/includes/cors.adoc b/docs/src/main/asciidoc/includes/cors.adoc
@@ -106,14 +106,14 @@ ifdef::se-flavor[]
 [source,yaml]
 ----
 restrictive-cors:
-  allow-origins: ["http://foo.com", "http://there.com"]
+  allow-origins: ["https://foo.com", "https://there.com"]
   allow-methods: ["PUT", "DELETE"]
 ----
 endif::[]
 ifndef::se-flavor[]
 [source,yaml]
 ----
-allow-origins: ["http://foo.com", "http://there.com"]
+allow-origins: ["https://foo.com", "https://there.com"]
 allow-methods: ["PUT", "DELETE"]
 ----
 endif::[]
@@ -207,15 +207,15 @@ You can use mapped configuration to your advantage if you want to specify all CO
 
 The following example illustrates the mapped cross-origin configuration format.
 
-[source,hocon,subs="attributes+"]
+[source,yaml,subs="attributes+"]
 ----
-{mapped-config-top-key}: // <1>
+{mapped-config-top-key}: # <1>
   paths: <2>
     - path-pattern: /greeting // <3>
-      allow-origins: ["http://foo.com", "http://there.com", "http://other.com"] // <4>
+      allow-origins: ["https://foo.com", "https://there.com", "https://other.com"] # <4>
       allow-methods: ["PUT", "DELETE"]
-    - path-pattern: / // <5>
-      allow-methods: ["GET", "HEAD", "OPTIONS", "POST"] // <6>
+    - path-pattern: / # <5>
+      allow-methods: ["GET", "HEAD", "OPTIONS", "POST"] # <6>
 ----
 // We want to use the following to insert the SE or MP callout 1 text; we need to use the blank, plus,
 // and subs because the MP attribute value contains backticks, and this is the only way we've found
@@ -337,15 +337,15 @@ CORS configuration section.
 // Tag the following example so we can exclude it from MP which supplies its own complete example.
 // tag::se-config-example[]
 The following example restricts sharing of the
-`{built-in-service-prefix}/health` resource, provided by the health built-in service, to only the origin `\http://there.com`.
+`{built-in-service-prefix}/health` resource, provided by the health built-in service, to only the origin `\https://there.com`.
 [source,hocon,subs="attributes+"]
 ----
 cors:
   paths:
     - path-pattern: "{built-in-service-prefix}/health"
-      allow-origins: [http://there.com]
+      allow-origins: [https://there.com]
     - path-pattern: "{built-in-service-prefix}/metrics"
-      allow-origins: [http://foo.com]
+      allow-origins: [https://foo.com]
 ----
 
 // end::se-config-example[]
@@ -368,10 +368,11 @@ Build and run the QuickStart application as usual.
 The metrics service rejects attempts to access metrics on behalf of a disallowed origin.
 [source,bash,subs="attributes+"]
 ----
-curl -i -H "Origin: http://other.com" http://localhost:8080{built-in-service-prefix}/metrics
+curl -i -H "Origin: https://other.com" http://localhost:8080{built-in-service-prefix}/metrics
 ----
 
 [source, listing]
+.Curl output
 ----
 HTTP/1.1 403 Forbidden
 Date: Mon, 11 May 2020 11:08:09 -0500
@@ -382,13 +383,14 @@ connection: keep-alive
 But accesses from `foo.com` succeed.
 [source,bash,subs="attributes+"]
 ----
-curl -i -H "Origin: http://foo.com" http://localhost:8080{built-in-service-prefix}/metrics
+curl -i -H "Origin: https://foo.com" http://localhost:8080{built-in-service-prefix}/metrics
 ----
 
 [source, listing]
+.Curl output
 ----
 HTTP/1.1 200 OK
-Access-Control-Allow-Origin: http://foo.com
+Access-Control-Allow-Origin: https://foo.com
 Content-Type: text/plain
 Date: Mon, 11 May 2020 11:08:16 -0500
 Vary: Origin
@@ -405,7 +407,7 @@ The health service rejects requests from origins not specifically approved.
 
 [source,bash,subs="attributes+"]
 ----
-curl -i -H "Origin: http://foo.com" http://localhost:8080{built-in-service-prefix}/health
+curl -i -H "Origin: https://foo.com" http://localhost:8080{built-in-service-prefix}/health
 ----
 
 [source, listing]
@@ -416,17 +418,17 @@ transfer-encoding: chunked
 connection: keep-alive
 ----
 
-And responds successfully only to cross-origin requests from `\http://there.com`.
+And responds successfully only to cross-origin requests from `\https://there.com`.
 
 [source,bash,subs="attributes+"]
 ----
-curl -i -H "Origin: http://there.com" http://localhost:8080{built-in-service-prefix}/health
+curl -i -H "Origin: https://there.com" http://localhost:8080{built-in-service-prefix}/health
 ----
 
 [source, listing]
 ----
 HTTP/1.1 200 OK
-Access-Control-Allow-Origin: http://there.com
+Access-Control-Allow-Origin: https://there.com
 Content-Type: application/json
 Date: Mon, 11 May 2020 12:07:32 -0500
 Vary: Origin

diff --git a/docs/src/main/asciidoc/includes/cron.adoc b/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
-|=======================================================================================================================
+|=======================================================================================================================