Sync to the todo-backend QS; general tidying and updates

Author: bstansberry

todo-jakarta-data/README-source.adoc

@@ -1,13 +1,13 @@
 include::../shared-doc/attributes.adoc[]
 
-= todo-backend: quickstart for backend deployment on OpenShift
+= todo-jakata-data: quickstart for backend deployment on OpenShift
 :toc:               left
 :icons:             font
 :idprefix:
 :idseparator:       -
 :keywords:          openshift,galleon,helm
 :level:             Intermediate
-:technologies:      JPA, JAX-RS, OpenShift, Galleon
+:technologies:      Jakarta Data, Jakarta REST, OpenShift, Galleon
 :openshift: true
 :archiveType: war
 :useHelmChartDir: true
@@ -17,11 +17,12 @@ include::../shared-doc/attributes.adoc[]
 :helmSetWildFlyArgumentPrefix: wildfly.
 
 [abstract]
-The `todo-backend` quickstart demonstrates how to implement a backend that exposes a HTTP API with Jakarta RESTful Web Services
+The `todo-jakarta-data` quickstart demonstrates how to implement a backend that exposes a HTTP API with Jakarta RESTful Web Services
 to manage a list of ToDo which are persisted in a database with Jakarta Data.
+It is very similar to the `todo-backend` quickstart but uses Jakarta Data instead of Jakarta Persistence to handle interaction with the backend database.
 
 ifndef::ProductRelease[]
-This quickstart shows how to setup a local deployment of this backend as well as a deployment on OpenShift to connect
+This quickstart shows how to set up a local deployment of this backend as well as a deployment on OpenShift to connect
 to a PostgreSQL database also hosted on OpenShift.
 endif::[]
 ifdef::ProductRelease[]
@@ -32,7 +33,7 @@ endif::[]
 
 == What is it?
 
-The `todo-backend` quickstart demonstrates how to implement a backend that exposes a HTTP API with `Jakarta REST`
+The `todo-jakarta-data` quickstart demonstrates how to implement a backend that exposes a HTTP API with `Jakarta REST`
 to manage a list of ToDo which are persisted in a database with `Jakarta Data`.
 
 * The backend exposes a HTTP API to manage a list of todos that complies with the specs defined at https://todobackend.com/specs/index.html[todobackend.com].
@@ -48,6 +49,10 @@ ifdef::ProductRelease[]
 * It is deployed on OpenShift using the https://jbossas.github.io/eap-charts//[Helm Chart for {productName}].
 endif::[]
 
+This quickstart
+is the same as the `todo-backend` quickstart, but uses `Jakarta Data` for its persistence layer, instead of `Jakarta Persistence`.
+To see the differences, compare this quickstart's `ToDoRepository` interface with the `ToDoDAO` interface and `ToDoDAOImpl` class in `todo-backend`.
+
 // Link to the quickstart source
 include::../shared-doc/view-the-source.adoc[leveloffset=+1]
 // System Requirements
@@ -67,6 +72,7 @@ The layers are defined in the `pom.xml` file in the `<configuration>` section of
 ----
 <layers>
   <layer>cloud-server</layer>
+  <layer>jakarta-data</layer>
   <layer>postgresql-datasource</layer>
 </layers>
 ----
@@ -80,13 +86,16 @@ The layers are defined in the `pom.xml` file in the `<configuration>` section of
 ----
 <layers>
   <layer>cloud-server</layer>
+  <layer>jakarta-data</layer>
   <layer>postgresql-datasource</layer>
 </layers>
 ----
 endif::[]
 
 The `cloud-server` layer provides everything needed to run the backend on OpenShift. This also includes access to
-Jakarta EE APIs such as CDI, JAX-RS, JPA, etc. These two layers comes from the {productName} feature pack provided in the
+Jakarta EE APIs such as CDI, Jakarta REST, etc, along with the Hibernate support used by Jakarta Data.
+The `jakarta-data` layer provides the Jakarta Data API.
+These two layers come from the {productName} feature pack provided in the
 {productName} S2I builder image.
 
 ifndef::ProductRelease[]
@@ -105,6 +114,33 @@ The Git repository for this feature pack is hosted at https://github.com/jbossas
 It provides JDBC drivers and datasources for different databases but for this quickstart, we will only need the `postgresql-datasource`.
 endif::[]
 
+=== Generation of the Jakarta Data Repository implementation
+
+A key feature of Jakarta Data is it does not require application developers to write detailed code to write from and write to the backend database.
+Developers just need declare their entities (using Jakarta Persistence annotations like `@Entity`) and then write an repository interface that describes the desired persistence operations, using the Jakarta Data annotations.
+It is then up to the Jakarta Data implementation to generate an implementation of that interface.
+
+WildFly's implementation of Jakarta Data, Hibernate Data Repositories, generates that implementation at application build time using an annotation processor run as part of compilation of the application.
+
+This is handled in the project `pom.xml` by configuring the `maven-compiler-plugin`:
+
+[source,xml]
+----
+<plugin>
+  <groupId>org.apache.maven.plugins</groupId>
+  <artifactId>maven-compiler-plugin</artifactId>
+  <configuration>
+    <annotationProcessorPaths>
+      <path>
+        <groupId>org.hibernate.orm</groupId>
+        <artifactId>hibernate-jpamodelgen</artifactId>
+        <version>${version.org.hibernate.jpamodelgen}</version>
+      </path>
+    </annotationProcessorPaths>
+  </configuration>
+</plugin>
+----
+
 === Connection to the PostgreSQL database
 
 ifndef::ProductRelease[]
@@ -117,11 +153,11 @@ is provided by the `org.jboss.eap:eap-datasources-galleon-pack` feature pack.
 endif::[]
 
 By default, it exposes a single datasource.
-In the backend, the name of this datasource is `ToDoRepository` and is specified in the `persistence.xml` to configure JPA:
+In the backend, the name of this datasource is `ToDoRepository` and is specified in the `persistence.xml` to configure Hibernate:
 
 [source,xml]
 ----
-<persistence-unit name="primary">
+<persistence-unit name="ToDos">
   <jta-data-source>java:jboss/datasources/ToDos</jta-data-source>
 </persistence-unit>
 ----
@@ -157,8 +193,6 @@ This script is executed at build time and will provide the following HTTP header
 By default, the backend accepts requests from any origin (`*`). This is only simplicity. It is possible to restrict
 the allowed origin using the environment variable `CORS_ORIGIN` at runtime.
 
-ifndef::ProductRelease[]
-
 == Run the Backend Locally
 
 === Package the Backend
@@ -167,7 +201,7 @@ The backend is packaged and deployed on a provisioned server:
 
 [source,options="nowrap"]
 ----
-$ mvn clean package -Pprovisioned-server
+$ mvn clean package
 ----
 
 === Run a Local PostgreSQL Database
@@ -196,20 +230,24 @@ The backend is running, and we can use the HTTP API to manage a list of todos:
 [source,options="nowrap"]
 ----
 # get a list of todos
-$ curl http://localhost:8080
+$ curl http://localhost:8080/todo-jakarta-data
 []
 
 # create a todo with the title "This is my first todo item!"
 $ curl -X POST -H "Content-Type: application/json"  -d '{"title": "This is my first todo item!"}' http://localhost:8080
 {"completed":false,"id":1,"order":0,"title":"This is my first todo item!","url":"https://localhost:8080/1"}%
 
 # get a list of todos with the one that was just created
-$ curl http://localhost:8080
+$ curl http://localhost:8080/todo-jakarta-data
 [{"completed":false,"id":1,"order":0,"title":"This is my first todo item!","url":"https://localhost:8080/1"}]
 ----
 
-:extraStartParams: -DPOSTGRESQL_DATABASE=todos -DPOSTGRESQL_SERVICE_HOST=localhost -DPOSTGRESQL_SERVICE_PORT=5432 -DPOSTGRESQL_USER=todos -DPOSTGRESQL_PASSWORD=mysecretpassword -DPOSTGRESQL_DATASOURCE=ToDos
-include::../shared-doc/run-integration-tests-with-provisioned-server.adoc[leveloffset=+1]
+Please note that the quickstart includes integration tests, which may be executed using the following command:
+
+[source,subs="attributes+",options="nowrap"]
+----
+$ mvn verify -Pintegration-testing
+----
 
 //===========================================================
 // Openshift - START
@@ -239,7 +277,5 @@ endif::[]
 This quickstart shows how the datasource feature pack provided by {productName} simplifies the deployment
 of a {productName} Jakarta EE backend on OpenShift to connect to an external database and exposes an HTTP API.
 
-ifndef::ProductRelease[]
 The use of a Server Provisioned deployment makes it seamless to move from a local deployment for development to a
-deployment on cloud platforms such as OpenShift and Kubernetes.
-endif::[]
+deployment on cloud platforms such as OpenShift and Kubernetes.

todo-jakarta-data/additional-readme-cloud.adoc

@@ -20,38 +20,34 @@ For {additional-readme-cloud-platform}, we rely on secrets so that the credentia
 deploy:
   env:
     - name: POSTGRESQL_PASSWORD
-      valueFrom:
-        secretKeyRef:
-          key: database-password
-          name: todo-backend-db
+        - name: POSTGRESQL_DATABASE
+          valueFrom:
+            configMapKeyRef:
+              name: postgres-configmap
+              key: POSTGRES_PASSWORD
 ----
 
-When the application is deployed, the value for the `POSTGRESQL_PASSWORD` will be taken from the key `database-password`
-in the secret `todo-backend-db`.
+When the application is deployed, the value for the `POSTGRESQL_PASSWORD` will be taken from the key `POSTGRES_PASSWORD`
+in the secret `postgres-configmap`.
 
 ifdef::additional-readme-openshift[]
 == Use the todobackend Web Frontend
 
-Once the backend is deployed on {additional-readme-cloud-platform}, it can be accessed from the route `todo-backend`.
+Once the backend is deployed on {additional-readme-cloud-platform}, it can be accessed from the route `todo-jakarta-data`.
 Let's find the host that we can use to connect to this backend:
 
 [source,options="nowrap"]
 ----
-$ oc get route todo-backend -o jsonpath="{.spec.host}"
-todo-backend-jmesnil1-dev.apps.sandbox.x8i5.p1.openshiftapps.com
+$ oc get route todo-jakarta-data -o jsonpath="{.spec.host}"
+todo-jakarta-data-jmesnil1-dev.apps.sandbox.x8i5.p1.openshiftapps.com
 ----
 
 This value will be different for every installation of the backend.
 
-[WARNING]
-====
-Make sure to prepend the host with `https://` to be able to connect to the backend from the ToDo Backend Specs or Client.
-The host must also be publicly accessible.
-====
+To be able to connect to the backend from the ToDo Backend Specs or Client, then prepend the host with `https://`, and append the relative web context `/todo-jakarta-data`. For the previous example host this would be `https://todo-jakarta-data-jmesnil1-dev.apps.sandbox.x8i5.p1.openshiftapps.com/todo-jakarta-data`.
 
 We can verify that this application is properly working as a ToDo Backend by running its https://todobackend.com/specs/index.html[specs] on it.
 
-
 Once all tests passed, we can use the https://todobackend.com/client/index.html[todobackend client] to have a Web application connected to the backend.
 
 [NOTE]

todo-jakarta-data/charts/Chart.yaml

@@ -1,13 +1,9 @@
 apiVersion: v2
-name: todo-backend-chart
-description: A Helm chart to deploy a WildFly todo-backend application and its Postgresql database
+name: todo-jakarta-data-chart
+description: A Helm chart to deploy a WildFly todo-jakarta-data application and its Postgresql database
 type: application
 version: 1.0.0
-appVersion: 31.0.0.Final
 dependencies:
-    - name: postgresql
-      repository: https://charts.bitnami.com/bitnami
-      version: 13.1.5
     - name: wildfly
       repository: http://docs.wildfly.org/wildfly-charts/
-      version: 2.3.2
+      version: 2.3.2

todo-jakarta-data/charts/templates/postgres-configmap.yaml

@@ -0,0 +1,11 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: postgres-configmap
+  labels:
+    app: postgres
+data:
+  POSTGRES_DB: {{ .Values.db.database }}
+  POSTGRES_USER: {{ .Values.db.username }}
+  POSTGRES_PASSWORD: {{ .Values.db.password }}
+  PGDATA: /var/lib/postgresql/data/pgdata

todo-jakarta-data/charts/templates/postgres.yaml

@@ -0,0 +1,40 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: todo-jakarta-data-postgresql
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: todo-jakarta-data-postgresql
+  template:
+    metadata:
+      labels:
+        app: todo-jakarta-data-postgresql
+    spec:
+      containers:
+        - name: postgres
+          image: postgres:17
+          ports:
+            - containerPort: 5432
+              name: postgres
+          envFrom:
+            - configMapRef:
+                name: postgres-configmap
+          volumeMounts:
+            - name: pgdata
+              mountPath: /var/lib/postgresql/data
+      volumes:
+        - name: pgdata
+          emptyDir: {}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: todo-jakarta-data-postgresql
+spec:
+  ports:
+    - port: 5432
+      targetPort: postgres
+  selector:
+    app: todo-jakarta-data-postgresql

todo-jakarta-data/charts/values.yaml

@@ -2,21 +2,10 @@
 # This is a YAML-formatted file.
 # Declare variables to be passed into your templates.
 
-postgresql:
-  auth:
-    username: todos-db
-    password: todos-db
-    database: todos-db
-  architecture: "standalone"
-  primary:
-    podSecurityContext:
-      enabled: false
-      fsGroup: "auto"
-    containerSecurityContext:
-      enabled: false
-      runAsUser: "auto"
-      runAsGroup: ""
-
+db:
+  username: todos-db
+  password: todos-db
+  database: todos-db
 
 wildfly:
     build:
@@ -28,15 +17,24 @@ wildfly:
       env:
         # Env vars to connect to PostgreSQL DB
         - name: POSTGRESQL_DATABASE
-          value: todos-db
+          valueFrom:
+            configMapKeyRef:
+              name: postgres-configmap
+              key: POSTGRES_DB
         - name: POSTGRESQL_USER
-          value: todos-db
+          valueFrom:
+            configMapKeyRef:
+              name: postgres-configmap
+              key: POSTGRES_USER
         - name: POSTGRESQL_PASSWORD
-          value: todos-db
+          valueFrom:
+            configMapKeyRef:
+              name: postgres-configmap
+              key: POSTGRES_PASSWORD
         - name: POSTGRESQL_DATASOURCE
-          value: ToDoRepository
+          value: ToDos
         - name: POSTGRESQL_SERVICE_HOST
-          value: todo-backend-postgresql
+          value: todo-jakarta-data-postgresql
         - name: POSTGRESQL_SERVICE_PORT
           value: "5432"
         # Env to avoid OOME
@@ -46,8 +44,7 @@ wildfly:
           value: "96"
       initContainers:
         - name: check-db-ready
-          image: postgres:9.6.5
-          command: [ 'sh', '-c',
-              'until pg_isready -h todo-backend-postgresql -p 5432; 
-                    do echo waiting for database; sleep 2; done;' ]
-
+          image: busybox:1.36
+          command: ['sh', '-c',
+                    'until nc -z -v -w 2 todo-backend-postgresql 5432; 
+                     do echo "waiting for database"; sleep 2; done;']