KumuluzEE Axon Extension

KumuluzEE Axon Extension project allows an easy way to integrate the Axon framework for developing CQRS and DDD applications with the KumuluzEE microservice framework. The extension allows simple straightforward configuration of Axon components and offers annotation for auto-configuring aggregates and aggregates repositories. Furthermore the extension automatically registers all annotated event, command and query handlers.

Usage

You can enable KumuluzEE Axon by adding the following dependency:

<dependency>
    <groupId>com.kumuluz.ee.axon</groupId>
    <artifactId>kumuluzee-axon</artifactId>
    <version>${kumuluzee-axon.version}</version>
</dependency>

Automatic Configuration

The base Axon Framework is extremely powerful and flexible. What this extension does is to provide a number of sensible defaults for Axon applications while still allowing you reasonable configuration flexibility - including the ability to override defaults. As soon as you include the module in your project, you will be able to inject a number of Axon APIs into your code using CDI. These APIs represent the most important Axon Framework building blocks:

• CommandBus
• CommandGateway
• EventBus
• EventGateway
• QueryBus
• QueryGateway
• Serializer
• Configuration

Override configurations

You can provide configuration overrides for the following Axon artifacts by creating CDI producers for them:

• EntityManagerProvider
• EventStorageEngine
• TransactionManager (in case of JTA, make sure this is a transaction manager that will work with JTA. For your convenience, we have provided a JtaTransactionManager that should work in most CMT and BMT situations.)
• EventBus
• EventGateway
• CommandBus
• QueryBus
• CommandGateway
• QueryGateway
• TokenStore
• Serializer (All serializers may be overriden. To override an serializer, please name the producer "serializer" via the @Named annotation for the configuration of the global serializer. For the event serializer use "eventSerializer" and for the message serializer use the name "messageSerializer". If no @Named annotation is present, the serializer is assumed to be global)
• ErrorHandler
• ListenerInvocationErrorHandler
• CorrelationDataProvider
• EventUpcaster
• Configurer

Automatic configuration of Aggregates

You can use the Aggregate annotation to auto detect and configure the aggregate with the Axon configuration. The annotation has one property repository that is the repository name, the default name is the aggregate name with appended Repository.

@Aggregate(repository = "exampleRepository")
@ApplicationScoped
public class GiftCard {
    // aggregate class
}

@Produces
@ApplicationScoped
public Repository<GiftCard> exampleRepository() {
    // repository producer method
}

Automatic registration message handlers

All message handlers annotated with @EventHandler, @CommandHandler and @QueryHandler are automatically registered with the Axon configuration by the extension.

Axon Server configuration

Axon Server can be configured through the KumuluzEE Config framework. You can see below the configuration of the Axon Server in the config.yaml file:

axon:
  axonserver:
    componentName: kumuluzEE-axon-example
    servers: localhost:8024

Running Axon Server

By default the Axon Framework is configured to expect a running Axon Server instance, and it will complain if the server is not found. To run Axon Server, you'll need a Java runtime (JRE versions 8 through 10 are currently supported). You can run it locally, in a Docker container (including Kubernetes or even Mini-kube), or on a separate server.

To run Axon Server in Docker you can use the image provided on Docker Hub:

$ docker run -d --name my-axon-server -p 8024:8024 -p 8124:8124 axoniq/axonserver
...some container id...
$

WARNING This is not a supported image for production purposes. Please use with caution.

If you want to run the clients in Docker containers as well, and are not using something like Kubernetes, use the "--hostname" option of the docker command to set a useful name like "axonserver", and pass the AXONSERVER_HOSTNAME environment variable to adjust the properties accordingly:

$ docker run -d --name my-axon-server -p 8024:8024 -p 8124:8124 --hostname axonserver -e AXONSERVER_HOSTNAME=axonserver axoniq/axonserver

When you start the client containers, you can now use "--link axonserver" to provide them with the correct DNS entry. The Axon Server-connector looks at the "axon.axonserver.servers" property to determine where Axon Server lives, so don't forget to set it to "axonserver".

Disabling extension

The extension can be disabled by setting the kumuluzee.axon.enabled configuration property to false.

Changelog

Recent changes can be viewed on Github on the Releases Page

Contribute

See the contributing docs

When submitting an issue, please follow the guidelines.

Issues related to KumuluzEE itself should be submitted at https://github.com/kumuluz/kumuluzee/issues.

License

MIT

References

• Axon framework Github
• Axon extension CDI Github