dodex-akka
v2.1.1
Published
A scala asynchronous server for Dodex and Dodex-mess
Downloads
35
Maintainers
Readme
doDex-akka, a scala asynchronous/reactive client to doDex-vertx supporting the Cassandra nosql database for Dodex, Dodex-input and Dodex-mess
Install Assumptions
- Java 17 or higher installed with JAVA_HOME set.
- Scala 3.4.2 and
sbt
installed. - Node/npm javascript package manager installed.
- Docker(to install a test Cassandra container) or installed Cassandra
- Optionally
cqlsh
Motivation and Summary
A maiden voyage into the Scala, Akka and Cassandra world. The Akka client attaches to the Vertx Event Bus Bridge using TCP. Daniel Stieger's project @ https://github.com/danielstieger/javaxbus is used to communicate with the event bus on the Vertx Server. On the Akka side this code was converted to Scala and used to fomulate the message. The development/testing environment uses either a Cassandra container or an installed networked Cassandra. View and change the configuration in application.conf
. The asynchronous/reactive code is much like Vertx using Futures and Promises. Conclusion, Akka is a good place to start if you want to learn Scala and the Actor/Behavior pattern. The need for a Dodex database is simple so Cassandra usage barely scratches the surface.
Note; dodex-Akka can be run/developed on most platforms since cqlsh is now supported with python 3.
Getting Started
Download methods:
npm install dodex-akka
gh repo clone DaveO-Home/dodex-akka
git clone
from https://github.com/DaveO-Home/dodex-akka
If you use npm install, move node_modules/dodex-akka to an appropriate directory.
Install Cassandra or use the provided script
cassDocker.sh
to create a Docker container. When using the Docker container, additional Cassandra configuration is not necessary to get started. The Cassandra container runs @ 127.0.0.1:9042.Edit
src/main/resources/application.conf
and change the following;- modify
cassandra-service
host values to reflect a networked Cassandra - modify
event.bus.dev.host
to reflect the location of the development Vertx micro-service - modify
event.bus.host
to reflect the location of the production Vertx micro-service - also change the
port
values if test and production are running on the same machine simultaneously. Make sure thebridge.port
value inapplication-conf.json
for the Vertx micro-service corresponds to these values.
- modify
cd <install directory>/dodex-akka
and executesbt
to enter the sbt shell and execterun
. This should install Scala dependencies and startup the micro-service in development mode against the installed Cassandra database. Review instructions below on Akka development.On the Vertx side, make sure dodex-vertx is running with
Cassandra
database set.- Method 1;
export DEFAULT_DB=cassandra
orSet DEFAULT_DB=cassandra
before starting theDodex-Vertx
micro-service. - Method 2; change
defaultdb
tocassandra
indatabase_config.json
file before starting vertx.
- Method 1;
With both Vertx and Akka sevices running, execute url
http://localhost:8087/test
in a browser. To test that theAkka
service is working, follow instructions forDodex-Mess
. If the message box displaysconnected
you are good to go.
Note: The Vertx service is started withCassandra
if the startup messageTCP Event Bus Bridge Started
is displayed.You can also run
http://localhost:8087/test/bootstrap.html
for a bootstrap example.Follow instructions for dodex at dodex-mess and dodex-input.
Using the Vert.x Mqtt Broker and Akka Mqtt Client
- The order of precedence for starting Sbt in development mode to run the Mqtt Client.
- Execute
sbt
,set run / fork := true
,~run mqtt=true
- Execute
export USE_MQTT=true
,sbt
,set run / fork := true
,~run
- In file src/main/resources/application.conf set use.dev.mqtt=true, execute
sbt
,set run / fork := true
,~run
- For production use use.mqtt=true
- The TCP/Event Bus connection is default.
- Execute
Note: To start the Vert.x Mqtt Broker, see dodex-vertx README
Operation
Starting in Dev Mode to test implementation; execute
sbt
and thenrun
. Thedodex-vertx
service should be running first, however ifdodex-akka
is started first, the Akka service will continue attempting the TCP handshake for a limited number of tries. This can be configured inLimits.scala
. Conversely, ifdodex-vertx
is shutdown, the Akka client will continue with attempts to reconnect a limited number of times, frequency can also be configured.Starting in Dev Mode to develop; execute
sbt
to start thesbt
shell
Note: These commands should work when changingAkka
code.- execute
set run / fork := true
, this allows the application to reload when shutting down withctrl-c
- execute
set run / javaOptions += "-Ddev=true"
for forked JVM and then execute~run
to start - modify some
Akka
code and executectrl-c
, while still in thesbt shell
and using~run
theAkka
service will restart. - When changing and restarting the
Vert.x
service, theAkka
service should auto restart.
- execute
Building a Production distribution - Review the
sbt
plugin documentation for detailsTry
sbt stage
this will build a production setup without packaging. You can execute by runningtarget/universal/stage/bin/akka-dodex-scala
. Make sure your production database is running.Execute
sbt "Universal / packageBin"
to package the application. It can then be moved to a proper machine/directory for extraction and execution. The generated package istarget/universal/akka-dodex-scala-2.0.zip
.Building a fat jar using the
assembly
plugin requires a hack for anAkka
application. Basically the plugin cannot determine the fullAkka
configuration.- Using a Java based package @ https://github.com/DaveO-Home/jin to generate the
Fat Jar
- Jin must be installed in the
src
directory. The simplist method is tocd src
and executegit clone https://github.com/DaveO-Home/jin.git
. - In the project directory where
GenFatJar
is located, executeexport WD=.
,export CD=${PWD}/target/classes
andmkdir target/classes
. - Execute
./GenFatJar
to build the Fat Jar. - The generated jar should be
target/scala-3.4.2/akka-dodex-scala-assembly-2.0.jar
. - Execute
scala target/scala-3.4.2/akka-dodex-scala-assembly-2.0.jar
to startup production. - Or using Java you can execute
./runUber
.
- Using a Java based package @ https://github.com/DaveO-Home/jin to generate the
Cassandra
- If
cqlsh
is installed, to access the local database, this might be useful -cqlsh 127.0.0.1 --cqlversion=3.4.6 --encoding=utf8
. - For a
Cassandra 4
setup this might be useful -cqlsh <production host> 9042 --cqlversion="3.4.6"
. - Other wise just execute
cqlsh
,use dodex;
anddescribe tables;
.
Test Dodex
- Make sure the demo Java-vertx server is running in development mode.
- Test Dodex-mess by entering the URL
localhost:3087/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.
Optimizing with Graalvm
Single Page React Application to demo Development and Integration Testing
- For details see https://github.com/DaveO-Home/dodex-vertx/blob/master/src/spa-react/README.md
- In the vertx directory .../src/spa-react/devl, the following commands can be executed, assuming the the app was installed in "spa-react" by running
npm install
. - After setting the database to
cassandra
, co-ordination amongAkka
,Vertx
andReact
builds is difficult to automate. Therefore usingnpx gulp test
andnpx gulp prod
will not work. For a test build usenpx gulp rebuild
and onceVertx
andAkka
are restarted, tests can be executed withnpx gulp acceptance
. For theReact
production build, usenpx gulp prd
.
Additional References
Scala, Sbt, Akka and Cassandra documentation.
ChangeLog
https://github.com/DaveO-Home/dodex-akka/blob/master/CHANGELOG.md
Authors
- Initial work - DaveO-Home
License
This project is licensed under the MIT License - see the LICENSE file for details