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.

Of course dihydromonoxide and the many warnings against it are all based on a clever use of words. Seen in that light dihydromonoxide is a wonderful example of something I was taught by a professor of mine at university (and reminded of a couple of times today): Shakespeare may have prattled on about roses by any other name, but in reality notation is absolutely everything in our business.

Here’s (another) example of the importance of notation: derivation. Derivation as in calculus, which you were taught in highschool. I’m sure everybody remembers doing endless sums about calculating the derivative function f ‘(x) of a given function f(x), quickly followed by the second derivative f ”(x) and possibly even the third derivative f⁽³⁾(x) and fourth derivative f⁽⁴⁾(x). And I’ll bet most of you never even knew (or cared) about the fact that there are a number of different notations in use for a derivative. But there are; and of these, the three most well-known are the Newton notation (which indicated derivation against a function by placing one or more dots above the functor), the Lagrange notation (the notation with the primes used most often for first and second derivative) and the most commonly used of all, the Leibniz notation (which a number in parentheses, an analog to the power-of or exponent notation). Of these, the Leibniz notation is most often used in mathematics. And the reason is simple: once you get beyond second derivatives, the other notations get to be very cumbersome.

Notation is an important factor in our work as computing scientists and software engineers. It often makes the difference between making a piece of software easy to use or cumbersome and unusable. Sometimes it also makes the difference between making a problem easy to solve and difficult. Back in university, for instance, there were a number of courses where we derived solutions to problems from a formal specification. This process involved using predicate calculus, which is very powerful but often cumbersome. However, introducing a useful notation and proving some simple properties of this notation could often greatly reduce the burden of proof in these exercises.

Another example of notation making life easier is a pattern that I’ve employed quite often over the past few years when applying the strategy pattern: in order to select the correct strategy for a specific case, instead of using a gigantic pile of if-statements, I prefer to put instances of all my different strategies in a hashtable using a representative for each case (like a Class instance) as the key. The result looks a little like this:

private Map strategyMap = ...; // Instantiate this somehow 

public void applyStrategyToASpecificCase(final Object theCase)
{
     strategyMap.get(theCase.getClass()).applyTo(theCase);
} 

One of the reasons I like this, by the way, is that it also mixes well with dependency injection frameworks like Spring.

Like I already said, I was reminded by my professor’s wise lesson a number of times today, both in the positive and in the negative sense. One such reminder occurred when I was working on some UML diagrams using Enterprise Architect (which is a horror I hope you will all be spared). This series of diagrams includes a certain construct which occurs a large number of times in many different places. I quickly found myself wishing there was a simple way to create a shorthand notation for this construct. I was however pleasantly surprised to find that you can embed diagrams in other diagrams (both as embedded images and as symbolic links) and can drill down to them. This allows you to define subactivities for your activity diagrams, for instance. Now if only you could actually include the subactivity within the overall activity as an activity, rather than having to include an activity and put the diagram link next to that (but not connected to the diagram)….

A second example I ran into is related to the definition of a web service interface that is currently being defined. This interface must provide for the inclusion of one or more pieces of configuration data that are retrieved from other XML documents. A very generic solution was chosen by defining a repeatable element called Item, which contains an XMLElement element and a FieldValue element. This solution certainly works, but I think that names like ConfigurationItem, ConfigurationItemName and ConfigurationItemValue are a bit more expressive and therefore make it easier to understand how to use the service.

Notation is one of those subtle little things that I think are too easily overlooked in software engineering, especially given the huge role it can play in making or breaking your system. Notation means the difference between an easily usable API and an airline terminal (ask a travel agent about it, if you’ve never seen one used). It means the difference between self-documenting, maintainable code and unmaintainable code. It can mean the difference between an easily comprehensible and codable solution and a solution that hurts your head just to come up with. It can aid you in achieving separation of concerns (if only by ordering your thoughts). It can even be the key to better-performing code for some problems.

The importance of notation in API design is one of the reasons I am quite enamoured of the notion of a Fluent API, by the way. This interface style promises to make APIs a lot easier to use and a lot less error prone albeit at the cost of requiring more thought on the part of the development team. One of my current projects is experimenting with Fluent APIs right now; I’ll dedicate a future blog to the outcome.

Whether the fluent style will work out or not, I can confirm right now that a clear and expressive interface is always a good idea: two of the projects I am involved with are moving from very generic, “you can put any parameter and value you want in this key-value pair list”-style of interfaces to interfaces that are very explicit about what is needed, what is allowed and what the effect and outcome will be; both projects are reporting far less aggravation in the implementation of their new services than they had previously. Note that the type of data that can be passed through the interface has not changed; just the way the interface forces the client to present this data. Like my professor said, notation is everything.

By the way, in case you were worried: dihydromonoxide (or H₂O) is more commonly referred to as water….