Read on to find out more.

About the Axon Framework

Axon Framework helps build scalable, extensible and maintainable applications by supporting developers apply the Command Query Responsibility Segregation (CQRS) architectural pattern. It does so by providing implementations, sometimes complete, sometimes abstract, of the most important building blocks, such as aggregates, repositories and event the bus – the dispatching mechanism for events. Furthermore, Axon provides annotation support, which allows you to build aggregates and event listeners without tying your code to Axon specific logic. This allows you to focus on your business logic, instead of the plumbing, and helps you makes your code easier to test in isolation.

Features available in 0.4

We have made quite a few additions and changes since the 0.3 release. Unfortunately, this also means I had to make some minor API changes. There is now a bigger choice of abstract classes for most of the building blocks. This allows you to choose whether you want to use the logic provided by Axon, or prefer to develop more of your own. Whatever your wish is, there should be a class to help you on your way.

The biggest change since 0.3 is the addition of an Asynchronous Event Bus that supports transactional processing of events. Since it is asynchronous, it means that your command processing doesn’t have to wait for events to be processed. However, this Event Buss can also guarantee the order in which events are delivered to the event handlers. You can choose full concurrent processing (without any guarantees about ordering), full sequential processing (FiFo guarantee) or anything in between. You could, for example, guarantee the sequential processing of Events that come from the same aggregate.

The Event Bus also provides transaction support. That means you can tell the event bus to retry an event after a certain amount of time when processing fails, for example due to an error in the underlying mechanism, such as a database. For performance reasons, you can configure the event handler to process multiple events within a single transaction. Database updates are a lot faster if you process several events within a single transaction before committing it. Within your event handler, you can configure transactions.

Besides Domain Events, Axon now also allows you to explicitly define two other types of events: Application Events and System Events. Application Event can notify your event listeners that something interesting happened in your application. System Events are a special type of application events and can be used to indicate that a part of your application has changed state, for example when the database is no longer available. These System Events could provide interesting operational information about your application.

Another major change since 0.3 is the documentation. We have brought the documentation up to par with the code-base. All features are now extensively described in the reference guide. You can download the manual from the Axon Framework website: www.axonframework.org.

Last, but definitely not least, we have created a demo application that you can easily download and deploy to have a look at how you can use events to your advantage. This demo application is built using a Flex Client and an Axon-based server side component. The Flex Client registers itself as an event listener and will automatically process incoming events, at real time! That means that you can have 2 windows open, change something in one window, and see the change come in immediately on the other window, too. Check our Sample Installation page for more information.

What to expect in upcoming releases

The major components of the CQRS pattern are already available in the 0.4 release of Axon Framework. However, there is still a number of features we want to include in the 1.0 release. Although one of the advantages of CQRS is that it makes an application scalable and extensible, the 1.0 release of Axon Framework focuses on what happens inside a single JVM. Streaming events between JVM’s is not made impossible though, the Spring Integration connectors can be used to publish events to JMS, MQ, mail, HTTP and any other protocol supported by Spring Integration.

Some features to expect before the 1.0 release are rolling snapshots. When aggregates live for a long time, the number of events to read in each time the aggregate is loaded could easily run in the thousands. Reading in a thousand events takes a long time. Instead of reading in a thousand events, you can summarize all these events into a single snapshot event. Axon Framework will provide the plumbing necessary for you to build snapshot events.

Another feature that we’ll be spending some attention on is failure recovery. Unfortunately, applications sometimes behave unexpectedly and sometimes stop entirely. The reason of a crash won’t be the Axon Framework itself, of course. But since we have a reliable source of events in the events store, we can use this to recover from failure. Axon Framework will provide some building blocks that allow you to republish events to event handlers that did not get the chance to process them. This same mechanism will allow you to restore your application state from backups.

The last feature currently on the roadmap is JMX support. Since Axon Framework deals with the dispatching and invocation of event handlers, it has interesting information about an application’s performance and technical state. We are planning to expose this information using JMX MBeans.

If you have any other ideas, you can submit a feature request on www.axonframework.org/issues.

Getting started with Axon

If you’re eager to get started using Axon Framework for your own application, check out the Axon Framework website. There, you can download the binaries, sources documentation and a sample application. If you use Maven, the reference manual will explain how you can configure the dependencies on the Axon binaries.

If the information on the website is not enough to get you started, don’t hesitate to send me a message or post a comment at the bottom of this blog entry.

A special thanks to…

Before I wrap up, I would like to thank Jettro Coenradie for his help on the sample project and the reference documentation. I think the sample turned out into a pretty cool demo environment for some of the advantages that Axon can provide.

Also many thanks to JTeam for the time they allowed me to spend on the project. Without it, I am sure I couldn’t have delivered this release. Thanks!

A lot of activity in the DDD area, and a lot of discussions with colleagues and other interested people about DDD. The biggest question is of course WHY?. There is not a very simple answer to this question. Ok, maybe one: Why not?. But that is to easy and not very convincing. A lot of arguments against DDD are coming from people talking about implementation problems. This blog post is focussing on those people. Not that others should not read it, but I am writing this post with those people in my mind.

When we were explaining DDD to developers we often heard: Nothing different than what I am doing now, only other methods names. We than tried to convince them from a technical perspective only. Of course this is very hard. Especially because your trying to compare apples with pears. Design is not implementation. People having a hard time giving DDD a place are often not doing design at all. They call thinking about technical problems design. This not the same design as the third D in DDD.

So, as an implementer, what should you know about DDD. Well first thing you should learn is that you need a domain expert to talk to. The second thing you must learn is to create a ubiquitous language with the complete team. The third thing to learn is how to combine the knowledge from a domain expert and some technical requirements and describe this using the mentioned ubiquitous language.

Domain Driven Design is about helping you achieve this. DDD presents some basic principles that help you to create better applications. Applications that you can explain to all members of the team and to the domain expert using the ubiquitous language.

This post introduces some basic things that I picked up from the training by Eric Evans. I do want to stress that reading about DDD is not a replacement for the actual training. The training in itself is no replacement for doing actual projects using DDD.

I am already doing domain driven design

We are doing domain driven design for all our projects. Look this is our domain model for a project. Hmm, nice diagram. Well that is not completely what DDD is about. What does this diagram mean? Ahh, it is a graphical representation of the relationships between some of the most important entities and value objects of your model. But how did you get to this diagram? Did you talk to your domain expert? Does he understand it? Does it somehow reflect what he is thinking about when he is talking about his domain? Are all these terms known in the ubiquitous language? Are all project members talking about them in a consistent way?

DDD is not about creating a nice diagram. If diagrams help to understand the domain, it is wise to create them. Very often the creation of the diagram is helping to understand the domain. Usually developers and domain experts understand these kind of diagrams. But please do not call this diagram the model. The idea about DDD is to create a model using a ubiquitous language. To get better insights into the model, diagrams can surely help.

Of course I talk to the client

A very big part about DDD is talking to the domain expert. You must learn how to get information from a domain expert. Learn about the domain. When talking to people representing the client, make sure you are talking to a domain expert.

A few tips when interacting with the domain expert:

• When talking to the domain expert, make it a conversation. You should have mutual interest in having these talks.
• Share your own ideas around the model.
• Use multiple different ideas to get the discussion going.
• Bad ideas are good, they teach you a lot about what it is not.
• Use bad examples to see if you understand the domain expert and if he is still with you.
• Use scenarios to talk about the domain and the model. Also use realistic values, that way the domain expert knows better what you are talking about and you get a better feeling with your domain.
• Don’t think you need to talk to the domain expert once, make sure he is available to you the complete project.

Here is my Model

Central to domain driven design is the model. We all have an idea what a model is. To me the context for the model is very important. Do not make a model as realistic as possible. The model is a simplification of the domain. You leave out everything that is not needed for your specific need.

The model must be intuitive to users and simple to learn. In order to find the right model you should try to apply different scenarios to the model. If the domain expert does not understand the model, cannot talk about scenarios with respect to the model, the model is wrong. If the model is wrong, your code is wrong. If the code is wrong, I guess you understand what that means.

Context Map

I real eye opener to me during the training from Eric Evans was the context map. If you have read the book from eric, you can find it in his book. There is a small summary of the terms discussed online.

If your complete system becomes bigger and you need integrations with other systems, it is a very good time for a Context Map. The complete solution might exist from different contexts. Each context is created by different teams and often by different companies. With a context map, you plot these context and focus on their relationships. The type of relationship between two different contexts has it’s influence on the domain model.

An example:
A small company A uses a component from company B for plotting points of interest on a map. Now company A needs a feature to add extra characteristics to points of interest on the Map. Company B has no interest for these additional properties and do not change the model. This is a good example of a customer-supplier relationship. Does company A use the model of company B for it’s points of interest map? Or does company A create an adapter for all communication to company B and do data transformation. That way there is not dependency on the model of company B. Eric calls the first scenario a Conformist and the second an Anti corruption layer. The anti corruption layer is expensive at the start, but gives a lot of flexibility.

Eric discussed other relationships as well, things like: Shared Kernel, Separate ways, Open host and published language. These concepts are not new, but now they have a name. Plotting them on a context map and making them explicit in your ubiquitous language helps you when making choices in your model.

DDD is hard to implement

Depending on who you are talking to, implementing DDD has different challenges. One thing often mentioned is that the domain objects need to take care of their own persistence. All hard things to inject data access components into the domain object are considered by these people. I do not believe in that direction. I’ll take away transaction, security and persistence from the domain entities. The application services take care of the transaction boundaries and repository objects take care of the persistence. The post from Allard about the repository interface gives you an idea. More posts on this topic are coming.

A few things to think about while implementing

• Make sure the domain expert available to the team.
• Make sure the designers are writing the code as well.
• Let the model drive the code.
• Use the domain expert while coding. Spotting code duplication might be a misunderstanding in the model. Talk to the domain expert. This is also the case when you want to do a refactoring in the model.
• Create intention revealing interfaces and side effect free functions.
• Make the left side of statements read the same as the right side:
  Itinerary truncatedItinerary = itinerary.truncatedAt(routingPoint);
• Use Equals and HashCode methods as they were meant to be used.(see blog post Allard)
• Learn from other solutions, for instance infrastructure mechanisms for repositories.
• Do not try to copy domains. Most certainly they have been used in a different context. Of course you can learn from other models, use them for inspiration.

DDD is Domain Driven Design, it is not called DDI (Domain Driven Implementation). Do not come to me and tell me that it is impossible to implement DDD. If you are designing an application that cannot be implemented, that is a whole different problem.

Final remarks

• Do not design for technology, design for the domain.
• Use short feedback cycles with the domain expert, test first and verify solutions with the domain expert.
• Do not loose all technical perspective in design, but let the domain guide you in technical choices like: remoting, caching, transactions boundaries.
• The biggest impact in domain driven design is that your code can be understood by domain experts. That way problems in your code can be solved like in the domain. So you can actually copy the solution that the domain expert has been using for years into your design.
• The developer cannot make domain driven design a succes on his own. He needs the complete team.
• Make sure the design and implementation are tightly coupled.

That’s it. I hope I inspired some of you to have a better look at DDD. If you are living in the Netherlands you can attend a tech evening of JTeam, we will give an introduction into DDD. You can send an email to techmeeting@jteam.nl if you want to attend (3 september 2009, we start at 16:00). Another thing I would like to bring to the attention of the dutch readers is the DDDnl usergroup. We are planning our first session the 8th of september 2009. You can register yourself for the usergroup and for the session on the homepage of the usergroup. http://www.dddnl.org

In this article, I will elaborate on some common pitfalls you can encounter when implementing the equals method, as well as some sensible guidelines.

A lot of IDE’s nowadays allow you to generate technically perfect and compliant implementations of the equals method for any object. You simply choose a number of properties you wish to include in the comparison, indicate some of them as being non-null values and voila. Write a small unit test for the thing, commit the whole shebang and you’re done. Well, not quite. You’ve probably got an implementation even worse than the one provided by Object.

I’ve seen developers generate equals methods in mere seconds. Although managers tend to love this sort of “productivity”, as an architect doing code reviews, I measure productivity differently. I doubt if any developer can properly evaluate the functional value of such an implementation in just seconds.

First, we need to define what equals really means. To me, when to objects are equals, it means they are to such a degree identical to each other, that they can be replaced without side effects. In other words, if two objects are equal, it doesn’t matter which one you pick. In math, equality is very well defined. In software, it is a little harder to achieve that level of definitions. But that doesn’t mean we shouldn’t try.

As the title of this article suggests, I want to look at the equals method in the context of Domain Driven Design (DDD). In DDD, it’s all about making concepts explicit. In our case, it means answering the question: “What does it mean, for two [fill in the blank] to be equal?” Of course, there isn’t really a single generic answer for all objects. However, objects can be classified into a few major groups in DDD: Entities, Value Objects and (Domain)Services. The last of the three is not really of much interest in this context, so let’s focus on the other two.

Value objects

Value objects are immutable objects of which only the properties are of importance. They carry no concept of identity. A perfect example of a value object in daily life is money. Personally, I don’t care which 10 euro bill I carry, as long as it is a valid 10 euro’s. You can swap it with one owned by a friend and you won’t feel better or worse about it. The two bills are equal.

Because of the immutability in value objects, testing them for equality is rather easy. Generally, you can just generate an equals method using all of the (exposed) properties of the object. In our example, as long as the currency and the amount is the same, we don’t really care which instance of the bill we carry with us.

Therefore: the default choice for the equals method on value objects should be to include all (exposed) properties of that value object in the comparison.

Entities

En entity is “an object fundamentally defined not by its attributes, but by a thread of continuity and identity.” In daily life, having the same name as somebody else doesn’t make you the same. This form of mistaken identity can lead to huge problems in an application.

But back to our equals implementation. What does it mean for two entities to be equal? Well, it should mean that they can replace each other without side effects. If they can’t replace each other, they can’t really be equal. This means that, for to entities to be equal, at least their identity should be equal.

But entities have mutable state. To what degree do you want to use that state in the comparison? That really depends on the context of the comparison. If you want to know if the state has been modified between two copies of the instance, you will need an equals method that checks on all mutable properties as well as the identity. If you are only interested in knowing whether you are talking about an object representation of the actual same thing, identity comparison is the only thing you need.

If there is one thing an equals method cannot do, it is to look at the context and intentions of the caller. Since it extremely important to use “intention revealing interfaces”, an equals method on an entity is probably not the right way to go. In a discussion with Eric Evans, he explained that he prefers not to implement equals on entities at all, and instead provide other comparison methods, such as “hasSameIdentityAs”. This method clearly states what it means to be the same. Depending on the context and intention of your comparison, you call another method.

Let’s go back to the statement about equality: when two objects are equal, it means that you can replace one with the other without side effects.

Replacing one entity instance with another is dangerous in most circumstances. If they have the same identifier, they might have different state. The different instances are likely to be used by different threads with different intentions. When using persistence frameworks like JPA, your entity is likely to be attached to a persistence context, meaning that replacing them without side effect is out of the question.

This probably means that this statement is a little too rigid for entities. Mechanisms like the Set rely on the equals method to decide whether you are allowed to add an item or not.

Personally, I like to define two entities as equal when you are talking about the representation of the same actual thing. Hence, when the type and identity of the two are the same. This means my choice of equals method will only take the actual class and identity into consideration.

This gives us a nice problem when identity is provided by the persistence framework at the time an object is persisted. How do you measure equality when one or both instances do not (yet) have an identity? Although you cannot (or should not) try to predict the identity of those instances, there is one thing you can say about it. If two different instances have no identity, there is no way a persistence framework will assign them the same identity. This means that you can revert to the default implementation of equals in that case (practically doing a == comparison). The same goes for comparison of an entity with identity and one without: they will never, ever have the same identity in the future.

Conclusion

Before implementing the equals method, think clearly about the type of object that you are comparing. If it is an immutable value object, you should include all (exposed) properties of the value object. If it is an entity, be very cautious and first define what equality really means. Consider using methods with intention revealing interfaces, such as “hasSameIdentityAs” and “hasSameStateAs”.

Most of the applications I encounter in my work as Software Architect apply more or less the same layering. The well-known layers in an application are the web layer, application layer, persistence layer and domain layer. This layering provides some boundaries for different types of logic to keep an application maintainable in the long term. Typically, layers are placed in different modules (each with their own jar file) inside a project. However, for smaller projects it would suffice to just place each layer in its own package structure.

Almost all applications I encounter have implemented a layering as shown in the image on the left. The arrows show the direction of the dependency of each module on the others.

As you can see, the Application Layer has a dependency on the Persistence layer. The need for that dependency comes from the fact that the persistence layer contains the Repository. Both the interface (since it is good practice to develop against interfaces) and its implementation. With my recent study of the Domain Driven Design principles, I gained the insight that it doesn’t really make a lot of sense to put the interface next (or near) to its implementation.

But why would you even bother to create an interface for the Repository at all? Well, there are a few good reasons (and probably some bad ones too) to do so. One of them is that it allows easy mocking and stubbing for tests. Another is that it allows you to replace or modify the implementation without the risk of breaking interaction (as long as the interface is maintained).

However, replacing the persistence layer with another one isn’t as easy as it seems when it contains the interface. To be able to do so, you must copy the interface into the new persistence layer implementation. And as any good developers knows, when you’re copying stuff, take your hands off the keyboard, and think for a second. You’re probably doing something wrong.

Quite recently, I had a small discussion with someone who said: “How often do you expect to change the implementation of your persistence layer?”. I didn’t really have an answer back then, but right now I am spending time on exactly that in one of my projects. And you’ll have to trust me on this: correctly designing the interface is well worth the trouble. Even if you only have to change the persistence implementation once every 100 projects. Furthermore, another project I recently started actually requires the ability to “plug in” different implementations of the persistence layer (no, not at runtime, it doesn’t have to be OSGi, unfortunately).

Inspired by the DDD sample application, I decided to place the interface in the Domain Layer. By doing this, there was no longer a need to have a (compile time) dependency from the Application layer to the Persistence layer. On paper that looks a bit cleaner.  But we don’t design applications to look good on paper.

A good repository interface, as described by Martin Fowler and Eric Evans, gives it’s client the perception of an in-memory repository. In fact, it should hide any implementation choices you make about how and where data is really stored. And if you want to be able to replace persistence layers, that’s exactly what you need.

If you place the interface next to an implementation, you’re tempted to just use your IDE to extract an interface from your implementation. Chances are that your interface “leaks” information of your implementation choices. Instead, try to force yourself to design the interface first and develop an implementation that conforms to that interface later. This will help you achieve the “in-memory” perception.

A colleague of mine asked me why I chose to put the interface in the domain layer (see Separated Interface Pattern), and not the application layer, which is most likely to need the interface and call its implementation.I had three reasons.

First, the interface is described based on a small selection of domain entities. This gives the interface high coupling with these domain objects. High coupled classes are good candidates to share a package. In fact, you repository interface probably doesn’t require any import statements at all.

Secondly, it is probable that more than one service, perhaps located in different packages or modules, need to use the same repository. In that case, which package is most suitable to put the implementation in? Choosing even another package will result in lots of inter-package dependencies that aren’t really necessary. Unnecessary package dependencies decrease the ability to refactor your application .

And thirdly, the repositories provide access to your “aggregate roots”. If you have an aggregate root named, for example, “Order” and call your repository “OrderRepository”, your IDE will sort these classes in such a way, that you can easily find the most important entities in a blink of an eye.

Well, I hope this can help you in your projects as it could have helped me in the past. If you have any questions or concerns, don’t hesitate to leave a comment.

In this post, I will explain some of the advantages that immutable domain objects bring us, while showing that some of the seemingly problematic side effects aren’t really that problematic.

A practical example is often the easiest way to explain these kind of things. Since the banking world has received enough discredit in these times, I will use another example than the infamous “withdrawal” example. Instead, we will use the almost-as-infamous product and order example.

Imagine an application where you can browse trough products and place an order for one or more of those products. Our simple domain will contain three entities: product, order and order line. A UML class diagram for this domain is shown below.

The anemic approach

A commonly seen approach to implement this domain model is the following. The Order is implemented containing some delivery details and a list of order lines. The Order exposes getters and setters to modify each of those properties, including a getter that provides access to the list of order lines. The implementation of the OrderLine class is similar; it might contain a reference to a Product instance as well as a property to indicate the quantity ordered, resulting in the following code:

public class OrderLine {
    private Product product;
    private int quantity; 

    public Product getProduct() {
        return product;
    } 

    public void setProduct(final Product product) {
        this.product = product;
    } 

    public int getQuantity() {
        return quantity;
    } 

    public void setQuantity(final int quantity) {
        this.quantity = quantity;
    }
}

This code has a few problems, some functional and some technical

• What happens if the price of the product changes? Invoices will probably show the new price (which is always higher, for some reason).
• It’s no longer possible to delete a product, since you won’t be able to see what somebody ordered
• You allow every other class in your application to modify the OrderLine at will. What if you have a discount for customers that order for a certain amount? Each time an order line was modified, your code would have to call a calculateDiscount in your order
• If you want to calculate the total price of an order, you would have to iterate through all OrderLine and Product instances.

Of course, each of those problems can be solved some way or another, but whatever you do to solve them, it only adds to the complexity already there.

The immutable approach

Making the OrderLine immutable will solve some of the problems outlined above. The state of immutable objects is exclusively set in the constructor, meaning that both the Product and quantity will have to be passed as constructor parameters.

To solve the problem of the Product changing state, we can copy some of the important fields into the OrderLine. Good candidates for copying are the product identifier, the product name and its price. In fact, we don’t need any reference to the original Product instance at all after the OrderLine has been constructed.

The implementation of the immutable OrderLine is then changed into the following:

public class OrderLine {

    private final String productIndentifier;
    private final String productName;
    private final Price itemPrice;
    private final Price totalPrice;
    private final int amount;

    public OrderLine(Product product, int amount) {
        this.productIndentifier = product.getIdentifier();
        this.productName = product.getName();
        this.itemPrice = product.getPrice();
        this.totalPrice = itemPrice.multiply(amount);
        this.amount = amount;
    }

    /* getters not shown for brevity */
}

All problems solved? Well, no, not really. For starters, the last two problems enumerated above are still not solved. And then there is persistence. I use hibernate for nearly every project that requires persistence. Hibernate and immutable objects are not the best friends possible. Hibernate requires a non-private default constructor. Doesn’t seem like a problem, just add a no-argument constructor to you class. But then the final keyword ruins the game. You’ve got no other choice than to remove it. This removed the guaranteed visibility when your class is accessed by different threads at the same time. Solving that is a totally different ballgame and would carry me way off topic.

Using an aggregate root

We still have the problem that our discount is not updated when OrderLine instances are added or removed from an order. Making an order immutable in the same fashion would solve the problems. But let’s assume that a user is allowed to update and modify his orders as long they haven’t been processed by the system.

Exposing the list of OrderLine entries inside an order is not a good way to go, since your order is not in charge of its own lifecycle. If you take a close look at the UML diagram above, you will notice there is a composite relationship between the Order and OrderLine classes. This means that the Order class is responsible for the lifecycle of the OrderLine items that belong to it. In Domain Model terms, this means that Order is the Aggregate Root of these components.

The order would then be implemented as follows:

public class Order {

    private final List<orderline> orderLines = new ArrayList<orderline>();
    private final Customer customer;
    private Address shippingAddress;
    private Price totalAmount;

    public Order(Customer customer) {
        this.customer = customer;
    }

    public List<orderline> getOrderLines() {
        return Collections.unmodifiableList(orderLines);
    }

    public void addToOrder(Product product, int amount) {
        removeFromOrder(product);
        final OrderLine orderLine = new OrderLine(product, amount);
        orderLines.add(orderLine);
        totalAmount = totalAmount.add(orderLine.getTotalPrice());
        calculateDiscount();
    }

    public void removeFromOrder(Product product) {
        // implementation left to your imagination
    }

    /* rest of implementation left out for brevity */
}

As you can see, a high level of encapsulation has been applied. It is now impossible to change any state of the Order or OrderLine without the Order knowing it. The list of OrderLine items that the Order exposes is made immutable using the utility method in the Collections class.

With this implementation, it the latter two of the problems enumerated above have been solved. Since the order is in charge of making the changes to its own state, it is rather easy to discover state changes that might impact applicable discounts or change the total amount of the order. Now, getting access to the amount of the order is as easy as returning the totalAmount property from the Order.

Conclusion

In this post, I’ve introduced a very powerful concept to manage the state of complex domain models: immutability. By preventing the application to change state directly, you gain more control over the the actions that need to be taken when the state changes. Especially in aggregates, immutability reduces the complexity of state management.

However, when using Hibernate, it is impossible to make an entity completely immutable using the final keywords. In that case it is sufficient to create a default constructor with package visibility and removing the final keywords.