Transactional messaging for microservices
Clone or download
Latest commit 97b802d Oct 9, 2018
Permalink
Failed to load latest commit information.
.circleci upgraded Eventuate Local version Aug 23, 2018
buildSrc/src/main/groovy Added Javadoc and src jars to build Jul 29, 2017
eventuate-tram-aggregate-domain-events Removed .class files Aug 21, 2018
eventuate-tram-cdc-mysql-connector-autoconfigure Added Javadoc and src jars to build Jul 29, 2017
eventuate-tram-cdc-mysql-connector Upgraded to Eventuate Local 0.22.1.RELEASE to fix CDC ignoring schema… Sep 27, 2018
eventuate-tram-cdc-mysql-service Fixed #18 - Postgres image is failing to build Aug 21, 2018
eventuate-tram-commands-mysql-kafka-integration-test Postgres wal support. Mar 30, 2018
eventuate-tram-commands Removed unneeded dependencies Jul 31, 2018
eventuate-tram-consumer-kafka Merge pull request #14 from dartartem/kafka-props-hotfix Jul 12, 2018
eventuate-tram-events major refactoring Oct 23, 2017
eventuate-tram-in-memory Added DESTINATION header to messages. Added support wildcard subscrip… Feb 1, 2018
eventuate-tram-jdbc-kafka Added Javadoc and src jars to build Jul 29, 2017
eventuate-tram-messaging Added DESTINATION header to messages. Added support wildcard subscrip… Feb 1, 2018
eventuate-tram-mysql-kafka-integration-test Fixing usage of kafka properties. Jul 6, 2018
eventuate-tram-producer-jdbc removed unneeded dependency Jul 29, 2018
eventuate-tram-test-util major refactoring Oct 23, 2017
eventuate-tram-testing-support-spring-cloud-contract Fixed #18 - Postgres image is failing to build Aug 21, 2018
eventuate-tram-testing-support Added libraries to support testing Eventuate Tram applications Aug 21, 2018
gradle Upgraded Gradle Jun 26, 2018
mysql upgraded Eventuate Local version Aug 23, 2018
postgres Updated wal2json plugin Aug 28, 2018
.gitignore Removed .class files Aug 21, 2018
LICENSE.md major refactoring Oct 23, 2017
README.adoc Added support link Oct 9, 2018
ReliablePublication.png Revised README Dec 14, 2017
_set-env.sh Refactoring env scripts. Apr 2, 2018
build-and-test-all-cdc-mysql-binlog.sh Upgraded to Eventuate Local 0.22.1.RELEASE to fix CDC ignoring schema… Sep 27, 2018
build-and-test-all-cdc-postgres-polling.sh Upgraded to Eventuate Local 0.22.1.RELEASE to fix CDC ignoring schema… Sep 27, 2018
build-and-test-all-cdc-postgres-wal.sh Upgraded to Eventuate Local 0.22.1.RELEASE to fix CDC ignoring schema… Sep 27, 2018
build-and-test-all-images.sh cleaned up build-and-test scripts Nov 20, 2017
build-and-test-all-mysql-binlog.sh Upgraded to Eventuate Local 0.22.1.RELEASE to fix CDC ignoring schema… Sep 27, 2018
build-and-test-all-postgres-polling.sh Postgres wal support. Mar 30, 2018
build-and-test-all-postgres-wal.sh Postgres wal support. Mar 30, 2018
build-and-test-everything.sh Postgres wal support. Mar 30, 2018
build.gradle major refactoring Oct 23, 2017
deploy-artifacts.sh Reordered build steps Nov 20, 2017
docker-compose-cdc-mysql-binlog.yml Postgres wal support. Mar 30, 2018
docker-compose-cdc-postgres-polling.yml Postgres wal support. Mar 30, 2018
docker-compose-cdc-postgres-wal.yml Postgres wal support. Mar 30, 2018
docker-compose-images.yml cleaned up build-and-test scripts Nov 20, 2017
docker-compose-mysql-binlog.yml upgraded Eventuate Local version Aug 23, 2018
docker-compose-postgres-polling.yml upgraded Eventuate Local version Aug 23, 2018
docker-compose-postgres-wal.yml upgraded Eventuate Local version Aug 23, 2018
gradle.properties Upgraded to Eventuate Local 0.22.1.RELEASE to fix CDC ignoring schema… Sep 27, 2018
gradlew Initial code Jul 29, 2017
gradlew.bat Initial code Jul 29, 2017
mysql-cli.sh Fix DB command line client Jun 25, 2018
postgres-cli.sh Fix DB command line client Jun 25, 2018
set-env-mysql-binlog.sh Refactoring env scripts. Apr 2, 2018
set-env-postgres-polling.sh Refactoring env scripts. Apr 2, 2018
set-env-postgres-wal.sh Refactoring env scripts. Apr 2, 2018
settings.gradle Added libraries to support testing Eventuate Tram applications Aug 21, 2018
wait-for-mysql.sh Adding scripts for postgres. Nov 10, 2017
wait-for-postgres.sh Adding scripts for postgres. Nov 10, 2017
wait-for-services.sh cleaned up build-and-test scripts Nov 20, 2017

README.adoc

Eventuate Tram (Transactional Messaging) framework

download

The Eventuate Tram framework enables a Java/Spring application to send messages as part of an database transaction. This enables an application atomically update state and send a message or a domain event. It is a foundation of ensuring data consistency within a microservice architecture.

Eventuate Tram (which was formerly known as Tarr) is described in more detail in my book Microservice Patterns and the getting started guide. It provides several messaging abstractions:

  • messaging - send and receive messages over named channels

  • events - publish domain events and subscribe to domain events

  • commands - asynchronously send a command to a service and receive a reply

How it works

Eventuate Tram messaging implements the Application events pattern. An message producer inserts events into an OUTBOX table as part of the ACID transaction that updates data, such as JPA entities. A separate message relay (a.k.a. CDC service) publishes messages to the message broker.

ReliablePublication

The message relay works in one of two ways:

Getting started

Please see the getting started guide.

Example applications

There are the following examples applications:

Got questions?

Don’t hesitate to create an issue or see

Need support?

Take a look at the available paid support options.

Transactional messaging

Send a message using MessageProducer:

public interface MessageProducer {
  void send(String destination, Message message);
}

Receive messages using:

public interface MessageConsumer {
  void subscribe(String subscriberId, Set<String> channels, MessageHandler handler);
}

See this example of transactional messaging.

Transactional domain events

The domain event package builds on the core APIs.

Publish domain events using the DomainEventPublisher interface:

public interface DomainEventPublisher {

  void publish(String aggregateType, Object aggregateId, List<DomainEvent> domainEvents);
  ...

Subscribe to domain events using a DomainEventDispatcher:

public class DomainEventDispatcher {
    public DomainEventDispatcher(String eventDispatcherId,
                DomainEventHandlers eventHandlers,
                ...) {
...
}

Handle the events using DomainEventHandlers:

public class RestaurantOrderEventConsumer {

  public DomainEventHandlers domainEventHandlers() {
    return DomainEventHandlersBuilder
            .forAggregateType("net.chrisrichardson.ftgo.restaurantservice.Restaurant")
            .onEvent(RestaurantMenuRevised.class, this::reviseMenu)
            .build();
  }

  public void reviseMenu(DomainEventEnvelope<RestaurantMenuRevised> de) {

See this example of transaction events.

Transactional commands

Transaction commands are implemented using transactional messaging.

Send a command using a CommandProducer:

public interface CommandProducer {
  String send(String channel, Command command, String replyTo, Map<String, String> headers);
  ...
}

Subscribe to commands using a CommandDispatcher:

public class CommandDispatcher {

  public CommandDispatcher(String commandDispatcherId,
           CommandHandlers commandHandlers) {
  ...
}

Handle commands and send a reply using CommandHandlers:

public class OrderCommandHandlers {


  public CommandHandlers commandHandlers() {
    return CommandHandlersBuilder
          .fromChannel("orderService")
          .onMessage(ApproveOrderCommand.class, this::approveOrder)
          ...
          .build();
  }

  public Message approveOrder(CommandMessage<ApproveOrderCommand> cm) {
    ApproveOrderCommand command = cm.getCommand();
    ...
  }

See this example of transactional commands.

Maven/Gradle artifacts

The artifacts are in JCenter. The latest version is:

download

There are the following API artifacts:

  • io.eventuate.tram.core:eventuate-tram-messaging:$eventuateTramVersion - core messaging APIs

  • io.eventuate.tram.core:eventuate-tram-events:$eventuateTramVersion - domain event API

  • io.eventuate.tram.core:eventuate-tram-commands:$eventuateTramVersion - commands/reply API

There are the following 'implementation' artifacts:

  • io.eventuate.tram.core:eventuate-tram-jdbc-kafka:$eventuateTramVersion - JDBC database and Apache Kafka message broker

  • io.eventuate.tram.core:eventuate-tram-in-memory:$eventuateTramVersion - In-memory JDBC database and in-memory messaging for testing

Running the CDC service

In addition to a database and message broker, you will need to run the Eventuate Tram CDC service. It reads events inserted into the database and publishes them to Apache Kafka. It is written using Spring Boot. The easiest way to run this service during development is to use Docker Compose. The Eventuate Tram Code Basic examples project has an example docker-compose.yml file.