Dodex-helidon-mp NPM

dodex-helidon-MP

A synchronous server for Dodex, Dodex-Input and Dodex-Mess using the Helidon Virtual Threaded Java Framework.

Install Assumptions

Java 21+ installed with JAVA_HOME set.
Maven and Gradle 8.5.0 installed.
Javascript node with npm package manager installed.
Helidon cli client.

Install Dodex-Helidon-MP

Execute npm install dodex-helidon-mp or download from https://github.com/DaveO-Home/dodex-helidon-mp. If you use npm install, move node_modules/dodex-helidon to an appropriate directory.

Why Helidon MP

Helidon supports two frameworks, Helidon MP and Helidon SE. MP is an Java EE annotated microprofile configuration where as SE is a framework supporting reactive programming.
Java 21+ and frameworks using Virtual Threads(Helidon MP) may be performant using traditional synchronous programming versus non-blocking asynchronous code on modern computer chip architecture.
Microprofile compliant

Getting Started

Quick Getting Started (docker)

cd .../dodex-helidon-mp/src/main/resources/WEB/static and execute npm install --save to install the dodex modules.
In .../dodex-helidon-mp Execute docker build -t dodex-helidon:latest .
Execute docker run -d -p 8060:8060 --name dodex_helidon dodex-helidon:latest
View in browser; localhost:8060/test/index.html or localhost:8060/test/bootstrap.html
To verify that the image is working, execute docker exec -ti --tty dodex_helidon /bin/sh
To keep and run later, execute docker stop dodex_helidon and later docker start dodex_helidon
To cleanup execute docker stop dodex_helidon and docker rm dodex_helidon and docker rmi dodex-helidon
To verify cleanup execute docker imiages, execute docker rmi <image id> to remove unwanted images.
Note: Assumes that dodex-helidon-mp is setup to use the "h2" database, the default.

Building `dodex-helidon-mp`

cd .../dodex-helidon-mp/src/main/resources/WEB/static and execute npm install --save to install the dodex modules.
To build for development use the helidon client as it supports live-reload. Execute helidon dev, uses pom.xml.
The other build method is; cd .../dodex-helidon-mp and execute gradlew run. This should also install java dependencies and startup the server against the default h2 database.
Execute url http://localhost:8060/test/index.html in a browser.
You can also run http://localhost:8060/test/bootstrap.html for a bootstrap example.
Follow instructions for dodex at https://www.npmjs.com/package/dodex-mess and https://www.npmjs.com/package/dodex-input.

Operation

The Dodex-Helidon backend uses Hibernate/HikariCP to persist data.
The application is configured to use a Websocket-Endpoint and OpenAPI endpoints to communicate with frontend HTML/javascript.
Multiple databases are supported, to configure see;
- .../src/main/resources/META-INF/microprofile-config.properties for connection properties.
- .../src/main/resources/META-INF/persistence.xml for J2EE/JTA persistence units.
- .../src/main/java/dmo/fs/db/fac/DbConfiguration.java to change which database to use (String pu = "h2dev").
Once the connection properties are configured, the pu variable in DbConfiguration.java can be changed with one of the following:
- h2dev or h2prod
- postgresdev or postgresprd
- mariadbdev or mariadbprod
- oracledev or oracleprod
- mssqldev or mssqlprod
- ibmdb2dev or ibmdb2prod
Building the Production Jar with supporting libraries using Maven.
- Before building the Jar for production.
  - Make sure dodex is installed at ./src/main/resources/WEB/static by running npm install.
  - Also consider setting up a production database.
- Execute mvn package to generate the production jar(dodex-helidon-mp.jar) in ./target and ./target/libs.
- Execute java -jar target/dodex-helidon-mp.jar to startup the production server.
Building the Production Jar with supporting libraries using Gradle.
- Execute ./gradlew clean build to generate the production jar(dodex-helidon-mp.jar) in ./build/libs`.
- Execute java -jar build/libs/dodex-helidon-mp.jar to startup the production server.
Execute url http://localhost:8060/test/index.html or .../test/bootstrap.html in a browser.

Java Linting with PMD

Note: PMD is not ready for Java-21 - "ClassNotFoundException: net.sourceforge.pmd.ant.PMDTask". However, all of the PMD 7 deprecations have been fixed in dodexstart.xml.

Run gradlew pmdMain and gradlew pmdTest to verify code using a subset of PMD rules in dodexstart.xml
Reports can be found in build/reports/pmd

Test Dodex

Make sure the demo dodex-helidon-mp server is running in development mode.
Test Dodex-mess by entering the URL localhost:8060/test/index.html in a browser.
Ctrl+Double-Click a dial or bottom card to popup the messaging client.
To test the messaging, open up the URL in a different browser and make a connection by Ctrl+Double-Clicking the bottom card. Make sure you create a handle.
Enter a message and click send to test.
For dodex-input Double-Click a dial or bottom card to popup the input dialog. Allows for uploading, editing and removal of private content. Content in JSON can be defined as arrays to make HTML more readable.
Standalone Dodex can be used as a normal rolodex as well as a menu launcher(localhost:8060/test/bootstrap.html).

Dodex Groups using OpenAPI

A default javascript client is included in .../dodex-helidon-mp/src/main/resources/WEB/static/group/. It can be regenerated in .../dodex-helidon-mp/src/openapi/client/ by executing npm run group:prod.
The group javascript client is in .../src/grpc/client/js/dodex/groups.js and group.js.
Note: The client is included in the application by default.
See .../src/main/resources/META-INF/openapi.yaml for OpenAPI declarations. You can view and test the configuration for development at http://localhost:8060/openapi/ui/index.html. If there is an error, explore with /openapi/.
The implementation uses a REST api in the GroupResource class.

Installing in Dodex (already included in demo)

Implementing in a javascript module; see .../dodex-helidon-mp/handicap/src/grpc/client/js/dodex/index.js
- import { groupListener } from "./groups";
- in the dodex init configuration, add
```
...
.then(function () {
     groupListener();
...
```
Implementing with inline html; see .../dodex-helidon-mp/main/resources/WEB/static/test/index.html
- <script src="../group/main.min.js"></script>
- in the dodex init configuration, add
```
...
.then(function () {
     window.groupListener();
...
```
Using dodex-messaging group functionality
Note: Grouping is only used to limit the list of "handles" when sending private messages.
- Adding a group using @group+<name>
  - select Private Message from the more button dropdown to get the list of handles.
  - enter @group+<name> for example @group+aces
  - select the handles to include and click "Send". Members can be added at any subsequent time.
- Removing a group using @group-<name>
  - enter @group-<name> for example @group-aces and click "Send". Click the confirmation popup to complete.
- Removing a member
  - enter @group-<name> for example @group-aces
  - select a "handle" from the dropdown list and click "Send"
- Selecting a group using @group=<name>
  - enter @group=<name> for example @group=aces and click "Send"
  - Select from reduced set of "handles" to send private message.

By default the entry "dodex.groups.checkForOwner" in microprofile-config.properties is set to false. This means that any "handle" can delete a "group" or "member". Setting the entry to true prevents global administration, however, if the owner "handle" changes, group administration is lost.

The grouping function also implements Basic HTTP Security, see application.yaml. The basic security is enabled by setting security.jersey.enabled to true. A user logging in with the admin role can manipulate any group.

A Logout button on the demo dodex pages .../test/index.html and .../test/bootstrap.html is provided to change the basic login. It may require a cntl alt f5 and browser restart to work.