Stack Name - Axon

Synopsis

The is the base reusable implementation for Axon type tech stacks.  The stack includes:
  • Axon Framework:
    • CQRS implementation
    • Event Store using default store
    • Event Sourcing
    • Default message bus topology
    • Open source
  • Axon Server (Standard Edition)
    • Single node
    • Single context
    • Open source
  • Spring Boot:
    • Designed to simplify the bootstrapping and development of a new Spring application.
  • Kotlin:
    • Simplified declaration of data objects.
  • Hibernate:
    • Using Spring JPA
  • Swagger:
    • GUI to help invoke requests on the generated API

Details

Author dev@harbormaster.ai
Access Public
Derived From .java.tech.stack
Long Name Axon
Short Name Axon
Language(s) Java 11, YAML, XML, Velocity Macros
Git Url https://github.com/Harbormaster-AI/techstacks/tree/main/Spring Core
Example Project YAML https://github.com/Harbormaster-AI/cli/tree/main/samples/yamls/project.as.code

Contents

Along with what is supported by the parent  tech stack (.java.tech.stack), the following are overridden and additional capabilities:
  • Aggregate:
    • Axon Aggregate template for each entity in the domain model.  Contains command handlers and event source handlers.
  • API:
    • Kotlin templates for commands, events, queries, entities, enumerations, and value objects
  • App:
    • The main Application template used to configure, initiate, and run as a Spring Boot application.
  • Build/Maven:
    • Overrides the default Maven pom.xml file to create a Spring Boot self-contained web application.
  • Config:
    • Contains configurations for the overall application as well as aggregate specific snapshot definitions
  • Controller:
    • Template used to generate the Restful handlers for all CRUD functions for each entity and association within the model.
  • Delegate:
    • An abstract layer to separate the controllers from the underlying CQRS/Event system.
  • Eureka:
    • Optional Spring Cloud Eureka Discovery Server
  • Projector:
    • Event and query handlers for each entity within the domain model
  • Properties:
    • Contains the templates to generate the Hibernate XML database schema declarations.
  • Repository:
    • Custom repository for JPAEventStoreEngine usage
  • Subscriber:
    • Default subscribers to core system events
  • Test:
    • Test classes for exercising generated functionality
  • Validator:
    • Helper classes to validate the state for each generated CRUD command and query

Stack Options

enable-monitoringTurn on monitoring using Prometheus. Assumed Prometheus is running and accessible.booleandefault:true
Option Name description Type values
axon-framework
server-port Port for Spring Boot to listen on input default:8011
version Framework version input default:4.5.4
axonserver-token Token to provide Axon server when connecting. Not required for Axon Server SE. input
axonserver-context Default context to apply to the application. Not required for Axon Server SE input
entity-store-type The type to use to store entities input
  • h2
  • mysql
  • postgres
  • mongodb
entity-store-url URL to use to connect to the entity database. input ex: mongodb://localhost:27017/appdb
event-store-type The type to use to store events input
  • axon {default}
  • jpa:h2
  • jpa:mysql
  • jpa:postgres
  • mongodb
entity-store-url URL to use to connect to the event store if one is being used. input ex: jdbc:h2:~/appdb
database-name The name of the database. Also included in the entity url field input
database-username The user name to apply to login, if required input
database-password The password to apply to login, if required input
use-axon-server Is the Axon Server in use? boolean default: true
axonserver-servers URL to the Axon Server input default: localhost
enable-monitoring Turn on monitoring using Prometheus. Assumed Prometheus is running and accessible. boolean default:true
enable-tracing Turn on tracing using Jaeger boolean default:true
default-snapshot-threshold Default snapshot threshold to provide per aggregate. Can be overridden when defining an entity in the domain model input default: 50
snapshot-events-collection-name Collection name to use for snapshot events when MongoEventStoreEngine is in use input
domain-events-collection-name Collection name to use for domain events when MongoEventStoreEngine is in use input
enableDiscoveryClient Directive to ensure the generated app is a discoverable client boolean
generateEurekaDiscoveryServer Directive to generated a Eureka Discovery server. boolean
axon-server
useCluster Generates scripts to simply setting up a cluster of Axon Server nodes. Not yet supported boolean default:false
total-nodes When useCluster is true, determines the # of nodes to create. Not yet supported input default:3
first-node-url The URL of the 1st (primary) node to connect to. Not yet supported. input
cluster-contexts Default context to provision for a new cluster. Axon Server SE only supports a single context named ‘default’ input
internal-token Token each node in the cluster will exchange for validation during cluster initialization. Not yet supported input
datasource-url JDBC Url required to connect to the DB input
accesscontrol Controls access to the server or cluster boolean defualt: true
jaeger-endpoint End point as URL to a running instance of Jaeger. Required for monitoring input
enable-tracing Turn on tracing using Jaeger boolean default:true

Usage

If using a CI/CD platform such as CircleCI, AWS Codebuild, Jenkins, etc.., it is best to refer to the Pipeline YAML file generated for that platform. If not using a CI/CD platform refer to the instructions below on how to use the generated project.

To get started manually

In the root directory of the generated project is a generated Maven pom.xml file that contains the declarations and dependencies to run the application within a Jetty container. 
mvn spring-boot:run
This will cause a complete compilation and packaging of the application into a jar file capable of running as a Spring Boot application

Using Swagger

Swagger is included as part of a generated Axon project. It has a easy to UI available at: http://localhost:8011/swagger-ui Swagger simplifies testing invocations to the generated Rest Controllers. For entity in the domain model, access includes:
    • create
    • read
    • update
    • delete
    • findAll
Also include are end points to execute all single and multiple associations on any given entity.

Axon Event Storage Engines

By default, Axon uses a file-based storage to persist events. There is also support for JPA and MongoDB. Depending on the event-store-type indicated, Harbormaster will handle all the nuisances and details in order to generate the right code for each storage engine scenario.

Enabling Eureka Discovery

When enabled via configuration, Harbormaster takes care of creating a Netflix Eureka service registry then enabling the generated microservice to automatically register to a server, assuming one is discovered.

When generateEurekaDiscoveryServer is set to true, Harbormaster will generate a separate Spring Boot application to serve as a Eureka Discovery Server. As part of it, Harbormaster generates an application properties file, and a Maven pom.xml. To start the server first locate the Maven POM xml titled (src/eurekaserver/src/eureka-server-pom.xml) and issue the following command to start the Discovery Server:

mvn -f eureka-server-pom.xml -Dspring.profiles.active=eurekaserver spring-boot:run

Once the discovery server is running, turn your attention to building and running the generated app (microservice). When the app is finally run, visit your web browser and access the Eureka dash board at:

http://localhost:8761/

If the app successfully discovered and registered itself with the discovery server, it’s name will appear in the dashboard.