Gridshore » design patterns

The power of immutability in a Rich Domain Model

Allard — Mon, 06 Apr 2009 19:00:00 +0000

As many other developers, I’ve been used to the fat service layer and the anemic domain model of the transaction script pattern. In that programming model, immutability is pretty much as rare as a Dodo. However, I have been investigating the rich domain model pattern lately (as you can read in my previous post) and more importantly, a good migration path for “transaction script” developers to get acquainted with the rich Domain Model, a design pattern that has been heavily underrated (and misunderstood) by many.

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 orderLines = new ArrayList();
    private final Customer customer;
    private Address shippingAddress;
    private Price totalAmount;

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

    public List 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.

Using the Memento pattern to solve thread safety issues

Ben — Sat, 27 Dec 2008 12:21:29 +0000

Introduction

Author’s note: this is an article that I co-authored
with a colleague, Robert van der Steen. It has also been
published in our company newsletter.

Many of the applications we write for our clients nowadays use the service paradigm: a dedicated and often reusable component within the application that is responsible for a particular task or process. Such components are often written and used in such a way that a component is instantiated once and reused often within the runtime of the application (such as a web service or a Spring managed bean).

Using components in this way is a very resource-friendly way of constructing an application; resource-intensive objects are created only once and reused instead of having to be recreated and reinitialized for each request. However, they do make it necessary to pay special attention to issues that arise in reuse and concurrent use — specifically state management. A common technique to avoid such state problems is to build stateless components.

Unfortunately, mistakes happen in software engineering. Sometimes team members introduce state to shared components without thinking about it. This article discusses using the Memento pattern as an easy way of transforming a stateful into a stateless service.

The problem

In order to illustrate the problem sketched above, let’s introduce an example. This example is an adaptation of a piece of code I stumbled upon in the codebase of a project:

                public class SpringManagedServiceClass {
                        private String oneField;
                        private String anotherField;

                        public boolean anOperation(final String input) {
                                oneField = someOperationOnInput(input);
                                anotherField = somethingElseInvolvingInput(input);
                                totalOperationSucceeded = operationOnTwoStrings(oneField, anotherField);
                                return totalOperationSucceeded;
                        }

                        public String getOneField() {
                                return oneField;
                        }

                        public String getAnotherField() {
                                return anotherField;
                        }
                }

The code above evolved from a class that was not managed by Spring and was instead instantiated each time the service was needed. In that form having state at the class level was no problem: each object was used once and then discarded. This meant it was also thread safe for a client of the service object to extract state using the getters. However, when moved over to Spring the class became a de facto singleton and therefore not thread safe. The person who converted the class to a Spring bean did not recognize this and so introduced a problem by allowing concurrent access to unguarded state.

A quick fix to this problem might be to move back from Spring to instantiation at use. Unfortunately, in this case the class had evolved to depend on a database connection managed by Spring, so moving away from Spring support would be a lot of work.

Introducing the Memento

The Memento pattern is a rather simple pattern that externalizes a classes (visible) state. The way it works is by following these steps:

Take a class C which has fields (i.e. objects with state).
Introduce a new class CMemento.
Move all the fields from C to CMemento. Make them private.
Introduce constructors, getters and setters into CMemento as needed.
In C, in your service methods, initialize a new instance of CMemento.
Refactor C to use the variables in CMemento instead of the variables C used to have itself.
Refactor the relevant methods of C to return a CMemento instead of their existing return types.
Refactor CMemento and C so that the previous return values of the methods of C are placed in the CMemento objects.
Finally, refactor the relevant methods of C again to place their previous return values in their CMemento objects before returning these objects.

The CMemento classes take over the state of the class C in this pattern. C can instantiate a single CMemento instance or as many instances of CMemento as it likes and so create a set of states for itself. Each of these CMemento instances can be the “current” state of any object of type C at any time, so instances of C can roll back to a previous state easily or even swap states.

The Memento pattern is actually not meant to address the problem discussed in this article; it is meant to enable rolling back to a previous state. Fortunately for us the idea can be reused easily to solve our problem as well. Instead of being swappable however, we will refactor our service object to create a Memento object (an object to hold the externally visible state). The public service method will then return this Memento object and the service class will “abandon” its “state” after that, making the service completely stateless.

The solution applied to the example

First, let’s introduce our Memento class:

                public class ServiceMemento {
                        private String oneField;
                        private String anotherField;
                        private boolean serviceResult;

                        public ServiceMemento(final String oneField, final String anotherField, final boolean serviceResult) {
                                 this.oneField = oneField;
                                 this.anotherField = anotherField;
                                 this.serviceResult = serviceResult;
                        }

                        public String getOneField() {
                                 return oneField;
                        }

                        public String getAnotherField() {
                                 return anotherField;
                        }

                        public boolean getServiceResult() {
                                 return serviceResult;
                        }
                 }

Now we can refactor our original service class and replace its state with a Memento object:

                public class SpringManagedServiceClass {
                        public ServiceMemento anOperation(final String input) {
                                String oneField = someOperationOnInput(input);
                                String anotherField = somethingElseInvolvingInput(input);
                                boolean totalOperationSucceeded = operationOnTwoStrings(oneField, anotherField);
                                ServiceMemento result = new ServiceMemento(oneField, anotherField, totalOperationSucceeded);
                                return result;
                        }
                }

After this refactoring all the client code will of course have to be refactored as well. However, all the state access has been replaced by getter calls to the new Memento object, so that refactoring is not very difficult.

The most important thing is that using the Memento has allowed us transform our service class into a thread safe, stateless service class rather easily. The price for this was introducing a new class. This is not as clean a solution as we would have had if the service class had been designed to be thread safe from the very start. But it is an easy fix to implement so it allows us to avoid a lot of (potentially difficult) rework. Also, this Memento class will do nothing but hold the result of the work done by the service class. So at least instantiating and having multiple instances of this class will not be as expensive as having to create multiple instances of the service class.

Summary

This article discussed using the Memento pattern as a quick fix for a thread safety problem in service classes. It covered the problem of accidentally introducing concurrent access problems in singleton classes by introducing state into those classes and then showed how that state can be externalized into a Memento class to make the service class stateless once more.

The Life Cycle Pattern

Ben — Sat, 09 Aug 2008 20:42:58 +0000

One of my current projects is responsible for delivering a library of functions that are used by several applications being built and maintained at our customer. One of those functions in particular is quite central to the operation of all the applications that use out library and is responsible for collecting, transforming and combining data from many different sources (essentially it is an orchestrating function). This function has a classical codebase, in the sense that the codebase started out being much smaller than it is now and with fewer tasks but has since grown. The library function is being developed continuously and will be expected to meet more and more requirements as more and more data must be collected and correlated. The problem, as you can imagine, is that the codebase is becoming unmanageable as more and more code goes into it. So we are faced with the question: how can we refactor the existing codebase to improve manageability?

As mentioned before the function in question is essentially an orchestrator, collecting data from several locations and combining these different data into one package. The collection of data is not random, however: some requests depend on the results of others, creating a natural partitioning of the function’s code into tasks with an internal ordering. Of course, this sounds like a classical orchestration setup and the first suggestion might be to use an orchestration tool like a BPEL engine. However, integrating a BPEL engine into the library seems like overkill given the current size and complexity of the function (and doesn’t fit well with the rest of the library). So instead my project is going to attempt an intermediate solution between the current pile-of-code architecture and a full orchestration tool: the Life Cycle Pattern.

The setup

Now, I have to admit to a little marketing here: there is (to the best of my knowledge) no official pattern called the “Life Cycle Pattern”. What I am talking about in fact is, in fact, a refactoring of our current pile-of-code collection of tasks (collecting data, transforming data, combining data and similar) into a collection of separate task objects, each of which is associated with one (or more) explicily identified steps within the overall library function.

Let me start from the other end to explain. I assume most people reading this article have at least heard of the maven build management tool. This tool (starting with version 2.0) divides the build process into a number of distinct steps or stages (clean, generate-sources, compile, test, package, deploy, etc.) which are together known as the build life cycle. A run of the maven executable runs through each of the stages in order. At each stage the executable delegates to zero or more modules (in the case of maven they’re called mojos) each of which attempts to carry out a task (in maven-speak, attempts to achieve a goal). Which module is associated with which stage is determined by configuration.

Patterns

From a design pattern point of view, the “life cycle pattern” is actually a combination of two patterns: the Mediator pattern and the Command pattern. The first of these is a pattern that deals with having a central controller that delegates to a number of objects (each with their own responsibilities within the system) and controls their execution order to create a process. The second is a pattern that deals with turning system tasks into objects. The pattern actually exists to turn tasks into first-class citizens of a system so that they can be manipulated (e.g. reversed, as in an “Undo” functionality). In our case however we just want to make tasks manageable to associate them with steps. The structure we are aiming for is the following:

In this design the LifeCycleManager is the class that is responsible for controlling the entire process with its different steps (in our case: the class that provides the library function). The operation that is called to kick of a process instance is referred to as the publicOperation() in the diagram above (in general this method will probably have one or more parameters). In the design above this method is the one that knows about the exact order in which the life cycle stages should be executed. As you can see, each stage is associated (in this design) with a list of Task objects. The publicOperation() method passes each of these lists to the executeStageTasks() method in the correct order. This method iterates over the Tasks in the list it is passed and calls executeTask() on each Task. The execution of this setup is illustrated in the following sequence diagram:

Code example

In the following section I will include a small code example of this “pattern”. The example is a Springified one, which means that the association of tasks to stages is done by dependency injection (in this case of the lists of Task objects into the LifeCycleManager). As illustrated in the design above, Task is just an interface that defines the Task hierarchy.

package nl.bentels.test; 

/**
 * This interface defines the Task type, the type of any task that can be
 * executed as part of a life cycle.
 *
 * @author ben.tels
 */
public interface Task
{
    /**
     * Method that executes a task.
     */
    void executeTask();
}

The LifeCycleManager is also unsurprising:

package nl.bentels.test;

import java.util.List;

/**
 * This class is responsible for managing and executing the life cycle of
 * whatever it is that the life cycle blongs to.
 *
 * @author ben.tels
 */
public class LifeCycleManager
{
        /** Preparation tasks for stage 0. */
        private List        preStage0;
        /** Tasks for stage 0. */
        private List        stage0;
        /** Postprocessing tasks for stage 0. */
        private List        postStage0;

        /**
         * The operation that can be invoked by an external entity.
         */
        public void publicOperation()
        {
                executeStageTasks(preStage0);
                executeStageTasks(stage0);
                executeStageTasks(postStage0);
        }

        /**
         * Iterate over the tasks for a life cycle stage and execute them.
         *
         * @param tasks The tasks.
         */
        void executeStageTasks(final List tasks)
        {
                for (Task task : tasks)
                {
                        task.executeTask();
                }
        }

        /**
         * @param preStage0 the preStage0 to set
         */
        public void setPreStage0(final List preStage0)
        {
                this.preStage0 = preStage0;
        }

        /**
         * @param stage0 the stage0 to set
         */
        public void setStage0(final List stage0)
        {
                this.stage0 = stage0;
        }

        /**
         * @param postStage0 the postStage0 to set
         */
        public void setPostStage0(final List postStage0)
        {
                this.postStage0 = postStage0;
        }
}

In order to make a full example, I’ll provide an example task implementation. This one does nothing but print a number:

/**
 *
 */
package nl.bentels.test;

/**
 * This class is an example task.
 *
 * @author ben.tels
 */
public class ExampleTask implements Task
{
        /** Number of the task. */
        private final int       taskNumber;

        /**
         * @param taskNumber
         */
        public ExampleTask(final int taskNumber)
        {
                this.taskNumber = taskNumber;
        }

        /**
         * {@inheritDoc}
         */
        @Override
        public void executeTask()
        {
                System.out.println(taskNumber);
        }

}

Finally, the Spring configuration:

< ?xml version="1.0" encoding="UTF-8"?>

Moving on….

Like I said, this mechanism is not in place yet; the project is only about to start working on it. This means that there are still considerations open, such as how to arrange communication (or state sharing) between the tasks of the process. Of course I will report on the outcome (once it is known) in a sequel to this article…..