Eventuate Tram basic examples

This project is part of Eventuate, which is a microservices collaboration platform. It consists of a basic set of Spring Boot-based examples that show how to use Eventuate Tram, which is a framework for transactional messaging. Eventuate Tram sends and receives messages as part of a database transaction, which maintains data consistency. It ensures that your application atomically updates the database and sends messages. Eventuate Tram also ensures that your message handlers are idempotent.

About the examples

There are the following examples:

• Messaging - sending and receiving messages

• Event publishing/subscribing - publishing of and subscribing to domain events

• Command/async reply - sending commands and receiving replies

Each example has a producer service and at least one consumer service.

Supported databases and message brokers

The examples support a variety of databases and message brokers:

• Databases: MySQL, PostgreSQL

• Message brokers: Apache Kafka, RabbitMQ, and ActiveMQ

There are the following Gradle properties that specify which infrastructure services to use:

• messageBroker - specifies the messageBroker, which can be kafka, rabbitmq, or activemq. It defaults to kafka.

• database - specifies the database, which can be mysql or postgres. It defaults to mysql.

• mode - specifies how the Eventuate CDC service reads the transactional outbox table. It defaults to binlog for MySql and wal for Postgres. It can also be set to polling for Postgres.

Various Gradle tasks for building, and running the services can be configured with these properties. For example,

./gradlew  -P messageBroker=activemq -P database=postgres someTask

executes someTask using Postgres and ActiveMQ.

Running the infrastructure services

Before running the examples, you need to start the infrastructure services:

$ ./gradlew startServices -P messageBroker=kafka -P database=mysql

Similarly, you can stop the services by running:

$ ./gradlew stopServices -P messageBroker=kafka -P database=mysql

About the messaging examples

The examples are in the messages directory. There are two services:

• eventuate-tram-examples-basic-message-producer - a service that implements a POST /produce endpoint that sends a message to a channel

• eventuate-tram-examples-basic-message-consumer - a service that subscribes the channel

This command starts the producer:

$ ./gradlew :messages:eventuate-tram-examples-basic-message-producer:bootRun

This command starts the consumer:

$ ./gradlew :messages:eventuate-tram-examples-basic-message-consumer:bootRun

You can then send a message to the producer:

$ http POST localhost:8080/produce accountId=101

You should see a 2024-04-02 13:42:29.644 INFO 66525 --- [pool-1-thread-1] i.e.t.e.b.e.subscriber.MessageHandler : Got message …​ log entry in the consumer.

About the event publishing/subscribing examples

These examples are in the events directory. There are three services:

• eventuate-tram-examples-basic-event-publisher - a service that implements a POST /publish endpoint publishes an event to a channel

• eventuate-tram-examples-basic-event-subscriber - a service that subscribes to the event channel

• eventuate-tram-examples-basic-event-cqrs-subscriber - a subscriber service that does NOT use the (relational) database to implement message handler idempotency

The following command starts the producer:

$ ./gradlew :events:eventuate-tram-examples-basic-event-publisher:bootRun

This command starts the subscriber:

$ ./gradlew :events:eventuate-tram-examples-basic-event-subscriber:bootRun

This command starts the CQRS subscriber:

$ ./gradlew :events:eventuate-tram-examples-basic-event-crqs:subscriber:bootRun

This command triggers the publishing of event:

$ http POST localhost:8080/publish accountId=10 amount=12

About the command/async reply examples

These examples are in the commands directory. There are two services:

• eventuate-tram-examples-basic-command-producer - a service that implements a POST /send endpoint sends a command to a channel

• eventuate-tram-examples-basic-command-consumer - a service that subscribes to a command channel and sends a reply

This command starts the producer:

$ ./gradlew :commands:eventuate-tram-examples-basic-command-producer:bootRun

This command starts the consumer:

$ ./gradlew :commands:eventuate-tram-examples-basic-command-consumer:bootRun

You can then send a command to the consumer:

$ http POST localhost:8080/send customerId=101

Runnning the tests

After starting the infrastructure services, you can also run the tests:

$ ./gradlew build

For more information

Please read the Eventuate Tram getting started guide or look at the examples.