Skip to main content

Examples

Example project​

oncebox-example runs a publisher, a consumer and a load generator in Docker Compose, on any of the three databases and either broker:

ServiceRole
oncebox-producer-exampleAn order API that publishes order events through the outbox
oncebox-consumer-exampleConsumes them through the inbox
oncebox-traffic-generatorA Gatling scenario that generates load against the producer
oncebox-shared-contractEvent DTOs shared by both sides
Prometheus and GrafanaMetrics, with the oncebox dashboards provisioned

What it shows​

The producer's OrderService publishes in each of the three ways oncebox offers:

// the return value is the payload; a List result becomes one event per element
@Transactional
@OutboxPublish(eventType = "create-order")
public OrderDto save(OrderCreateDto dto) { ... }

// the payload is picked from the arguments with SpEL
@Transactional
@OutboxPublish(eventType = "delete-order", payload = "#id")
public void delete(Long id) { ... }

// programmatic, for a payload the method does not return
@Transactional
public OrderDto update(OrderUpdateDto dto) {
...
outboxPublisher.publish("update-order", mapper.toDto(order));
return mapper.toDto(order);
}

On Kafka the consumer reads orders one message at a time and orders.created in batches, both through @TransactionalConsumer; Redis backs the inbox cache.

Both services use oncebox.schema.mode: flyway, in the two situations an application can be in. The producer has Flyway migrations of its own for the orders table, and its Flyway and oncebox's run side by side with separate history tables. The consumer has none, so it switches Spring Boot's Flyway off with spring.flyway.enabled: false.

Running it​

From oncebox-example, build once, then start the stack with one broker and one database profile:

docker compose build
COMPOSE_PROFILES=kafka,postgres,test docker compose up

Use rabbit instead of kafka, and mysql or oracle instead of postgres. The test profile adds the traffic generator, Prometheus and Grafana. Keep the same COMPOSE_PROFILES for every docker compose command of one run: the profiles are passed to the services, so a different value recreates the producer and consumer containers.

The services take a minute or two to start. Grafana is at http://localhost:3000 (admin / admin) with the outbox and inbox dashboards loaded; the producer API is on port 8080. The example README lists every port.

To check that nothing was lost, compare counters rather than table rows - both services clean up after 10m: requests the generator completed, outbox_events_rate_total{status="processed"} on the producer and inbox_events_total{type="consumed"} on the consumer should be equal, with the DLQ empty.

Configuration recipes​

Ready configurations for common setups - several event types, RabbitMQ, production, an inbox, both sides in one service, local development - are in Configuration Recipes.