Command Query Responsibility Segregation (CQRS) is an architectural style that makes a clear distinction between commands that change the application state and queries that expose the application state.

Background

My interest in CQRS was triggered when I saw Greg Young explain “State Transitions in Domain-Driven Design” on InfoQ. In this interview, Greg explains how he sees that application would benefit from using separate models for state validation and transition on one side and maintaining a view on the current state on the other.

One of the problems that Greg describes is the fact that a single model is often used for different purposes. It is nicely illustrated by the SQL query below. It shows how the model chosen in the application is not suited for the purpose of providing certain information (messages between users, in this case).

queryBuilder.append(
  "m.*, " +
  "m.origin_participant_id as message_origin_participant_id, " +
  "po.first_name as message_origin_participant_first_name, " +
  "po.avatar as message_origin_participant_avatar, " +
  "po_ua.username as message_origin_participant_username, " +
  "CASE WHEN !isnull(po.fieldworker_project_id) THEN 'fieldworker' WHEN !isnull(po_ap.project_id) THEN 'fundraiser' ELSE 'player' END AS message_origin_participant_type, " +
  "po.city as message_origin_participant_city, " +
  "c.name as message_origin_participant_country, " +
  "pd.first_name as message_destination_participant_first_name, " +
  "pd.avatar as message_destination_participant_avatar, " +
  "pd_ua.username as message_destination_participant_username, " +
  "CASE WHEN !isnull(pd.fieldworker_project_id) THEN 'fieldworker' WHEN !isnull(pd_ap.project_id) THEN 'fundraiser' ELSE 'player' END AS message_destination_participant_type, " +
  "m.destination_participant_id as message_destination_participant_id " +
  "from internal_message m  " +
  "left join player po on m.origin_participant_id = po.id " +
  "left join (select player_id, project_id from ambassador_project where enabled = true group by player_id) po_ap on po_ap.player_id =  po.id " +
  "left join user_account po_ua on po.user_account_id = po_ua.id " +
  "left join country c on po.country_id = c.id " +
  "left join player pd on m.destination_participant_id = pd.id " +
  "left join (select player_id, project_id from ambassador_project where enabled = true group by player_id) pd_ap on pd_ap.player_id =  pd.id " +
  "inner join user_account pd_ua on pd.user_account_id = pd_ua.id " +
  "where m.destination_participant_id = ? "
);

Wouldn’t it be a lot nice to have a query such as the one below instead?

</pre>
SELECT * FROM messages WHERE receiving_participant = ?
<pre>

Achieving such queries is very easy, but doing so without making your model impossible to use for maintaining state integrity and guarding invariants is a lot harder. Well, unless you apply CQRS.

Architecture

The diagram below shows an overview of a typical 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.

Benefits

Matches the natural language used

At first glance, such an architecture might look very complex and over-engineered. However, after taking the first implementation steps, it felt pretty natural. In fact, when you explain the behavior of an application, you use a style that fits CQRS quite nicely: “when an order is approved, we send a confirmation email to the customer”.

Extensibility

Imagine an order management application. With CQRS, you could have an “OrderApproved” event, which is caught by a database updating event handler as well as one that sends an email to the customer with order information. If you later on decide to store the order information in an accounting tool as well, all it takes is adding an event handler that does the accounting integration. And since you can reload historic events as well, you can even reconstruct historic information to put in the accounting table.

Reliable audit trail

As I said above [see section Architecture], the model that is used to process command will generate events. These events are the sole source of state changes for the domain classes. If you want to load an aggregate from persistent storage, it will actually load all the past events of that aggregate. This process is called Event Sourcing. When events become too numerous, you can combine a number of historic events into a single snapshot event. The events that have been combined can then be archived for auditing purposes.

Event Sourcing turns your event storage into an extremely reliable audit trail. The events do no only show what happened and when, but they will also reveal the intention a user had. Not only is it an audit trail that will never move out-of-sync with your application, you can use the audit trail to actually replay all actions in the application. Events are not just a notification of state change, they are also the source of state change.

Transparent distributed processing

When using events as the trigger for state changes, you can easily distribute your application over multiple processing units (servers, JVM’s, whatever). Events can easily be serialized and sent from one server to another over JMS, via the file system or even email. The Spring Integration framework –a messaging framework – fits nicely with the event processing concept.

You could even let certain types of aggregates live on dedicated machines. This allows you to choose different SLA’s for different parts of you application, such as giving order creation a higher priority than sales reporting.

Performance and Scalability

Since event handling is done asynchronously, a user does not have to wait for all changes to be applied. Especially when integrating with external systems, this can improve liveness of an application significantly.

Another aspect of CQRS is that it heavily builds upon BASE (Basic Availability, Soft-state, Eventual consistency) transactions. Although the “eventual” part scares a lot of customers and developers, the price of distributed ACID transactions is one that customer typically resent. In most cases “eventual” is just a matter of several milliseconds. But you’re free to make that seconds, minutes or even hours if your SLA permits it (think of management reports that are only read once a week or month).

Asynchronous analysis

When you build a CQRS style application, all activity in your application is processed using events. This makes it easy to catch these events and monitor them for inconsistent behavior. Event analysis tools like Esper allow you to monitor event streams for patterns that indicate possible fraud.

For example, when you detect that a sudden large number of users has an increased amount of failed login attempts, you could decide to block these accounts for a small period of time. In one of our projects, we use RSA Adaptive Authentication to increase the level of authentication required when someone tries to login on an account that might be the subject of dictionary attacks.

cqrs4j – an open source CQRS Framework

A few days ago, I published the source code of a CQRS framework – cqrs4j – on Google code. This framework aims at reducing the amount of “plumbing” and boilerplate code to a minimum. It also provides integration support for Spring Integration and transactional event processing.

You can find project information, source code and documentation at http://code.google.com/p/cqrs4j/.

[Update: cqrs4j has been renamed to Axon Framework. You can find more information on www.axonframework.org].

Upcoming presentations and events

JTeam organizes monthly Tech Meetings, where interesting technologies are discussed. The January 2010 edition will contain a presentation about CQRS. Registration is required, but free of charge. The tech meeting is held on January 7th in our office in Amsterdam [directions] and starts at 16:00. It includes dinner.  Send us an email if you like to attend.

The DDDnl user group organizes a presentation and discussion session on March 9th, starting at 18:00. It is also held at the JTeam office in Amsterdam [directions]. Attendance requires registration with the DDDnl user group, which is completely free of charge. Visit dddnl.org for more information.

The increasing demands from the business have a direct influence on the applications complexity. Each time, especially when joining external projects, I am amazed by the way complexity is dealt with in most applications. “Building software isn’t rocket science”, but sometimes we do seem to make it just as complex.

In this article, I provide some insight in different forms of complexity, and how software development teams can design their application in order to deal with the ever growing demands from the business.

At the dawn of each software development project, the sky is blue and the grass is green. That’s the type of project most developers like to do. However, as time progresses and features are added and changed (they are hardly ever removed, for some reason), the developers become entangled by their own code. Concepts –in which lots of time was invested to get them defined- become muddled and intentions of methods and services become vague. Eventually, the application will evolve into a Big Ball of Mud.

Causes of complexity

The degree in which the project team deal with complexity significantly influences the speed at which a codebase evolves into a ball of mud. There are numerous sources for complexity, that can be separated into three categories.

It is important to distinguish the different causes of complexity

Project Environment

The first source is the project environment itself. This mainly includes the availability of resources (e.g. people, money, knowledge) and the management style of the project manager and customer. Some project managers truly believe that when a developers estimates a piece of work at 1 week, that the sentence “I’ll give you 3 days” will actually do good to the project on the long term. Although an interesting topic, it is not the type of complexity I want to deal with in this post.

Technical Complexity

Another aspect influencing complexity is the technical environment of the project. What are the frameworks and platforms used in the development and deployment of the software. As with any technology, it is important to know the powers and limitations of each framework. If a framework requires expert knowledge to interact with it, then try to abstract that knowledge away into separate modules.

Every development team contains a couple of developers that is very well capable of solving these technical solutions. However, once solved and abstracted away, this technical complexity is mitigated and hardly a risk to the project. Of course there are extremes, where project heavily rely on bleeding edge technology. On those projects, you’re likely to keep a high level of technical complexity in the project. But no matter what, it should be clearly separated from the other type, discussed in the next paragraph.

Business Complexity

The third aspect is the one I will be focusing on in this post: the business domain. It is the sum of the knowledge, rules and activities of your customer that makes them survive. Solving the problems in this domain is often highly complex, but not unsolvable.

The majority of the business complexity is composed of the business rules. In contrast to the technological environment, the business environment is continuously in motion. And for some reason, this always means the addition of new rules and the changing of old ones, hardly ever removing them. The result of this process is an ever-growing application with increasing complexity.

The next sections cover a few guidelines that help you manage complexity and maintain it in acceptable ranges. In the end, people have to be able to understand the code.

Application Layering

The use of layers in software engineering is a concept I encounter in almost any project I join. The boundaries and definitions of these layers, though, are often fuzzy or undefined. The result is that, as the project progresses, different types of concerns leak into layers of the application where those concerns do not belong.

When correctly defined, layers can help developers make a clear separation between different types of complexity. Solve technical issues in another layer (e.g. the infrastructure layer) than the business complexity (e.g. application or service layer). Define clear boundaries between these layers and make sure each developer understands and respects them.

Use a model

The real world as a whole is useless when it comes to solving problems in software engineering. If you’re in the theatre ticket selling business, you don’t care that seats come in different styles, different colors and that some types of seats have legs. In other words, you don’t care what a seat is in the real world. I don’t expect to be telling new stuff here, but for some reason, I see it go wrong many times.

A common mistake I encounter in programs is that there is no real model at all. Well, there is a modules in the project called model, and it contains classes with getters and setters. Technically, it is a model, but is has been simplified to the extent that it is pretty much useless in solving the business problems. These problems are then solved in the service layer. But with the additions of new rules, this layer grows out of proportions with in some cases hundreds of methods, some of which are quite-the-same-but-not-really.

Another pitfall is the desire to make their model similar to the real world. The real world is not relevant to the application. An application needs to solve problems. The real world might just not be the ideal place to do that. Instead, the business itself should drive the modeling choices. And if two parts of a business (e.g. divisions) have different views on the same actual thing, consider creating a different model for each one of them.

A third consideration often forgotten in the development process is that not every part of the application should have to use the same model. A model is used to solve (complex) problems. Each part of an application solves different problems in the domain. A logical conclusion is that these parts do not necessarily ask for the same model. A good indicator for the possibility of splitting the model is that a single word is used in different contexts, and has a different meaning in each context. The word “Flight” will mean different things to the ground crew and the cabin crew. They will all have different intents when using the concept of a Flight. Combining all these intents into a single (shared) domain concept will most likely clutter your domain and make it harder to understand.

Watch your language

Ideally, the names of the concepts in the model reflect the actual words used in the business. If a new concept is added to the model, that name should be introduced in the business as well. Eric Evans calls this the “Ubiquitous Language”, the language used by all people and software involved in the domain the software runs in.

Why is this important? It helps new developers on a project. If they are familiar with the terminology, they will most likely understand the application right away. If they don’t, they will pick up the jargon faster and be able to talk to domain experts earlier.

It will also help in finding the locations where changes need to be made. If the model is correct (i.e. fits the business nicely), the language the domain expert uses will pinpoint you to the location where changes need to be made.

Modularity

Where simple applications will contain just a few concepts (where each concept is implemented as one or few classes), large applications may contain literally hundreds or thousands of concepts. A human being is simply not able to maintain a good overview of that amount of concepts.

Therefore, separate related concepts into modules. Within a module, these concepts may have tight relationships. In other words, the classes representing these concepts will have dependencies towards each other. Across modules, dependencies should be minimized. I often encounter dependencies between modules that don’t really need to be there. Removing them decreases application complexity and increases its maintainability. Especially “Entity”  to “Entity” relationships should be avoided as much as possible.

For example, let’s say we have an Order that references a Product, both in different modules as different departments manage the lifecycle of these objects. What happens if the Product price changes? All orders containing that product (and most of them have probably been handled already) will change as well. The solutions is simple, add a property to the order that states the price at which the product was sold. What if other characteristics change? The name for example? Remember, we don’t care about the real world , where products don’t just change name, we care about the world the way the business wants it. Instead of referencing the Product entity as a whole, perhaps it is sufficient to copy the relevant data from the Product into the Order at the time the Order is created. Or perhaps the entity reference is only maintained for as long as the Order is being processed. This allows you to delete Product instances without losing data in the Orders module.

The choices you can make in keeping nicely separated modules heavily depend on the way the model has been built. The better the model is, the more flexibility you have in making choices that help your application.

Conclusion

In this post, I have briefly touched a few types of complexity encountered in software projects. Don’t deal with multiple types of complexity in one location (i.e. layer) in your application. Make a clear separation between these to prevent technical choices from interfering with your business logic and vice versa.

When it comes to business logic, try to make a model that fits the way the business likes to work. Don’t try to make it look like the real world. That world has proven to be less than ideal when it comes to solving complex problems.

Use the Ubiquitous Language to define the terms and concepts in your model. This helps new developers to learn the language faster and get a better understanding of the application.

Finally, when the number of concepts expands beyond human capability of maintaining an overview of them, separate concepts into modules. Choose your modularity carefully. Try to keep dependencies tight inside the module, while limiting the dependencies between modules.

The app I am currently building is getting larger every day, and so is the main Activity class! Because my main activity contains a TabHost with a bunch of tabs, it also contains references to all individual view components contained in those tabs. All kinds of listeners are registered on those components so the activity contains some inner and anonymous classes as well. So you could say that this activity now has way too much responsibility! What I was looking for, is a way to separate the main activity into multiple parts, each with its own clear responsibility.

As it turns out, you can create custom components for a single piece of functionality within an Activity. Exactly what I was looking for!

Writing custom components

There are different ways to write custom components for your Android application.

• Simply extend a view class – If you want to add some behavior to an existing view class (like a TextView or a ListView) you can simply extend the class and override any method you like.
• Create an entirely customized component – Extend the View class and implement everything from scratch. Create listeners, properties, implement onMeasure() and onDraw(), etcetera. This might be useful if you want a very specific component and fine grained for your needs, for example a slider control.

Read about the above approaches here: http://developer.android.com/guide/topics/ui/custom-components.html.

Compound components

Unfortunately both of the above approaches are not what I was looking for in this case. I was looking for a way to simply group a bunch of view components in a separate class, also containing all related behavior logic. Luckily there is a way to do this! In the documentation they call it “compound components”, which is exactly what I was looking for. To explain it, I will try to demonstrate it with the following example:

public class MyActivity extends TabActivity {

    // First tab
    private LinearLayout linearLayout;
    private EditText editText;
    private ListView listView;

    // Second tab
    private RelativeLayout relativeLayout;
    private ImageView imageView;
    private TextView textView;
    private TextView anotherTextView;

    // Third tab
    private TableLayout tableLayout;
    private TextView tableLabel;

    @Override
    protected void onCreate(Bundle bundle) {
        super.onCreate(bundle);
        setContentView(R.layout.main);

        // Initialization logic for all the above components
    }

    // All kinds of helper methods for things like the initialization logic,
    // listeners, context and option menu's ...

    private void handleSomeClick() {
        // ...
    }

    private class FirstTabEditTextClickListener implements View.OnClickListener {
        public void onClick(View view) {
            // On click logic for the editText component
        }
    }

    // Some more listener inner classes ...
}

The “main.xml” layout file would look something like this:

<?xml version="1.0" encoding="utf-8"?>
<TabHost xmlns:android="http://schemas.android.com/apk/res/android"
         android:id="@android:id/tabhost"
         android:layout_width="fill_parent"
         android:layout_height="fill_parent">

    <LinearLayout android:orientation="vertical"
                  android:layout_width="fill_parent"
                  android:layout_height="fill_parent">

        <TabWidget android:id="@android:id/tabs"
                   android:layout_width="fill_parent"
                   android:layout_height="wrap_content"/>

        <FrameLayout android:id="@android:id/tabcontent"
                     android:layout_width="fill_parent"
                     android:layout_height="fill_parent">
            <LinearLayout android:id="@+id/firstTab"
                          android:layout_width="fill_parent"
                          android:layout_height="fill_parent">
                <!-- All view components of the first tab -->
            </LinearLayout>
            <RelativeLayout android:id="@+id/secondTab"
                          android:layout_width="fill_parent"
                          android:layout_height="fill_parent">
                <!-- All view components of the second tab -->
            </RelativeLayout>
            <TableLayout android:id="@+id/thirdTab"
                          android:layout_width="fill_parent"
                          android:layout_height="fill_parent">
                <!-- All view components of the third tab -->
            </TableLayout>
        </FrameLayout>
    </LinearLayout>
</TabHost>

Identify the components

The first thing to do is to identify the individual components you want to separate. In this case we can simply split this activity into three components, one for each tab. Of course, the Activity itself will still exist for obvious reasons (handling menu items, displaying dialogs, etc.). So in the end we’ll have a total of 4 classes.

Create new component classes

Second step is to create a new class for each component you want to create, which extends some layout class. In the case of this example those layout classes are RelativeLayout, LinearLayout and TableLayout (see above layout definition). Next, move all components contained in those layouts to the appropriate classes along with all related logic (listeners, etc.).

Example of such a component:

public class FirstTab extends LinearLayout {
    private ImageView imageView;
    private TextView textView;
    private TextView anotherTextView;

    public SecondTab(Context context, AttributeSet attributeSet) {
        super(context, attributeSet);

        LayoutInflater inflater = (LayoutInflater) context.getSystemService(Context.LAYOUT_INFLATER_SERVICE);
        inflater.inflate(R.layout.firstTab, this);
    }
}

Classes called SecondTab and ThirdTab can be implemented in a similar way. First thing to notice about the above implementation is the constructor. It should always have the following 2 arguments: Context and AttributeSet. Without such a constructor this component can’t be instantiated from XML. Another thing to notice is that a layout called “firstTab” is inflated on instantiation. All instantiated views in that layout are added as a child of FirstTab

Now, let’s try to create the “firstTab” layout that is being instantiated from the FirstTab component class:

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- All view components of the first tab -->
</LinearLayout>

There is a problem with this layout definition. If you think about it, you’ll notice what’s wrong with it. The problem is that when this layout is inflated, an instance of LinearLayout is created with all it’s defined child components attached. This is a problem because after the LinearLayout is instantiated, it is attached as a child component of the FirstTab, which itself already is a LinearLayout. So using this layout you will get a redundant LinearLayout in between the FirstTab and its child components.

The solution for this problem took me a while to figure out, but is actually quite simple. Instead of LinearLayout you should use the merge tag like this:

<merge xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- All view components of the first tab -->
</merge>

The merge tag makes sure that all its child views are attached to the merge tag’s parent instead. This is exactly what we want! Because now no new LinearLayout is instantiated and all child components are attached directly to the FirstTab.

To reference your new components from the original layout definition “main.xml”, you should use the fully qualified class name of the components. So this is how the layout could look like now:

<?xml version="1.0" encoding="utf-8"?>
<TabHost xmlns:android="http://schemas.android.com/apk/res/android"
         android:id="@android:id/tabhost"
         android:layout_width="fill_parent"
         android:layout_height="fill_parent">

    <LinearLayout android:orientation="vertical"
                  android:layout_width="fill_parent"
                  android:layout_height="fill_parent">

        <TabWidget android:id="@android:id/tabs"
                   android:layout_width="fill_parent"
                   android:layout_height="wrap_content"/>

        <FrameLayout android:id="@android:id/tabcontent"
                     android:layout_width="fill_parent"
                     android:layout_height="fill_parent">
            <com.example.android.FirstTab android:id="@+id/firstTab"
                          android:layout_width="fill_parent"
                          android:layout_height="fill_parent"/>
            <com.example.android.SecondTab android:id="@+id/secondTab"
                          android:layout_width="fill_parent"
                          android:layout_height="fill_parent"/>
            <com.example.android.ThirdTab android:id="@+id/thirdTab"
                          android:layout_width="fill_parent"
                          android:layout_height="fill_parent"/>
        </FrameLayout>
    </LinearLayout>
</TabHost>

This is it! Now you have divided your views over several components (classes).

Keep components loosely coupled

Now that you have all your view and behavior logic divided into multiple classes, you will probably run into some issues. Examples:

• FirstTab wants to refresh the SecondTab after a click on certain button
• Menu items are handled in MyActivity, but actually need to make changes to ThirdTab when selected

Listeners

The issue with the first example is, that FirstTab doesn’t have a reference to SecondTab to be able to refresh it. Under no circumstance should you give the FirstTab a direct reference to the SecondTab. This would result in very tight coupling between the components, which generally is not a good idea. Instead try to solve the issue using listeners. This is already a pattern implemented in a lot of places in the Android SDK itself, for example here: View#setOnClickListener(OnClickListener). So in the above example, you should create your own listener interface:

public interface SearchListener {
    void onSearch(SearchResult searchResult);
}

This could for example be a listener for when a search is performed in the FirstTab. The MyActivity class could register an anonymous implementation of this listener interface and call the SecondTab to refresh it.

firstTab.setSearchListener(new SearchListener() {
    public void onSearch(SearchResult searchResult) {
        secondTab.refresh(searchResult);
    }
});

A similar thing could be done when handling menu item clicks in the MyActivity, only this time listeners are not needed.

public boolean onMenuItemSelected(int featureId, MenuItem item) {
    switch (item.getItemId()) {
        case MENU_ADD_ENTRY:
            thirdTab.addEntry();
            break;
    }
}

So, create methods on your custom components if you need to control them from your Activity. Never expose any child components of your custom component to the Activity. The Activity should not have to know about them at all. Instead, create methods on your custom components that controls these child components like the above examples (refresh(…) and addEntry()).

I think with similar approaches, all issues can be solved when splitting your activity in multiple components. When you solve all issues you might have, you will have a cleanly separated Android application! This improves the overview of the application and makes it more maintainable.

Summary

I’ve shown you how to avoid making a mess of your application’s Activities by splitting clear chunks of functionality into custom components. Also, to avoid tight coupling between the custom components, I suggested to use Listeners.

If you have ever tried to deal with this before and have other suggestions to approach this, please leave a comment! Also, if you decided to try this structure in your application, let me know how that works out for you by leaving a comment!