From 896a39eb41831387a950d04dfb92885585967cfe Mon Sep 17 00:00:00 2001 From: Michael Schnell Date: Sun, 29 Dec 2019 10:03:31 +0100 Subject: [PATCH] Refactored doc and demo structure --- README.md | 103 ++++++++++++++++-- .../demo => demo}/create-person-command.json | 0 .../demo => demo}/create-person-command.sh | 0 .../docker-compose.yml => docker-compose.yml | 0 quarkus/README.md | 80 +------------- quarkus/command/README.md | 34 ++++++ quarkus/query/README.md | 36 ++++++ 7 files changed, 165 insertions(+), 88 deletions(-) rename {quarkus/demo => demo}/create-person-command.json (100%) rename {quarkus/demo => demo}/create-person-command.sh (100%) rename quarkus/docker-compose.yml => docker-compose.yml (100%) create mode 100644 quarkus/command/README.md create mode 100644 quarkus/query/README.md diff --git a/README.md b/README.md index 1113775..cc46637 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,102 @@ # ddd-cqrs-4-java-example Example applications that use [ddd-4-java](https://github.com/fuinorg/ddd-4-java) and [cqrs-4-java](https://github.com/fuinorg/cqrs-4-java) libraries and an [EventStore](https://eventstore.org/) to store the events (Event Sourcing). -## Java SE + CDI -Two standalone applications (Command & Query) using [Weld](https://weld.cdi-spec.org/) for dependency injection. +## Components -[More...](java-se-cdi) +### Shared +Common code for all demo applications (commands, events, value objects and utilities). [More...](shared) -## Quarkus -Two web applications (Command & Query) based on [Quarkus](https://quarkus.io/). +### Aggregates +DDD related code for all demo applications (aggregates, entities and business exceptions). [More...](aggregates) -[More...](quarkus) +### Java SE + CDI +Two standalone applications (Command & Query) using CDI for dependency injection. [More...](java-se-cdi) -## Spring Boot -Two web applications (Command & Query) based on [Spring Boot](https://spring.io/projects/spring-boot/). +### Quarkus +Two web applications (Command & Query) based on [Quarkus](https://quarkus.io/). [More...](quarkus) -[More...](spring-boot) +### Spring Boot +Two web applications (Command & Query) based on [Spring Boot](https://spring.io/projects/spring-boot/). [More...](spring-boot) + +## Getting started + +### Prerequisites +Make sure you have the following tools installed/configured: +* [git](https://git-scm.com/) (VCS) +* [Docker CE](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/) +* [Docker Compose](https://docs.docker.com/compose/) +* *OPTIONAL* [GraalVM](https://www.graalvm.org/) +* Hostname should be set in /etc/hosts (See [Find and Change Your Hostname in Ubuntu](https://helpdeskgeek.com/linux-tips/find-and-change-your-hostname-in-ubuntu/) for more information) + +Or simply use the [lubuntu-developer-vm](https://github.com/fuinorg/lubuntu-developer-vm) that has already everything installed. Then execute the following steps: +1. Download and install the developer VM as described +2. OPTIONAL: Change memory of VM to 6 GB (instead of 4 GB default) if you want to create a native image with GraalVM +3. Start the VM and login (developer / developer) +4. Open a console (Shortcut = ctrl alt t) +5. Run a small script that finalizes the setup of the developer virtual machine + ``` + bash <(curl -s https://raw.githubusercontent.com/fuinorg/ddd-cqrs-4-java-example/master/setup-lubuntu-developer-vm.sh) + ``` + +### Clone and install project +1. Open a console (Ubuntu shortcut = ctrl alt t) +2. Clone the git repository + ``` + git clone https://github.com/fuinorg/ddd-cqrs-4-java-example.git + ``` +3. Change into the project's directory and run a Maven build + ``` + cd ddd-cqrs-4-java-example + ./mvnw install + ``` + +### Start Event Store and Maria DB +1. Open a console (Ubuntu shortcut = ctrl alt t) +2. Change into the project's directory and run Docker Compose + ``` + cd ddd-cqrs-4-java-example + docker-compose up + ``` + +### Start command / query implementations +Start one command and one query microservice. + +- Quarkus Microservices + - [Command](quarkus/command) + - [Query](quarkus/query) + +- Spring Boot Microservices + - [Command](spring-boot/command) + - [Query](spring-boot/query) + +### Test +1. Open [http://localhost:2113/](http://localhost:2113/) to access the event store UI (User: admin / Password: changeit) +2. Opening [http://localhost:8080/persons](http://localhost:8080/persons) should show an empty JSON array +3. Open a console (Ubuntu shortcut = ctrl alt t) +4. Change into the demo directory and execute a command using cURL (See [shell script](demo/create-person-command.sh) and [command](demo/create-person-command.json)) + ``` + cd ddd-cqrs-4-java-example/demo + ./create-person-command.sh + ``` + Command console should show something like + ``` + Update aggregate: id=PERSON 84565d62-115e-4502-b7c9-38ad69c64b05, version=-1, nextVersion=0 + ``` + Query console should show something like + ``` + PersonCreatedEventHandler ... Handle PersonCreatedEvent: Person 'Peter Parker' was created + ``` +4. Refreshing [http://localhost:8080/persons](http://localhost:8080/persons) should show + ```json + [{"id":"84565d62-115e-4502-b7c9-38ad69c64b05","name":"Peter Parker"}] + ``` +5. Opening [http://localhost:8080/persons/84565d62-115e-4502-b7c9-38ad69c64b05](http://localhost:8080/persons/84565d62-115e-4502-b7c9-38ad69c64b05) should show + ```json + {"id":"84565d62-115e-4502-b7c9-38ad69c64b05","name":"Peter Parker"} + +### Stop Event Store and Maria DB and clean up +1. Stop Docker Compose (Ubuntu shortcut = ctrl c) +2. Remove Docker Compose container + ``` + docker-compose rm + ``` diff --git a/quarkus/demo/create-person-command.json b/demo/create-person-command.json similarity index 100% rename from quarkus/demo/create-person-command.json rename to demo/create-person-command.json diff --git a/quarkus/demo/create-person-command.sh b/demo/create-person-command.sh similarity index 100% rename from quarkus/demo/create-person-command.sh rename to demo/create-person-command.sh diff --git a/quarkus/docker-compose.yml b/docker-compose.yml similarity index 100% rename from quarkus/docker-compose.yml rename to docker-compose.yml diff --git a/quarkus/README.md b/quarkus/README.md index 153b5a8..7d47ecb 100644 --- a/quarkus/README.md +++ b/quarkus/README.md @@ -2,52 +2,7 @@ Example applications that uses [Quarkus](https://quarkus.io/), [ddd-4-java](https://github.com/fuinorg/ddd-4-java) and [cqrs-4-java](https://github.com/fuinorg/cqrs-4-java) libraries. Events are stored in an [EventStore](https://eventstore.org/) and the query data is retrieved from a [PostgreSQL](https://www.postgresql.org/) database. ## Prerequisites -Make sure you have the following tools installed: -* [git](https://git-scm.com/) (VCS) -* [Docker CE](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/) -* [Docker Compose](https://docs.docker.com/compose/) -* *OPTIONAL* [GraalVM](https://www.graalvm.org/) - -Hostname should be set in /etc/hosts (See [Find and Change Your Hostname in Ubuntu](https://helpdeskgeek.com/linux-tips/find-and-change-your-hostname-in-ubuntu/) for more information) - -Or simply use the [lubuntu-developer-vm](https://github.com/fuinorg/lubuntu-developer-vm) that has already everything installed. -Then execute the following steps: -1. Open a console (Ubuntu shortcut = ctrl alt t) -2. Install GraalVM - ``` - sdk install java 19.2.1-grl - ``` -3. Finalize GraalVM settings - ``` - echo "export GRAALVM_HOME=\"/home/developer/.sdkman/candidates/java/19.2.1-grl\"" >> ~/.profile - source source ~/.profile - $GRAALVM_HOME/bin/gu install native-image - ``` -4. Install zlib - ``` - sudo apt-get install libz-dev - ``` -5. OPTIONAL: Change memory of virtual machine to 6 GB (instead of 4 GB default) if you want to create a native image with GraalVM - -## Getting started -1. Open a console (Ubuntu shortcut = ctrl alt t) -2. Clone the git repository - ``` - git clone https://github.com/fuinorg/ddd-cqrs-4-java-example.git - ``` -3. Change into the quarkus directory and build the project - ``` - cd ddd-cqrs-4-java-example/quarkus - ./mvnw install - ``` - -## Start Event Store and Maria DB -1. Open a console (Ubuntu shortcut = ctrl alt t) -2. Change into the quarkus directory and run Docker Compose - ``` - cd ddd-cqrs-4-java-example/quarkus - docker-compose up - ``` +Make sure you installed everything as described [here](../). ## Run the command microservice in development mode 1. Open a console (Ubuntu shortcut = ctrl alt t) @@ -66,39 +21,6 @@ Then execute the following steps: ./mvnw quarkus:dev ``` 3. Opening [http://localhost:8080/](http://localhost:8080/) should show the query welcome page - -## Test -1. Open [http://localhost:2113/](http://localhost:2113/) to access the event store UI (User: admin / Password: changeit) -2. Opening [http://localhost:8080/persons](http://localhost:8080/persons) should show an empty JSON array -3. Open a console (Ubuntu shortcut = ctrl alt t) -4. Change into the demo directory and execute a command using cURL (See [shell script](demo/create-person-command.sh) and [command](demo/create-person-command.json)) - ``` - cd ddd-cqrs-4-java-example/quarkus/demo - ./create-person-command.sh - ``` - Command console should show something like - ``` - Update aggregate: id=PERSON 84565d62-115e-4502-b7c9-38ad69c64b05, version=-1, nextVersion=0 - ``` - Query console should show something like - ``` - PersonCreatedEventHandler ... Handle PersonCreatedEvent: Person 'Peter Parker' was created - ``` -4. Refreshing [http://localhost:8080/persons](http://localhost:8080/persons) should show - ```json - [{"id":"84565d62-115e-4502-b7c9-38ad69c64b05","name":"Peter Parker"}] - ``` -5. Opening [http://localhost:8080/persons/84565d62-115e-4502-b7c9-38ad69c64b05](http://localhost:8080/persons/84565d62-115e-4502-b7c9-38ad69c64b05) should show - ```json - {"id":"84565d62-115e-4502-b7c9-38ad69c64b05","name":"Peter Parker"} - ``` - -## Stop Event Store and Maria DB and clean up -1. Stop Docker Compose (Ubuntu shortcut = ctrl c) -2. Remove Docker Compose container - ``` - docker-compose rm - ``` # TODO ... (Does currently not work) diff --git a/quarkus/command/README.md b/quarkus/command/README.md new file mode 100644 index 0000000..5d230f7 --- /dev/null +++ b/quarkus/command/README.md @@ -0,0 +1,34 @@ +# cqrs4j-quarkus-example-command +Command microservice that uses [Quarkus](https://quarkus.io/), [ddd-4-java](https://github.com/fuinorg/ddd-4-java) and [cqrs-4-java](https://github.com/fuinorg/cqrs-4-java) libraries. Events are stored in an [EventStore](https://eventstore.org/). + +## Prerequisites +Make sure you installed everything as described [here](../../). + +## Run the command microservice in development mode +1. Open a console (Ubuntu shortcut = ctrl alt t) +2. Start the command microservice: + ``` + cd ddd-cqrs-4-java-example/quarkus/command + ./mvnw quarkus:dev + ``` +3. Opening [http://localhost:8081/](http://localhost:8081/) should show the command welcome page + +# TODO ... (Does currently not work) + +## *OPTIONAL* Build and run the command microservice in native mode +1. Make sure you have enough memory (~6-8 GB) on your PC or VM +2. Open a console (Ubuntu shortcut = ) +3. Build the native executable + ``` + cd command + ./mvnw verify -Pnative + ``` +4. Run the microservice + ``` + ./target/cqrs4j-quarkus-example-command-1.0-SNAPSHOT-runner \ + -Djava.library.path=$GRAALVM_HOME/jre/lib/amd64 \ + -Djavax.net.ssl.trustStore=$GRAALVM_HOME/jre/lib/security/cacerts + ``` + +**Issues** +- [Quarkus native command microservice fails with Yasson NullPointerException](https://github.com/fuinorg/ddd-cqrs-4-java-example/issues/2) diff --git a/quarkus/query/README.md b/quarkus/query/README.md new file mode 100644 index 0000000..1a506d4 --- /dev/null +++ b/quarkus/query/README.md @@ -0,0 +1,36 @@ +# cqrs4j-quarkus-example-query +Query microservice that uses [Quarkus](https://quarkus.io/), [ddd-4-java](https://github.com/fuinorg/ddd-4-java) and [cqrs-4-java](https://github.com/fuinorg/cqrs-4-java) libraries. Events are stored in an [EventStore](https://eventstore.org/) and the query data is retrieved from a [PostgreSQL](https://www.postgresql.org/) database. + +## Prerequisites +Make sure you installed everything as described [here](../../). + +## Run the query microservice in development mode +1. Open a console (Ubuntu shortcut = ctrl alt t) +2. Start the query microservice: + ``` + cd ddd-cqrs-4-java-example/quarkus/query + ./mvnw quarkus:dev + ``` +3. Opening [http://localhost:8080/](http://localhost:8080/) should show the query welcome page + + +# TODO ... (Does currently not work) + +## *OPTIONAL* Build and run the query microservice in native mode +1. Make sure you have enough memory (~6-8 GB) on your PC or VM +2. Open a console (Ubuntu shortcut = ) +3. Build the native executable + ``` + cd query + ./mvnw verify -Pnative + ``` +4. Run the microservice + ``` + ./target/cqrs4j-quarkus-example-query-1.0-SNAPSHOT-runner \ + -Djava.library.path=$GRAALVM_HOME/jre/lib/amd64 \ + -Djavax.net.ssl.trustStore=$GRAALVM_HOME/jre/lib/security/cacerts + ``` + +**Issues** +- [Quarkus native query microservice does not execute updates](https://github.com/fuinorg/ddd-cqrs-4-java-example/issues/1) +- [Building native query microservice fails with PostgreSQL (MariaDB works fine)](https://github.com/fuinorg/ddd-cqrs-4-java-example/issues/3)