Command Query Responsibility Segregation (CQRS) is an architectural style that makes a clear distinction between commands, which tell an application to do something, and queries, which are requests for information from an application. This distinction comes from the fact that the requirements (and thus also the model) for the execution and validation of commands are significantly different than those for queries. Events play an important role in the synchronization of application state resulting from executed command.

Applying a CQRS style architecture involves the development of quite a lot of “plumbing” code: event dispatching, asynchronous event processing, transactions, etc. cqrs4j, an Apache 2 licensed open source framework, takes care of all the plumbing for you. Read on to find out how…

A brief introduction to CQRS

As I stated above, CQRS makes a distinction between the model that validates and executes commands and the model that is used for providing state information. This is quite significantly different than how most (web)app applications are build nowadays. In fact, the model used for commands (the box named “Domain” in the image below), does not expose any state, at all. You might wonder, but how do I know what to show in the front end? That comes directly from your data sources using a thin data layer. I’ll explain how the data gets there in a minute.cqrs_architecture

When a command comes in, it will load an aggregate from the repository and execute certain operations on it. As a result of these operations, the aggregate produces events, which are picked up for storage by the repository and for dispatching by the event bus. The event bus will dispatch each event to all (interested) event handlers. Some of these event handlers will perform actions on other (related) aggregates, some others will update the database tables they manage.

Having handlers update the data in the database means that your tables do not have to be normalized anymore. Instead, CQRS allows you to optimize your tables for the way you want to query them. This makes the data layer processing your queries really simple, and maintainable.

Furthermore, since all state changes are initiated by events, these events become a reliable source for an audit trail. By storing these events, you have an audit trail that you can use to replay the entire application history. Instead of just seeing “current application state” only, you can see all the changes that have led to the current state, providing valuable information trying to find bugs or deal with customer complaints.

The asynchronous and event driven nature of CQRS makes it extremely valuable for complex applications that have different views on the information in the application. Integration with third party systems that need to be notified of certain changes in your application –and vice versa–  is a lot easier if you use an event driven approach. And since event handling is done asynchronously, the application is more responsive and easier to scale.

But as you notice, there is quite a lot of processing and pushing around of events. When you have a customer breathing up your neck, you don’t want to be developing infrastructure code. You would want to be focusing on the business logic, which is quite complex by itself.


cqrs4j is a Spring-oriented framework that provides the most important building blocks of a CQRS architecture. Creating an aggregate becomes really simple. You don’t have to worry about managing the storage and dispatching of (uncommitted) events. Event sourcing becomes as easy as wiring two beans in your application context.

Annotation support

cqrs4j comes with out-of-the-box annotation support. This makes is really easy to wire event handler methods. cqrs4j can automatically subscribe all your event handlers to the event bus and delegate all relevant events to the appropriate event handlers. Enabling annotation support is as easy as wiring a single bean in your application context.

Spring Integration support

Spring Integration is a framework that allows easy developments of a Messaging systems using the pipes-and-filters architecture. This fits nicely with most of the event dispatching process of CQRS. cqrs4j has support for Spring Integration, which allows you to publish all events as messages on a Spring Integration channel. Sending messages through JMS queues, via email, or through file system storage will only take a few lines of (XML) configuration.

Transaction support

If you update your database tables through incoming events, dealing with them one-by-one in a transaction can become time consuming and take up too much resources of your database. With cqrs4j, you can configure transactions just by setting the @Transactional annotation on your event handlers. You can also configure how many events should be handled in a single transaction.

cqrs4j project page

cqrs4j is an open source project, licensed under the Apache 2 license. Visit the project home page for the latest downloads, documentation and source code at code.google.com/p/cqrs4j.

We welcome your feedback

If you have any requests, remarks or other feedback, please let us know. You can report bugs and improvement requests on the issues page. You can also leave a message via the contact page or by leaving a comment.

Further reading

I have some more CQRS related blog articles coming up, but there are already quite a few around. Here is a few that helped me get started:

CQRS made easy with cqrs4j
Tagged on: