axoniq / reference-guide

The Axon Reference Guide

Introduction

Welcome to the Axon Manual!

Axon provides the Axon Framework and the Axon Server to help build applications centered on three core concepts - CQRS (Command Query Responsibility Segregation) / Event Sourcing and DDD (Domain Driven Design).

While many types of applications can be built using Axon, it has proven to be very popular for microservices architectures. Axon provides an innovative and powerful way of sensibly evolving to event-driven microservices within a microservices architecture.

Please visit the AxonIQ website to learn more about AxonIQ and the Axon community. There, you will find information about Axon training, support options, upcoming and past events.

Breaking Changes in Axon Framework 4.7!

Against our normal approach towards minor releases, we sadly had to introduce breaking changes between Axon Framework 4.6 and 4.7. Our apologies for this.

To help you with your upgrade we have constructed a dedicated page here that helps you on your path to upgrade to 4.7. If you find any irregularities concerning your upgrade, be sure to reach out to us!

How to use this guide

The Reference Guide is split into 4 sections

Section Name	Purpose
Quick Start	Details the Quick Start toolkit that Axon provides to easily familiarize with the basic concepts of Axon Framework and Axon Server
Axon Framework	Details the building of Axon Framework based applications.
Axon Server	Details the Installation/Setup and Maintenance of Axon Server.
Axon Framework Extensions	Details the extensions that Axon Framework provides to integrate with existing enterprise infrastructure(s).

License(s)

The Axon platform consists of Axon Framework and Axon Server. It is provided by AxonIQ B.V. under the licenses described below.

• Axon Framework, as well as the Axon documentation and sample programs, are open source and provided under the Apache License v2.0.
• For Axon Server, licensing depends on the version.
  • The standard version, called "Axon Server", is open source and free to download and use. It is provided under an AxonIQ-specific open source license. While this license allows you to run the software freely in any environment, it is less permissive than the Apache License. For instance, it doesn't allow you as a licensee to create a derivative work.
  • The commercial version, called "Axon Server Enterprise", as well as the various "Packs", are closed source and provided under a commercial license agreement.

If you have any questions about licensing, or want to obtain a license to our commercial software, please contact us via axoniq.io or [email protected].

reference-guide's Issues

Handler matcher ordering of Event Processors

It is useful to know in which order Event Handler matchers (to Event Processors) are invoked. This ticket is related to this documentation.

To achieve this, extend the Configuring processors chapter.

Restructuring 4.0 - Introduction/quick-start

Communicate the presence of the Download page.

1. Get everything you need by downloading QuickStart archive

2. Unzip AxonQuickStart-VERSION.zip

3. Run the Axon Server: $ java -jar AxonServer/axonserver-VERSION.jar

4. Axon Server web dashboard should be available here http://localhost:8024/

5. Run the demo application: $ cd giftcard-demo && ./mvnw spring-boot:run

6. Demo application should be available here http://localhost:8080/

7. Explore the README.md

[4.0] License

Decribe Section 3.B: Event Handling

Provide a description on how to handle and dispatch EventMessages throughout an Axon application.

Add reference to old documentation of Axon Framework 1 & 2

EventStore - SQL DDL

Ideally, SQL DDL related to the JPA/Jdbc event store should be added to the reference guide. Either as a dedicated section or as an appendix.

These DDL should be agnostic of the vendors such as Oracle, PostgreSQL, etc - but if this is not possible, at least the DDL related to major vendors should be provided.

Linked to: AxonFramework/AxonFramework#981

Decribe Section 3.C: Query Handling

Provide a description for handling and dispatching QueryMessages in an Axon application. In doing so, describe point-to-point, scatter-gather and subscription queries.

Saga Deployment constraints

Use case:

• imagine several micro-services.
• their choreography is managed by a saga.

I have some struggle understand how saga evolution will be supported, or which constraints need to be respected in order to avoid trouble.

To me there are three critical phases:

Before the saga-changes:

• is some versioning in the saga-store?
  -- is there some facility similar to event-up-caster?

During the deployment of the saga-change?

• throughout a rolling deployment, for some time there are two versions available.
• is there some control of which one applies?
  -- will there apply randomly and alternating?

After the deployment:

• in terms of trace-ability, will the saga-version be visible?

On the bottom-line request is of course to elaborate regarding this matter on the reference guide.
https://docs.axoniq.io/reference-guide/implementing-domain-logic/complex-business-transactions/implementing-saga

How to register a QueryHandler is not described

After reading 1.3.2 one would expect 1.3.3 to contain this information, but it doesn't.

Axon 4.0 module structure

Describe the new module structure in Axon 4.0.

Corresponding Axon issue: AxonFramework/AxonFramework#755

Restructuring 4.0 - setting-up/spring-boot

[4.0] Restructure Axon Framework chapters

AxonServer MetaData UUID persisting problem

Edit: Oh boy, completly wrong place. Closing

Hello

• axon 4.0.3
• axonserver 4.0.3

• java version "1.8.0_102"
  Java(TM) SE Runtime Environment (build 1.8.0_102-b14)
  Java HotSpot(TM) 64-Bit Server VM (build 25.102-b14, mixed mode)

Modifying the io.axoniq.demo:giftcard-demo:1.0 with a dispatch interceptor to insert meta data

axonConfiguration.correlationDataProviders().add( new SimpleCorrelationDataProvider( "userId" ) );

commandBus.registerDispatchInterceptor( messages -> ( index, message ) -> message.andMetaData( ImmutableMap.of( "userId", UUID.randomUUID() ) ) );

works as expected in projection with

public void on(IssuedEvt event, @MetaDataValue( "userId" ) UUID userId )

but is not persisted/serialized in AxonServer

{traceId=edee5d1a-a0c3-4260-866f-3997f3b67979, correlationId=edee5d1a-a0c3-4260-866f-3997f3b67979, userId=<Null>}

Using normal strings

commandBus.registerDispatchInterceptor( messages -> ( index, message ) -> message.andMetaData( ImmutableMap.of( "userId", UUID.randomUUID().toString() ) ) );

yields as expected

{traceId=5120c4d1-fcf7-4265-9e73-5bb8725b7b17, correlationId=5120c4d1-fcf7-4265-9e73-5bb8725b7b17, userId=2e652b2e-b1e7-4ada-b14a-e42b246c1614}

Greetings

[4.0] Add topics Migration Guide 3 -> 4

Add Axon 3 to 4 Migration Guide

For existing Axon 3 users, it would be beneficial to have a migration guide showing which issues a user might run in to. The axon-4-api-changes.md in the Axon Framework repository is a good starting point for this guide.

[4.0] Add Axon Server Query Reference

Restructuring 4.0 - operations-guide/setting-up-axon-server

Restructuring 4.0 -Introduction/architecture-overview

We have a main page introduction/architecture-overview/architecture-overview.md. Focus on message-driven approach: commands, queries, events, location transparency. CQRS as a pattern. Replace the arch image we have now with the latest one.

and two sub pages:

• introduction/architecture-overview/ddd-cqrs-patters.md (How CQRS fits in DDD patterns and concepts)
• introduction/architecture-overview/event-driven-microservices.md (High view architecture style. Bounded Context = Microservice, Aggregate = Microservice. Saga as orchestrator or choreographer)

[4.0] Move Axon Framework Reference Guide to Axon Reference Guide

Restructuring 4.0 - configuring-infrastructure-components/deadlines

Add Docker properties and configuration

Major Reference Guide Restructuring/Refactoring [4.0]

Major Reference Guide Restructuring/Refactoring [4.0]

Rewrite the chapters of the Axon Framework in the reference guide to reflect the logic in Axon 4.0.

The current version can be found on docs.axoniq.io. AxonIQ/reference-guide is the code base for the new reference guide.

As placing comments in the reference guide is not possible - hereby a list of ideas for changes

• Axon Framework Background -> Remove Terracotta / Gigaspaces reference
• Getting Started -> Is there a Gradle repository where we can link to?
• Configure Maven -> Mention the Spring Boot starter?
• Architecture Overview -> Is the SLF4J versioning still correct?
• Modules -> Is the setup of the modules still correct for 4.0?
• Modules -> axon-spring mention something about the starter here, or at least a reference to the Spring Boot starter example
• Commands -> Explain "wrapped using one of the CommandMessage implementations" a bit more.
• Event handling -> Rewrite to use the EventProcessingConfiguration instead of the EventHandlingConfiguration
• Saga -> Update with possibility to have multiple sagas in one event processor?
• Saga -> Quartz 2 still relevant?
• 1.1.3 Configuration API and [1.3.5] Spring Boot Auto Configuration](https://docs.axoniq.io/reference-guide/1.3-infrastructure-components/spring-boot-autoconfiguration) should link to each other or at least be in the same chapter.
• Event processing - Add information about replaying events

Optional dependencies that require you to provide versions need to be documented

When using SubscriptionQueries you will get build errors because reactor is used, but no version is specified/enforced, due to it being optional. We need to provide documentation on what dependencies there are, and which versions are safe to use. Currently you will find a reference to reactor core version 3.1 being safe, but that is not a usable version. 3.1.7.RELEASE is.

Change Maven central search link and Maven/Gradle dependencies info

The introduction paragraph to "Getting started" states:

...or configure a repository for your build system ([Maven](https://mvnrepository.com/artifact/org.axonframework/axon), Gradle, etc).

1. The link on the name "Maven" should point to the Maven project page (http://maven.apache.org/), just as "Gradle" should get one pointing at https://gradle.org/. The current link shows no information on Maven, nor information on how to configure the dependency.

2. Rather than use a link to mvnrepository.com, I suggest we use https://search.maven.org/search?q=g:org.axonframework%20AND%20v:4.0.

3. Add something like "Click the link on the version number to get snippets fro your pom.xml or build.gradle file, or re-introduce the snippet on our page.

4. Since the re-organisation of the package structure, there is no longer a "safe starter" such as the axon-core module, which gives you all the classes you need for common situations. Add a section "Axon Framework modules" to provide information on which modules are needed for what.

How to test the Query Model

The guide demonstrates how easy it is to test aggregates and sagas, i.e. https://docs.axoniq.io/reference-guide/implementing-domain-logic/command-handling/testing and https://docs.axoniq.io/reference-guide/implementing-domain-logic/complex-business-transactions/testing.

It would be great to show ways how to test projections.

There is no evident way to achieve that, despite IntegrationTests starting major portions of the spring-context, especially some entity manager.

Ideally unittesting over projections would be supported.

Include hint for JdbcSagaStore that Schema ist not automatically created

Currently nor the documentation under https://docs.axoniq.io/reference-guide/1.2-domain-logic/sagas#saga-repository-and-saga-store neither the Javadoc of JdbcSagaStore does state, that the database schema is not initialized automatically.
It would be helpfult to give a hint that you actually need to do this for the JdbcSagaStore to work somewhere.

UOW returns a message

Add a note about UOW result.

Decribe/update Section III.A: Command Handling

Provide a description on how to handle and dispatch CommandMessages throughout an Axon application. Has dedicated sections for Event Sourced Aggregates, State-Stored Aggregate, Testing, External Command Handlers and Multi-Entity Aggregates.

Restructuring 4.0 - configuring-infrastructure-components/event-processing

[3.4] Merge open branches to 3.4 reference guide

Currently, the following branches are still in the AxonFramework/ReferenceGuide project and are copied over to this (AxonIQ/reference-guide) project.

The branches should be merged to the 3.4/master branch or should be deleted

• deadlines
• distribution-considerations
• feature/34
• feature/61

[4.0] Deprecate Axon Server documentation in Axon Server project

The Axon Server documentation is included in the Axon Reference Guide. Duplicate information should be prevented so the Axon Server documentation should be removed from the Axon Server project

Change Reference Guide urls on http://www.axonframework.org/download/

Change

• [3.3] http://docs.axonframework.org/ to https://docs.axoniq.io/reference-guide/v/3.3/
• [3.2] http://docs.axonframework.org/v/3.2 to https://docs.axoniq.io/reference-guide/v/3.2/
• [3.1] http://docs.axonframework.org/v/3.2 to https://docs.axoniq.io/reference-guide/v/3.1/
• [3.0] http://docs.axonframework.org/v/3.2 to https://docs.axoniq.io/reference-guide/v/3.0/

Restructuring 4.0 - configuring-infrastructure-components/messaging-concepts

Restructuring 4.0 - configuring-infrastructure-components/command-processing

[4.0] Convert Axon Server information from AsciDoc to Markdown

Restructuring 4.0 - configuring-infrastructure-components/query-processing

Configuring Kafka as a Message Source

The current Reference Guide does no provide documentation on how to configure Kafka as a (Event) Message Source in an Axon application.
It would be beneficial if this is introduced. As this is about one of the Axon Framework extensions, it will be added in the appendix section.

Note that the Kafka extension is a release candidate - hence the contents of the guide and the code are subject to change.

• Original Message
  Axon4 Kafka integration documentation - inadequet.
  Would appreciate, if configuration related details are added along with sample example.

Provide some example how to use RoutingKey

The reference-guide is giving good intro. Keep it up! Good work!

One case that would benefit from further elaboration is the "routing-case":
When dealing with different application being connected to axon-server, i.e. axon4, or related use-case with axon3, how does RoutingStrategy apply.

What is @routingkey matched with?
It is AxonServerConfig.component or AxonServerConfig.clientId?

In this case which piece of code is executed in which place?
The command is emitted in the application A.
AxonServer will route Command to application B.
In application B the code of the aggregate will be executed.
Triggered events will be persisted in the event-store which again resides in the AxonServer.

I have plenty of doubt's about this last paragraph. An extension to the guide would support deeper understanding of newcomers to the CQRS matter.

[4.0] Architecture Overview

https://docs.axoniq.io/reference-guide/architecture-overview

[4.0] About 4.0

Write the README.md for the reference guide.

This information should also be present on https://axoniq.io/docs/axon-framework-3.3

[4.0] Include Axon Server in Axon Reference Guide

Provide disambiguition for Aggregates and Sagas

As a beginner with CQRS and axon-framework i ran into a pitfall.
I ponder how the reference guide could help others in my situation to avoid this one.

In fact i attempted to use an Aggregate instead of Saga.
More precisely i emitted to Commands aiming the exact same @TargetAggregateIdentifier.

As a result i got AXONIQ-2000 complaining about an event being inserted with sequence-number 0, where 1 was expected. See AxonFramework/AxonFramework#952 for the full stack-trace.

As i read deeper into the guide, the chapter about saga pattern starts in the right way saying that sagas in contrast to aggregates can last long time and can wrap several commands.

What would probably help is to make clear how far you can get with Aggregates and where to start using Sagas.

This can surely be achieved by a better error-message when one is attempting. On the other hand i guess there is some background that is underlying to the assumption that the expected sequence-number should be one.

Invalid link "Customizing the Docker image of Axon Server"

The link to "Customizing the Docker image of Axon Server" documentation seems to be invalid.

See https://docs.axoniq.io/reference-guide/operations-guide/setting-up-axon-server/launch#starting-axon-server-in-a-docker-container

Update default values for some client configuration properties

axon.axonserver.initial-nr-of-permits = 1000
axon.axonserver.new-permits-threshold = 500
axon.axonserver.nr-of-new-permits = 500

[3.0-4.0] Relink URLs to docs.axoniq.io instead of docs.axonframework.org

With moving the reference guide from docs.axonframework.org to docs.axoniq.io, we still have some old urls in de codebase. These should all point to axoniq.io based urls.

These changes should be applied on all version branches including master

[4.0] Textual changes and check for required changes

Check the reference guide on typos, inconsitency, etc.

Also with reading the reference guide, post suggestions for updates in #6

Unclear section titles about deadlines

The "Deadline handling" subsection under "Complex Business Transactions" doesn't mention @DeadlineHandler and gives no indication that there's a completely separate deadline handling API in addition to the event scheduler.

Builder pattern impacts

Find and update all components within the docs which are affected by builder patter changes.

[4.0] Restructure Axon Server content