bjfletcher/eventsourced-example

A Scala web application demonstrating event-sourcing best practices

Overview

This project demonstrates how to implement an event-sourced web application based on the Eligosource Eventsourced library. It is based on former work that has been described in the articles

• Building an Event-Sourced Web Application - Part 1: Domain Model, Events and State
• Building an Event-Sourced Web Application - Part 2: Projections, Persistence, Consumers and Web Interface

Compared to the old implementation, the whole service and persistence layer have been re-written and the domain events are now decoupled from the immutable domain model. The web UI and the web API remain unchanged.

The example web application uses the Eventsourced library for both event-sourcing and command-sourcing. Furthermore, it implements the CQRS pattern and follows domain-driven design principles.

Legend:

• The domain model is a rich, immutable domain model. It is annotated with JAXB annotations for XML and JSON binding.
• The service layer implements the event-sourced and command-sourced actors (processors) together with service facades for asynchronous writes and synchronous, non-blocking reads of application state.
  • Processors manage application state via STM references.
  • For reading current state, services facades access STM references directly (concurrent reads).
  • For updating current state, services facades access STM references via processors where a single STM reference is updated by a single processor (single-writer-principle)
  • On the command-side of the implemented CQRS pattern is the InvoiceService that manages application state and serves consistent reads of invoices.
  • On the query side of the implemented CQRS pattern is the StatisticsService, a read model that serves eventually consistent reads about invoice update statistics.
  • The PaymentProcess is an example of a stateful, potentially long-running and event-sourced business process.
• The web layer provides a RESTful service interface to application resources and supports HTML, XML and JSON representation formats. It is built on top of Jersey and Scalate. A Play-based version will follow (which supports asynchronous responses in contrast to Jersey).
• The application configuration wires the pieces together.

Build

Clone the example application and compile it

git clone git://github.com/eligosource/eventsourced-example.git
cd eventsourced-example
sbt compile

Run

To start the example application, enter

> run-main org.eligosource.eventsourced.example.server.Webserver

at the sbt prompt. Then go to http://localhost:8080 and create some invoices.

…

The example application's RESTful service interface supports HTML, XML and JSON representation formats. Content negotiation is done via the Accept HTTP header. The following examples show how to get HTML and XML representations for invoice-3.

HTML

Click on http://localhost:8080/invoice/invoice-3. Provided you have created an invoice with id invoice-3 before, you should see something like

XML

curl -H "Accept: application/xml" http://localhost:8080/invoice/invoice-3

yields

<draft-invoice id="invoice-3" version="2">
    <total>12.8</total>
    <sum>12.8</sum>
    <discount>0</discount>
    <items>
        <item>
            <description>item-1</description>
            <count>1</count>
            <amount>4.1</amount>
        </item>
        <item>
            <description>item-2</description>
            <count>3</count>
            <amount>2.9</amount>
        </item>
    </items>
</draft-invoice>