Rob Conery hits the nail right on the head in his post on Reporting in NoSQL.

Put as gently as I can – relational systems are an answer to a problem that we faced 30 years ago. What you’re doing now is nothing other than compensating for a lack of imagination from the platform developers. Think about it – we code using Object Oriented approaches, we store those objects in a relational system.

What we should all learn in this industry is to stop assuming that a relational database is the default option for storing the data of every solution we build. This is what we have been doing for a long time and its pure madness, plain and simple.

RDBMS don’t fit for holding your application’s data, and they don’t fit for reporting. They’re a solution for a problem that doesn’t exist anymore. Time to kick them to the curb.

The most typical setup you see is a single relational database that is used for both storing the data of an application as well as reporting from this data. The relational schema usually sits between normalized and denormalized tables, which means having a compromise for both needs. You can get away with this for small to medium-sized applications, but when you start working on mission-critical solutions with higher volumes, this compromise isn’t going to cut it anymore. This is why Greg Young, Udi Dahan and Mark Nijhof amongst others are advocating command query separation. For these kind of solutions, you want to have the best option for handling commands, which could be an OO database or a document/key-value store (with or without event-sourcing) and for reporting you’d want the best option available as well like an OLAP system. What I’m describing here is just the elevator pitch, so if you want to learn more about this then do checkout the resources that these gentlemen mentioned above have already put on their blogs.

I hope that one day we realize that a relational database was just a means for optimizing file storage, which is hardly a need anymore these days. We shouldn’t be struggling with how to solve the impedance mismatch between relational databases and OO programming in any kind of application. The one thing we should care about is how to provide solid and clean solutions to our businesses without having to worry about tables and those zealots with their holy database schemas. Just store the objects you want and worry about other things like the so-called ‘ilities’ and being able to respond to business needs in a timely manner. 

So you make a new version of the original event, this new version carries more or less information then the original one. Lets take a look at a very simple example:

    1 namespace Fohjin.DDD.Events.Account

    2 {

    3     [Serializable]

    4     public class CashWithdrawnEvent : DomainEvent

    5     {

    6         public decimal Balance { get; private set; }

    7         public decimal Amount { get; private set; }

    8 

    9         public CashWithdrawnEvent(decimal balance, decimal amount)

   10         {

   11             Balance = balance;

   12             Amount = amount;

   13         }

   14     }

   15 

   16     [Serializable]

   17     public class CashWithdrawnEvent_v2 : DomainEvent

   18     {

   19         public decimal Balance { get; private set; }

   20         public decimal Amount { get; private set; }

   21         public Guid AtmId { get; private set; }

   22 

   23         public CashWithdrawnEvent_v2(decimal balance, decimal amount, Guid atmId)

   24         {

   25             Balance = balance;

   26             Amount = amount;

   27             AtmId = atmId;

   28         }

   29     }

   30 }

This to me looks like a natural evolution for this type of event, so how do you deal with this. Because after having used the system, before adding this extension there have been many cash withdrawals. So all these events are in the Event Store, they cannot be altered, and when you retrieve an Aggregate Root from the Event Store all these historical events need to be processed in order to restore the internal state.

Now what you don’t want is to maintain code in the Aggregate Root that knows how to handle these old event versions, sure one version is ok, but what about one hundred different versions? Also we are not just talking about just in the Aggregate Root, also the different event handlers need to be kept and maintained.

The better approach is to have a mechanism that you can hook-up with different event convertors. Then when an event is retrieved from the Event Store it first goes through this pipeline of convertors to be converted to the latest event version.

Now I wanted to do this properly and write some actual code for this, and then blog about it, but someone kept nagging me about it, so here is a very rough spike instead, first some tests:

    1 namespace Test.Fohjin.DDD.Spike

    2 {

    3     public class Spike_test_1 : BaseTestFixture

    4     {

    5         private object ConvertedEvent;

    6 

    7         protected override void When()

    8         {

    9             ConvertedEvent = new EventConvertor().Convert(new CashWithdrawnEvent(10.0M, 20.0M));

   10         }

   11 

   12         [Then]

   13         public void The_converted_event_is_the_latest_version()

   14         {

   15             ConvertedEvent.WillBeOfType<CashWithdrawnEvent_v4>();

   16         }

   17 

   18         [Then]

   19         public void The_converted_event_wil_contain_the_correct_data()

   20         {

   21             ConvertedEvent.As<CashWithdrawnEvent_v4>().Balance.WillBe(10.0M);

   22             ConvertedEvent.As<CashWithdrawnEvent_v4>().Amount.WillBe(20.0M);

   23             ConvertedEvent.As<CashWithdrawnEvent_v4>().AtmId.WillBe(string.Empty);

   24         }

   25     }

   26 

   27     public class Spike_test_2 : BaseTestFixture

   28     {

   29         private object ConvertedEvent;

   30 

   31         protected override void When()

   32         {

   33             ConvertedEvent = new EventConvertor().Convert(new CashWithdrawnEvent_v2(10.0M, 20.0M, "12345"));

   34         }

   35 

   36         [Then]

   37         public void The_converted_event_is_the_latest_version()

   38         {

   39             ConvertedEvent.WillBeOfType<CashWithdrawnEvent_v4>();

   40         }

   41 

   42         [Then]

   43         public void The_converted_event_wil_contain_the_correct_data()

   44         {

   45             ConvertedEvent.As<CashWithdrawnEvent_v4>().Balance.WillBe(10.0M);

   46             ConvertedEvent.As<CashWithdrawnEvent_v4>().Amount.WillBe(20.0M);

   47             ConvertedEvent.As<CashWithdrawnEvent_v4>().AtmId.WillBe("12345");

   48         }

   49     }

   50 

   51     public class Spike_test_3 : BaseTestFixture

   52     {

   53         private object ConvertedEvent;

   54 

   55         protected override void When()

   56         {

   57             ConvertedEvent = new EventConvertor().Convert(new CashWithdrawnEvent_v3(10.0M, 20.0M, "12345"));

   58         }

   59 

   60         [Then]

   61         public void The_converted_event_is_the_latest_version()

   62         {

   63             ConvertedEvent.WillBeOfType<CashWithdrawnEvent_v4>();

   64         }

   65 

   66         [Then]

   67         public void The_converted_event_wil_contain_the_correct_data()

   68         {

   69             ConvertedEvent.As<CashWithdrawnEvent_v4>().Balance.WillBe(10.0M);

   70             ConvertedEvent.As<CashWithdrawnEvent_v4>().Amount.WillBe(20.0M);

   71             ConvertedEvent.As<CashWithdrawnEvent_v4>().AtmId.WillBe("12345");

   72         }

   73     }

   74 

   75     public class Spike_test_4 : BaseTestFixture

   76     {

   77         private object ConvertedEvent;

   78 

   79         protected override void When()

   80         {

   81             ConvertedEvent = new EventConvertor().Convert(new CashWithdrawnEvent_v4(10.0M, 20.0M, "12345"));

   82         }

   83 

   84         [Then]

   85         public void The_converted_event_is_the_latest_version()

   86         {

   87             ConvertedEvent.WillBeOfType<CashWithdrawnEvent_v4>();

   88         }

   89 

   90         [Then]

   91         public void The_converted_event_wil_contain_the_correct_data()

   92         {

   93             ConvertedEvent.As<CashWithdrawnEvent_v4>().Balance.WillBe(10.0M);

   94             ConvertedEvent.As<CashWithdrawnEvent_v4>().Amount.WillBe(20.0M);

   95             ConvertedEvent.As<CashWithdrawnEvent_v4>().AtmId.WillBe("12345");

   96         }

   97     }

   98 }

So basically some tests to confirm the correct conversion from one event to another event, now below here is the full implementation:

    1 namespace Test.Fohjin.DDD.Spike

    2 {

    3     public class EventConvertor

    4     {

    5         private readonly Dictionary<Type, Func<object, object>> _convertors;

    6 

    7         public EventConvertor()

    8         {

    9             _convertors = new Dictionary<Type, Func<object, object>>();

   10             RegisterEventConvertors();

   11         }

   12 

   13         private void RegisterEventConvertors()

   14         {

   15             _convertors.Add(typeof(CashWithdrawnEvent), x => new CashWithdrawnEventConvertor().Convert((CashWithdrawnEvent)x));

   16             _convertors.Add(typeof(CashWithdrawnEvent_v2), x => new CashWithdrawnEvent_v2Convertor().Convert((CashWithdrawnEvent_v2)x));

   17             _convertors.Add(typeof(CashWithdrawnEvent_v3), x => new CashWithdrawnEvent_v3Convertor().Convert((CashWithdrawnEvent_v3)x));

   18         }

   19 

   20         public object Convert(object soureEvent)

   21         {

   22             Func<object, object> convertor;

   23             return _convertors.TryGetValue(soureEvent.GetType(), out convertor) 

   24                 ? Convert(convertor(soureEvent)) 

   25                 : soureEvent;

   26         }

   27     }

   28 

   29     public interface IEventConvertor<TSourceEvent, TTargetEvent>

   30         where TSourceEvent : IDomainEvent

   31         where TTargetEvent : IDomainEvent

   32     {

   33         TTargetEvent Convert(TSourceEvent sourceEvent);

   34     }

   35 

   36     public class CashWithdrawnEventConvertor : IEventConvertor<CashWithdrawnEvent, CashWithdrawnEvent_v4>

   37     {

   38         public CashWithdrawnEvent_v4 Convert(CashWithdrawnEvent sourceEvent)

   39         {

   40             var theEvent = new CashWithdrawnEvent_v4(sourceEvent.Balance, sourceEvent.Amount, string.Empty)

   41             {

   42                 AggregateId = sourceEvent.AggregateId

   43             };

   44             (theEvent as IDomainEvent).Version = (sourceEvent as IDomainEvent).Version;

   45             return theEvent;

   46         }

   47     }

   48 

   49     public class CashWithdrawnEvent_v2Convertor : IEventConvertor<CashWithdrawnEvent_v2, CashWithdrawnEvent_v3>

   50     {

   51         public CashWithdrawnEvent_v3 Convert(CashWithdrawnEvent_v2 sourceEvent)

   52         {

   53             var theEvent = new CashWithdrawnEvent_v3(sourceEvent.Balance, sourceEvent.Amount, sourceEvent.AtmId)

   54             {

   55                 AggregateId = sourceEvent.AggregateId

   56             };

   57             (theEvent as IDomainEvent).Version = (sourceEvent as IDomainEvent).Version;

   58             return theEvent;

   59         }

   60     }

   61 

   62     public class CashWithdrawnEvent_v3Convertor : IEventConvertor<CashWithdrawnEvent_v3, CashWithdrawnEvent_v4>

   63     {

   64         public CashWithdrawnEvent_v4 Convert(CashWithdrawnEvent_v3 sourceEvent)

   65         {

   66             var theEvent = new CashWithdrawnEvent_v4(sourceEvent.Balance, sourceEvent.Amount, sourceEvent.AtmId)

   67             {

   68                 AggregateId = sourceEvent.AggregateId

   69             };

   70             (theEvent as IDomainEvent).Version = (sourceEvent as IDomainEvent).Version;

   71             return theEvent;

   72         }

   73     }

   74 }

This implementation is definitely not very elegant (so it doesn’t really belong on this blog) but hey it does show you how a possible solution would work. When building this yourself you might want to use conventions to auto register the convertors and chain them together during configuration so there is no need for the recursive functionality.

Also look at the jump from version 1 to version 4, this is an optimization to speed up the conversion. You would do this after a few versions, not for each version.

I’ll be adding a proper solution to the example in the near future, something that you would just plug the convertors in and the system would figure out how to handle them itself.

One of the first obvious ways to increase the performance of your system is to split the Command from the Query side by using a service bus or just a simple queue. So instead of one machine being responsible for both responsibilities you now have 2 machines.

Then you also get the ability to measure more precisely what the actual bottleneck is, normally your application queries for data many times more then that it is executing behavior. And there are already many well known approaches for scaling your reporting database so that is not what I would like to talk about, but I guess it is clear that this side can now be scaled-out individually from the command side.

Now the command side; because even if this is used many times less then the query side, the actual behavior may take much more time and or processing power.

There are two natural ways of splitting up the domain, the first one is by Aggregate Root type, so you can choose to place a single (or multiple) Aggregate Root type on a different server. The second way is by splitting-up a single Aggregate Root type by the Identity each individual instance has. Think of for example about splitting them up depending on the last number of the Id, even versus un-even.

So who decides? The decision needs to be made by the process that accepts the commands and passes them on to the command handlers, these command handlers can then be running on different machines and each machine may even have it’s own Event Store.

This is a very flexible way of splitting-up your system into different components, and because of the Event Driven Architecture basically build-into this approach you will be able to trigger other behavior on different Aggregate Roots without added trouble.

My new blog is at at http://cre8ivethought.com/blog/index come and follow me there.

-Mark Nijhof

So after reading this blog post by Rob Conery about Reporting In NoSQL where he explains very well what the problem is when using a RDBMS for persisting the state of your domain, or really anything that is written with Object Orientation in mind.

His solution to the problem is to use a object database or a document database for persisting the state of your object structure. And I do agree that this is a valuable approach to solve the problem.

But I would like to talk about a different approach, which is called Event Sourcing; a pattern thought of by Martin Fowler that, “Captures all changes to an application state as a sequence of events.”

Hey that is interesting, so instead of trying to store the object tree in a whole, we just store all the individual state changes that the object tree encapsulates; meaning all the state changes that have happened during the complete lifetime of the object tree. These state changes are being represented in the form of events. And such an event is nothing more then a Plain Old CLR Object, so not an actual .Net event.

And the objects are also re-constructed from the same events by applying all the state changes that they represent, and thus coming back to the previous state in the identical way that it came there originally.

Now the interesting part with respect to persistence is that these events are being serialized using a technique you like (Binary, JSon or custom) and this serialized event (object) is persisted in an event store, and this event store will threat all serialized events equally.

This event store can be based on an object database, document database, file system or even a RDBMS, you basically need to have one collection that describes all the different objects that the event store has persisted this includes the Id and the Version. Then another collection will contain all the serialized events for each different object and they should be retrievable by the object Id ordered by their Version. So to simplify this, in a RDBMS this would mean 2 tables, in total.

So there is no impendence mismatch between the domain (object structure) and the persistence layer anymore. Which would mean that it is should pass Rob’s criteria’s as well.

But hey it doesn’t stop there, you get a real audit log for free a well. And you have the ability to replay all the events to abstract new information about certain state changes. For example a web store is in business for 6 months and now they would like to know when and where an item is being removed from the shopping cart. With an event store you will have this information from the start of the system, and you didn’t have to think about it straight from the start.

And this also enables an easier swift to an Event Driven Architecture as well, because you can start publishing the events outside of the domain and have different behavior or processes react on them.

In my example I use a combination of CQRS and Event Sourcing and this makes a very powerful solution. I would recommend that when you are when applying CQRS you would do that in combination with Event Sourcing to get a very flexible system without much more complexity then just applying CQRS.

My new blog is at at http://cre8ivethought.com/blog/index come and follow me there.

-Mark Nijhof

My wife wants to start a web store selling all kinds of children products like clothing, toys and perhaps some small furniture. So there is a need for an internet store where she can list these products and try to sell them.

I guess the normal procedure would be to try and find a service/product that enables her to do just that, but she married the wrong guy for that, at least until I have to declare defeat.

Anyway I thought that combining my wife’s needs and my own would be an ideal solution, again at least for me, we’ll see what she thinks about it after a while. So what are my needs?

Update: Ok to be more fair, I am using my wife’s ambition to open a web store to create a project for myself. It might be so that we will be using it for her store, but there is a very high likelihood that we will be renting an existing service instead. Even if it was just to not have it get between our marriage but as I said I will build it as if it will be used by her.

FubuMVC – v.Reboot

As some of you (or most I actually don’t know my target audience good enough to make these statements) may already know Jeremy Miller has been putting a lot (read amazing amount) of work into FubuMVC replacing/rewriting parts of the original FubuMVC code base that Chad Myers initiated from lessons learned. I encourage you to read this first and second post about this reboot from Jeremy to learn more about it.

But all this does mean that I have to dig deep into the FubuMVC code again and see what has changed and how it now works, sure most of the basic principles are still true, but especially on the configuration side many things have changed. Also the behavior chain as the controller is now an option that I am looking forward to be using. And hopefully I’ll be able to add my own pet peeve; behavior chains for partials even further separating responsibilities.

DDD using CQRS and Event Sourcing

And I want to incorporate CQRS using Event Sourcing into this as well, but not just that I’ll be using this to drive the development of my PI solution for this approach. You may read some initial thoughts about that here. Nothing beats developing something then driven by actual usage. I am also thinking about incorporating Udi Dahan’s thoughts into this by not making my aggregate roots into huge tree structures, but by keeping it as flat as possible.

Sharing by blogging and OSS

I am building this for myself, for my wife really, anyway those are the specifications what I’ll be fulfilling (and yes I am going to try to make this as real as I can). Perhaps it is also time for me to start trying MSpec, but on the other hand I really like to try out Cucumber using Duke4Nuke and TeamCity. It would be great if I could get a public build server for this (CodeBetter?).

Anyway I want to make this completely in the open by providing all the source code via my GitHub account and also blog about the whole process. These posts would be covering everything, so from project setup with FubuMVC till some specifications and all the things that go into the creation of my PI CQRS solution (to early to call it a framework yet).

Now together with writing my book and many other things you should not expect a high speed project where this is build in no-time. So patience is a good thing here.

So?

Well I would like your feedback about this, what do you think about this approach? Also I would need a name for the project, both for the web store and for the PI CQRS solution. I hope you can help me with that, as I am very bad with names (we are currently looking into children names again and my wife will testify that I am indeed very bad at this).

My new blog is at at http://cre8ivethought.com/blog/index come and follow me there.

-Mark Nijhof

I received a couple questions about the Specification Framework that I use in the CQRS example and thought lets talk about that for a bit. The first thing that should be underlined is that this is _not_ a framework, they are a few classes and extension methods that rely on NUnit for the actual assertions and and Moq for mocking of the dependencies. I got the initial bits from Greg Young at his DDD course which I extended a little bit for my specific needs.

I have the following base test fixture classes:

• BaseTestFixture
• BaseTestFixture<TSubjectUnderTest>
• AggregateRootTestFixture<TAggregateRoot>
• CommandTestFixture<TCommand, TCommandHandler, TAggregateRoot>
• EventTestFixture<TEvent, TEventHandler>
• PresenterTestFixture<TPresenter>

These different classes are all very specific towards a specific need, which is a direct opposite from what a framework usually provides.

Black box

I try my best to make my tests treat the subject under test (SUT) as a black box, meaning that in my tests I don’t directly interact with the actual class that I am testing. Instead I want to trigger the behavior by executing behavior that lies further outside. The behavior that triggers the behavior on the SUT may be an actual implementation, or it could be a fake.

The same applies to the result of the behavior that gets tested, instead of verifying some state in the SUT I want to verify what happens outside of the SUT. So what matters is that I test the behavior not the state of the subject under test.

I also try to get further away from the SUT then its immediate usage. Doing so makes the tests less brittle for change. This in itself is not always an easy task, but I recommend you try it anyway.

The BaseTestFixture

This is the simplest test fixture class that I have and I use this for and I actually don’t use this anywhere in the example code, but it serves a really good basic overview of the semantics that are shared among the other test fixture classes.

    1 namespace Test.Fohjin.DDD

    2 {

    3     [Specification]

    4     public abstract class BaseTestFixture

    5     {

    6         protected Exception CaughtException;

    7         protected virtual void Given() { }

    8         protected abstract void When();

    9         protected virtual void Finally() { }

   10 

   11         [Given]

   12         public void Setup()

   13         {

   14             CaughtException = new ThereWasNoExceptionButOneWasExpectedException();            

   15             Given();

   16 

   17             try

   18             {

   19                 When();

   20             }

   21             catch (Exception exception)

   22             {

   23                 CaughtException = exception;

   24             }

   25             finally

   26             {

   27                 Finally();

   28             }

   29         }

   30     }

   31 

   32     public class GivenAttribute : SetUpAttribute { }

   33 

   34     public class ThenAttribute : TestAttribute { }

   35 

   36     public class SpecificationAttribute : TestFixtureAttribute { }

   37 }

It is following the Given When Then (GWT) approach, and as you can see it is really simple. Also note that I introduced some other named attributes by simply inheriting from the default NUnit attributes, this was purely done to stay with the GWT approach.

Below here is an incredible KISS example of how you would use this BaseTestFixture, which I believe doesn’t need further explanation. (I know I am misusing the term KISS here, but I thought if was fitting anyway).

    1 namespace Test.Fohjin.DDD

    2 {

    3     public class Very_adding_a_number_to_the_subject_under_test : BaseTestFixture

    4     {

    5         private int SubjectUnderTest;

    6 

    7         protected override void Given()

    8         {

    9             SubjectUnderTest = 2;

   10         }

   11 

   12         protected override void When()

   13         {

   14             SubjectUnderTest += 2;

   15         }

   16 

   17         [Then]

   18         public void Then_the_new_value_of_the_subject_under_test_will_be_4()

   19         {

   20             SubjectUnderTest.WillBe(4);

   21         }

   22     }

   23 }

The BaseTestFixture<TSubjectUnderTest>

Now we are getting into a more interesting case because now my subject under test is actually provided by the generic parameter of the base test fixture class. And to be honest this class is only used with 12 specifications out of the 122 specification classes. This is mostly because it is still a very generic solution, but again a nice way to ease into it.

    1 namespace Test.Fohjin.DDD

    2 {

    3     [Specification]

    4     public abstract class BaseTestFixture<TSubjectUnderTest>

    5     {

    6         private Dictionary<Type, object> mocks;

    7 

    8         protected Dictionary<Type, object> DoNotMock;

    9         protected TSubjectUnderTest SubjectUnderTest;

   10         protected Exception CaughtException;

   11         protected virtual void SetupDependencies() { }

   12         protected virtual void Given() { }

   13         protected abstract void When();

   14         protected virtual void Finally() { }

   15 

   16         [Given]

   17         public void Setup()

   18         {

   19             mocks = new Dictionary<Type, object>();

   20             DoNotMock = new Dictionary<Type, object>();

   21             CaughtException = new ThereWasNoExceptionButOneWasExpectedException();

   22 

   23             BuildMocks();

   24             SetupDependencies();

   25             SubjectUnderTest = BuildSubjectUnderTest();

   26 

   27             Given();

   28 

   29             try

   30             {

   31                 When();

   32             }

   33             catch (Exception exception)

   34             {

   35                 CaughtException = exception;

   36             }

   37             finally

   38             {

   39                 Finally();

   40             }

   41         }

   42 

   43         public Mock<TType> OnDependency<TType>() where TType : class

   44         {

   45             return (Mock<TType>)mocks[typeof(TType)];

   46         }

   47 

   48         private TSubjectUnderTest BuildSubjectUnderTest()

   49         {

   50             var constructorInfo = typeof(TSubjectUnderTest).GetConstructors().First();

   51 

   52             var parameters = new List<object>();

   53             foreach (var mock in mocks)

   54             {

   55                 object theObject;

   56                 if (!DoNotMock.TryGetValue(mock.Key, out theObject))

   57                     theObject = ((Mock) mock.Value).Object;

   58 

   59                 parameters.Add(theObject);

   60             }

   61 

   62             return (TSubjectUnderTest)constructorInfo.Invoke(parameters.ToArray());

   63         }

   64 

   65         private void BuildMocks()

   66         {

   67             var constructorInfo = typeof(TSubjectUnderTest).GetConstructors().First();

   68 

   69             foreach (var parameter in constructorInfo.GetParameters())

   70             {

   71                 mocks.Add(parameter.ParameterType, CreateMock(parameter.ParameterType));

   72             }

   73         }

   74 

   75         private static object CreateMock(Type type)

   76         {

   77             var constructorInfo = typeof(Mock<>).MakeGenericType(type).GetConstructors().First();

   78             return constructorInfo.Invoke(new object[] { });

   79         }

   80     }

   81 }

Wow there is _a lot_ more going on here! You are right, because here I make the base test fixture responsible for instantiating the subject under test, including providing mocks for any dependencies that it may have. So it is an auto mocker as well, but the interesting part here is that it puts a reference of the injected mocks in a collection that you can access inside your tests by using the OnDependency<TType> method that returns a Moq object.

Take a look at a specification using this base test fixture class:

    1 namespace Test.Fohjin.DDD.Scenarios.Receiving_money_transfer

    2 {

    3     public class When_receiving_a_money_transfer : BaseTestFixture<MoneyReceiveService>

    4     {

    5         protected override void SetupDependencies()

    6         {

    7             OnDependency<IReportingRepository>()

    8                 .Setup(x => x.GetByExample<AccountReport>(It.IsAny<object>()))

    9                 .Returns(new List<AccountReport> { new AccountReport(Guid.NewGuid(), Guid.NewGuid(), "AccountName", "target account number") });

   10         }

   11 

   12         protected override void When()

   13         {

   14             SubjectUnderTest.Receive(new MoneyTransfer("source account number", "target account number", 123.45M));

   15         }

   16 

   17         [Then]

   18         public void Then_the_newly_created_account_will_be_saved()

   19         {

   20             OnDependency<IBus>().Verify(x => x.Publish(It.IsAny<ReceiveMoneyTransferCommand>()));

   21         }

   22     }

   23 }

So the first thing you see is the method SetupDependencies that is requesting the mock object for injected type IReporintgRepository and it is using the Moq way of setting up the Mock object. This is only needed when in your specification you need the mocks to be setup in a specific way. I intentionally separated the SetupDependencies from the Given as they may be two different things. And in the actual test you see the usage of the OnDependency method again where its being used to verify that something was indeed triggered on the injected class.

Now indeed this is not really treating the subject under test as a black box, for example in the When I make a direct call to a method on the subject under test. So my test knows about this now, meaning when it changes I need to change this test as well. So lets take a look where I go a bit further into the black box mentality.

The PresenterTestFixture<TPresenter>

Here I am not going to show you the code of the PresenterTestFixture implementation as it is almost identical the the previous base test fixture. So lets go straight to an actual specification:

    1 namespace Test.Fohjin.DDD.Scenarios.Adding_a_new_client

    2 {

    3     public class When_in_the_GUI_the_phone_number_of_the_new_client_is_saved : PresenterTestFixture<ClientDetailsPresenter>

    4     {

    5         private object CreateClientCommand;

    6 

    7         protected override void SetupDependencies()

    8         {

    9             OnDependency<IPopupPresenter>()

   10                 .Setup(x => x.CatchPossibleException(It.IsAny<Action>()))

   11                 .Callback<Action>(x => x());

   12 

   13             OnDependency<IBus>()

   14                 .Setup(x => x.Publish(It.IsAny<object>()))

   15                 .Callback<object>(x => CreateClientCommand = x);

   16         }

   17 

   18         protected override void Given()

   19         {

   20             Presenter.SetClient(null);

   21             Presenter.Display();

   22             On<IClientDetailsView>().ValueFor(x => x.ClientName).IsSetTo("New Client Name");

   23             On<IClientDetailsView>().FireEvent(x => x.OnFormElementGotChanged += null);

   24             On<IClientDetailsView>().FireEvent(x => x.OnSaveNewClientName += null);

   25 

   26             On<IClientDetailsView>().ValueFor(x => x.Street).IsSetTo("Street");

   27             On<IClientDetailsView>().ValueFor(x => x.StreetNumber).IsSetTo("123");

   28             On<IClientDetailsView>().ValueFor(x => x.PostalCode).IsSetTo("5000");

   29             On<IClientDetailsView>().ValueFor(x => x.City).IsSetTo("Bergen");

   30             On<IClientDetailsView>().FireEvent(x => x.OnFormElementGotChanged += null);

   31             On<IClientDetailsView>().FireEvent(x => x.OnSaveNewAddress += null);

   32 

   33             On<IClientDetailsView>().ValueFor(x => x.PhoneNumber).IsSetTo("1234567890");

   34             On<IClientDetailsView>().FireEvent(x => x.OnFormElementGotChanged += null);

   35         }

   36 

   37         protected override void When()

   38         {

   39             On<IClientDetailsView>().FireEvent(x => x.OnSaveNewPhoneNumber += null);

   40         }

   41 

   42         [Then]

   43         public void Then_the_save_button_will_be_disabled()

   44         {

   45             On<IClientDetailsView>().VerifyThat.Method(x => x.DisableSaveButton()).WasCalled();

   46         }

   47 

   48         [Then]

   49         public void Then_a_create_client_command_with_all_collected_information_will_be_published()

   50         {

   51             On<IBus>().VerifyThat.Method(x => x.Publish(It.IsAny<CreateClientCommand>())).WasCalled();

   52 

   53             CreateClientCommand.As<CreateClientCommand>().ClientName.WillBe("New Client Name");

   54             CreateClientCommand.As<CreateClientCommand>().Street.WillBe("Street");

   55             CreateClientCommand.As<CreateClientCommand>().StreetNumber.WillBe("123");

   56             CreateClientCommand.As<CreateClientCommand>().PostalCode.WillBe("5000");

   57             CreateClientCommand.As<CreateClientCommand>().City.WillBe("Bergen");

   58             CreateClientCommand.As<CreateClientCommand>().PhoneNumber.WillBe("1234567890");

   59         }

   60 

   61         [Then]

   62         public void Then_overview_panel_will_be_shown()

   63         {

   64             On<IClientDetailsView>().VerifyThat.Method(x => x.Close()).WasCalled();

   65         }

   66     }

   67 }

Again there is the setting up of a dependency in the beginning and then there is the Given method, Presenter in this case is the subject under test, so you can see that the specification still knows about the SUT in the Given, but you will notice that this is not used in either the When or the Then.

Hey what is that On thing in there? Well that is a very small DSL wrapping the Moq API. I did this to make it slightly more readable, and in this case it is very adapt towards working with a view and presenter. In the Given I am setting up my IClientDetailsView with the correct data, but I am also simulating that an event was triggered. This is not logic that the test is concerned about, all we do here is bring the view and the presenter in the correct state for this particular specification. So instead of setting these things directly on the presenter this will all be directed from the view.

Then in the When we again fire an event from the view, but in this case it is the going to trigger the behavior on the presenter that we want to verify. And in the Then methods we verify on the view again that the presenter actually did the correct things, but we also verify on other dependencies that the correct methods where called, in this case the IBus.

I am not completely happy with the mini DSL yet, but I think it is cleaner then the default Moq API. Just for those that are curious, here is the mini DSL which gets returned by the On method:

    1 namespace Test.Fohjin.DDD

    2 {

    3     public class MockDsl<TType> where TType : class

    4     {

    5         private readonly IDictionary<Type, object> _mocks;

    6 

    7         public MockDsl(IDictionary<Type, object> mocks)

    8         {

    9             _mocks = mocks;

   10         }

   11 

   12         public ValueSetter<TType, TProperty> ValueFor<TProperty>(Expression<Func<TType, TProperty>> selector)

   13         {

   14             return new ValueSetter<TType, TProperty>(_mocks, selector);

   15         }

   16 

   17         public void FireEvent(Action<TType> fieldSelector)

   18         {

   19             if (!_mocks.ContainsKey(typeof(TType)))

   20                 throw new Exception(string.Format("The requested dependency '{0}' is not specified in the constructor", typeof(TType).FullName));

   21 

   22             var mock = (Mock<TType>)_mocks[typeof(TType)];

   23             mock.Raise(fieldSelector);

   24         }

   25 

   26         public Verifier<TType> VerifyThat { get { return new Verifier<TType>(_mocks); } }

   27     }

   28 

   29     public class Verifier<TType> where TType : class

   30     {

   31         private readonly IDictionary<Type, object> _mocks;

   32 

   33         public Verifier(IDictionary<Type, object> mocks)

   34         {

   35             _mocks = mocks;

   36         }

   37 

   38         public void ValueIsSetFor(Action<TType> selector)

   39         {

   40             if (!_mocks.ContainsKey(typeof(TType)))

   41                 throw new Exception(string.Format("The requested dependency '{0}' is not specified in the constructor", typeof(TType).FullName));

   42 

   43             var mock = (Mock<TType>)_mocks[typeof(TType)];

   44             mock.VerifySet(selector);

   45         }

   46 

   47         public MethodVerifier<TType> Method(Expression<Action<TType>> selector)

   48         {

   49             return new MethodVerifier<TType>(_mocks, selector);

   50         }

   51     }

   52 

   53     public class MethodVerifier<TType> where TType : class

   54     {

   55         private readonly IDictionary<Type, object> _mocks;

   56         private readonly Expression<Action<TType>> _fieldSelector;

   57 

   58         public MethodVerifier(IDictionary<Type, object> mocks, Expression<Action<TType>> fieldSelector)

   59         {

   60             _mocks = mocks;

   61             _fieldSelector = fieldSelector;

   62         }

   63 

   64         public void WasCalled()

   65         {

   66             if (!_mocks.ContainsKey(typeof(TType)))

   67                 throw new Exception(string.Format("The requested dependency '{0}' is not specified in the constructor", typeof(TType).FullName));

   68 

   69             var mock = (Mock<TType>)_mocks[typeof(TType)];

   70             mock.Verify(_fieldSelector);

   71         }

   72     }

   73 

   74     public class ValueSetter<TType, TProperty> where TType : class

   75     {

   76         private readonly IDictionary<Type, object> _mocks;

   77         private readonly Expression<Func<TType, TProperty>> _fieldSelector;

   78 

   79         public ValueSetter(IDictionary<Type, object> mocks, Expression<Func<TType, TProperty>> fieldSelector)

   80         {

   81             _mocks = mocks;

   82             _fieldSelector = fieldSelector;

   83         }

   84 

   85         public void IsSetTo(TProperty value)

   86         {

   87             if (!_mocks.ContainsKey(typeof(TType)))

   88                 throw new Exception(string.Format("The requested dependency '{0}' is not specified in the constructor", typeof(TType).FullName));

   89 

   90             var mock = (Mock<TType>)_mocks[typeof(TType)];

   91             mock.SetupGet(_fieldSelector).Returns(value);

   92         }

   93     }

   94 }

CQRS and Event Sourcing

By combining CQRS and Event Sourcing we get an architecture that is very suitable for black box testing its behavior, which was a real eye opener when Greg demonstrated this to me. He says that the way to bring your aggregate root back into the desired state is to playback the events that are needed to do so. Then you can execute the behavior on the aggregate root, and finally to actually verify your behavior you retrieve the published events and verify that they are as expected.

Now the beauty of this is that the setup and the verification this will work on any aggregate root because we are using the IEventProvider interface there that they all implement. The only actual knowledge about the aggregate root that remains is the specific behavior that you trigger.

But I went a little bit further then what was shown during the course, I am saying that instead of executing the behavior on the aggregate root we could also just provide the command that should trigger this behavior to be executed. Because the command would be handled by a specific command handler which in turn would execute the domain behavior.

Now below here is the command test fixture that allows me to do just that, I need to provide the actual command, command handler and aggregate root types that are to be used in this specification.

    1 namespace Test.Fohjin.DDD

    2 {

    3     [Specification]

    4     public abstract class CommandTestFixture<TCommand, TCommandHandler, TAggregateRoot> 

    5         where TCommand : class, ICommand

    6         where TCommandHandler : class, ICommandHandler<TCommand>

    7         where TAggregateRoot : class, IOrginator, IEventProvider<IDomainEvent>, new()

    8     {

    9         private IDictionary<Type, object> mocks;

   10 

   11         protected TAggregateRoot AggregateRoot;

   12         protected ICommandHandler<TCommand> CommandHandler;

   13         protected Exception CaughtException;

   14         protected IEnumerable<IDomainEvent> PublishedEvents;

   15         protected virtual void SetupDependencies() { }

   16         protected virtual IEnumerable<IDomainEvent> Given() 

   17         {

   18             return new List<IDomainEvent>();

   19         }

   20         protected virtual void Finally() { }

   21         protected abstract TCommand When();

   22 

   23         [Given]

   24         public void Setup()

   25         {

   26             mocks = new Dictionary<Type, object>();

   27             CaughtException = new ThereWasNoExceptionButOneWasExpectedException();

   28             AggregateRoot = new TAggregateRoot();

   29             AggregateRoot.LoadFromHistory(Given());

   30 

   31             CommandHandler = BuildCommandHandler();

   32 

   33             SetupDependencies();

   34             try

   35             {

   36                 CommandHandler.Execute(When());

   37                 PublishedEvents = AggregateRoot.GetChanges();

   38             }

   39             catch (Exception exception)

   40             {

   41                 CaughtException = exception;

   42             }

   43             finally

   44             {

   45                 Finally();

   46             }

   47         }

   48 

   49         public Mock<TType> OnDependency<TType>() where TType : class

   50         {

   51             return (Mock<TType>)mocks[typeof(TType)];

   52         }

   53 

   54         private ICommandHandler<TCommand> BuildCommandHandler()

   55         {

   56             var constructorInfo = typeof(TCommandHandler).GetConstructors().First();

   57 

   58             foreach (var parameter in constructorInfo.GetParameters())

   59             {

   60                 if (parameter.ParameterType == typeof(IDomainRepository<IDomainEvent>))

   61                 {

   62                     var repositoryMock = new Mock<IDomainRepository<IDomainEvent>>();

   63                     repositoryMock.Setup(x => x.GetById<TAggregateRoot>(It.IsAny<Guid>())).Returns(AggregateRoot);

   64                     repositoryMock.Setup(x => x.Add(It.IsAny<TAggregateRoot>())).Callback<TAggregateRoot>(x => AggregateRoot = x);

   65                     mocks.Add(parameter.ParameterType, repositoryMock);

   66                     continue;

   67                 }

   68 

   69                 mocks.Add(parameter.ParameterType, CreateMock(parameter.ParameterType));

   70             }

   71 

   72             return (ICommandHandler<TCommand>)constructorInfo.Invoke(mocks.Values.Select(x => ((Mock) x).Object).ToArray());

   73         }

   74 

   75         private static object CreateMock(Type type)

   76         {

   77             var constructorInfo = typeof (Mock<>).MakeGenericType(type).GetConstructors().First();

   78             return constructorInfo.Invoke(new object[]{});

   79         }

   80     }

   81 

   82     public class ThereWasNoExceptionButOneWasExpectedException : Exception {}

   83 }

Please note that the Given method now returns an IEnumerable<IDomainEvent> this is to be used to provide the events that are needed to bring the aggregate root into the correct state for this specification. This is using the exact same mechanism as the actual code uses to make state changes in the aggregate root, so there cannot be a case that you are testing your aggregate root using a state that it cannot get into.

The When method returns the expected command, so all you do there is create the command with the correct information and return it to the specification.

Then in the try catch block you may have noticed that a command handler is executing the provided command and that after that the events are being retrieved from the aggregate root. These events are what you would verify to make sure your domain behavior is correct.

But this may all sound very abstract, lets look at a simple specification and see how clean and readable is really is:

    1 namespace Test.Fohjin.DDD.Scenarios.Withdrawing_cash

    2 {

    3     public class When_withdrawing_cash : CommandTestFixture<WithdrawlCashCommand, WithdrawlCashCommandHandler, ActiveAccount>

    4     {

    5         protected override IEnumerable<IDomainEvent> Given()

    6         {

    7             yield return new AccountOpenedEvent(Guid.NewGuid(), Guid.NewGuid(), "AccountName", "1234567890");

    8             yield return new CashDepositedEvent(20, 20);

    9         }

   10 

   11         protected override WithdrawlCashCommand When()

   12         {

   13             return new WithdrawlCashCommand(Guid.NewGuid(), 5);

   14         }

   15 

   16         [Then]

   17         public void Then_a_cash_withdrawn_event_will_be_published()

   18         {

   19             PublishedEvents.Last().WillBeOfType<CashWithdrawnEvent>();

   20         }

   21 

   22         [Then]

   23         public void Then_the_published_event_will_contain_the_amount_and_new_account_balance()

   24         {

   25             PublishedEvents.Last<CashWithdrawnEvent>().Balance.WillBe(15);

   26             PublishedEvents.Last<CashWithdrawnEvent>().Amount.WillBe(5);

   27         }

   28     }

   29 }

So you provide historical events to bring the aggregate root into the expected state, you fire of the command, then you verify the published events to ensure your domain behavior is correct. If you choose the correct naming for your events and commands, then a business person would be able to understand the specification. Especially if you parse the text and do a little bit of formatting.

Where is Should?

Hey what are all those WillBe and WillBeOfType things that I see in your specifications, should they not be ShouldBe and ShouldBeOfType? Well I used to think so as well, until I attended a presentation by Kevlin Henney at NDC where he explained that Should is not specific enough. Should indicates that it might not. I like to use the example; “I should really do the dishes, but I won’t”. By using Will Be and Must you are much more dictating what will or must happen, its not a question anymore.

Finally

I am completely taken by this approach and as you see you don’t need a big BDD framework for this. I think using something like this gives a good learning experience before going towards an actual BDD framework like MSpec. Also Uncle Bob just wrote a good post about to not abuse the Given When Then approach and also take a look at the Mocks aren’t Stubs article by Martin Fowler.

By now you must <grin> understand that I like to throw with code examples so yes the post is very long, but I hope it provides enough value instead of just confusion.

So for example you have some behavior on your domain that gets called when a customer moves, this behavior will publish a Customer Moved event containing the new address. If the domain does not use the address information for any decision making, does it then need to be persisted in the aggregate root?

I guess it would greatly depend on whether or not you are using Event Sourcing to persist your published events (this is what I would suggest). If you do then I don’t see a problem in skipping storing the address information in the aggregate root. Because if at a later time you need the address information to make some decisions then it is easy to retrieve this from the events when reloading the aggregate root from the event store. You just create the address property and an internal event handler to process the Customer Moved event. Just make sure you delete the snapshots first.

But if you do not store all the events that you publish, but instead store only a snapshot then I would not skip storing the new address information, because in the end the domain is responsible for the state, not the reporting side. In other words, you can rebuild the reporting side from the domain, but you cannot necessarily do the same in reverse. So if you don’t store the address information and you need to rebuild the reporting store then you cannot do this.

So my conclusion is that the information should be available on the domain side. And when using CQRS and Event Sourcing to store the events instead of the internal state of the domain then that makes it possible to skip having the information in the domain structure, else not.

My new blog is at at http://cre8ivethought.com/blog/index come and follow me there.

-Mark Nijhof

If you have been following the source code changes on GitHub you may have noticed that I renamed the folder Fohjin.DDD to Fohjin.DDD.Example, my intention is to not make anymore changes there. Instead I have created a new folder next to it and in there I am rebuilding the same components but now with re-use and ease-of-use in mind.

The first thing that is very obvious in the example code is that the domain is not very persistence ignorant, something that is valued a lot in Domain-Driven Design. So this is something that I wanted to try to address first. I really like the way NHibernate makes our code persistence ignorant and am attempting to solve this in a similar manner, using Castle DynamicProxy.

Since I am a complete Castle DynamicProxy noob I asked the help of Krzysztof Koźmic who is an active committer on the Castle project. Krzysztof was gracias enough to get me through the basics in .Net proxy-ing. For those interested in this technology I would also recommend reading his excellent blog series about the same topic.

What I want to achieve is that you get back your poco and I am going to show you one suggestion that I have working now.

For comparison I’ll show you here how an aggregate root looks like in my initial example code (it is stripped down to only contain one behavioral method):

    1 namespace Fohjin.DDD.Domain.Client

    2 {

    3     public class Client : BaseAggregateRoot<IDomainEvent>, IOrginator

    4     {

    5         private Address _address;

    6 

    7         public Client()

    8         {

    9             registerEvents();

   10         }

   11 

   12         public void ClientMoved(Address newAddress)

   13         {

   14             Apply(new ClientMovedEvent(newAddress.Street, newAddress.StreetNumber, newAddress.PostalCode, newAddress.City));

   15         }

   16 

   17         IMemento IOrginator.CreateMemento()

   18         {

   19             return new ClientMemento(Id, Version, _address.Street, _address.StreetNumber, _address.PostalCode, _address.City);

   20         }

   21 

   22         void IOrginator.SetMemento(IMemento memento)

   23         {

   24             var clientMemento = (ClientMemento) memento;

   25             Id = clientMemento.Id;

   26             Version = clientMemento.Version;

   27             _address = new Address(clientMemento.Street, clientMemento.StreetNumber, clientMemento.PostalCode, clientMemento.City);

   28         }

   29 

   30         private void registerEvents()

   31         {

   32             RegisterEvent<ClientMovedEvent>(onNewClientMoved);

   33         }

   34 

   35         private void onNewClientMoved(ClientMovedEvent clientMovedEvent)

   36         {

   37             _address = new Address(clientMovedEvent.Street, clientMovedEvent.StreetNumber, clientMovedEvent.PostalCode, clientMovedEvent.City);

   38         }

   39     }

   40 }

And here is the same aggregate root but now _more_ persistence ignorant:

    1 namespace Fohjin.DDD.Domain.Client

    2 {

    3     public class Client

    4     {

    5         protected virtual void Apply(object @event) { }

    6         protected IEnumerable<Type> RegisteredEvents()

    7         {

    8             yield return typeof(ClientMovedEvent);

    9         }

   10 

   11         protected virtual Address Address { get; set; }

   12 

   13         public void ClientMoved(Address newAddress)

   14         {

   15             Apply(new ClientMovedEvent(newAddress));

   16         }

   17     }

   18 }

Ok this may seem a bit strange at first, I mean we are sending an event into nothing and we don’t set our state anymore. Let me try to explain

Convention over Configuration

Well in order to make this work I am going to insist on some conventions, in fact it is going to be very opinionated. If you want to learn more about convention over configuration then I would suggest reading Jeremy Millers article on MSDN. Personally I am all in favor for some strong guidelines so lets just go over them and see if they make sense to you as well.

Mandatory methods

The protected virtual method Apply and the protected method RegisteredEvents are both mandatory if you want to instantiate the aggregate root using this approach.

In the RegisteredEvents you return all the events that the aggregate root can publish, this is to let the persistence code know what it can expect. So when you add some new behavior that will publish a new event then you just add it to the list here. I think that you can sort of think about this as the mapping classes in NHibernate.

The Apply method is used to publish the events from the domain behavior, but as you can see it has an empty method body, so nothing will happen, right? Here we use Castle DynamicProxy to intercept calls to this method and replace the behavior (non-existing) with our persistence logic. Where this logic comes from I’ll explain in a minute.

Internal state needs to be protected virtual properties

One other difference with this approach versus the example code is that instead of private fields or private properties for the internal state, it now needs to be in the form of protected virtual properties. The reason for this is because state will not be managed by the aggregate root anymore, but instead by something that we add using Castle DynamicProxy and we will be using interception to map the properties to the internal representation of the state. The code even throws an exception if the aggregate root tries to set the internal state directly.

The event store

I haven’t done anything with the event store yet, I don’t think the functionality will change much from the code in the example project. One thing that will remain the same is the dependency on interfaces, and not on specific implementations. This is obviously because it is good design practices. And it will enable us to mix this new approach and the approach using the BaseAggregateRoot class together with the same event store. The BaseAggregateRoot is discussed in detail here.

Mix-in magic

So after reading the previous chapter you would probably say, but this aggregate root doesn’t implement anything? This is true, but when our repository is instantiating the aggregate root it is also adding or injecting two more classes into it. One class that implements the IEventProvider interface and an other class that implements the IOrginator interface. This is called mixing-in classes and by doing so the aggregate root will implement both these two interfaces and it will re-direct calls to it to the mix-in classes. So as far as our event store knows it just is a class that implements the needed interfaces.

Why have everything protected?

Well in order to be able to intercept members using Castle DynamicProxy these members need to be visible to the interceptor. The most private way that is available to us is protected, and the reason why I want this to be as private as possible is because this is not domain logic, and thus should not be visible to the users of the domain. For the same reason you may notice that for example the IEventProvider implementation has all the members implement the interface explicitly thus hiding them when the domain is used and only showing them when the domain is explicitly casted to the IEventProvider interface.

I have been thinking about providing a basic interface that dictates that the Apply and RegisterEvents methods needs to be present, but I like this approach better as from the outside these implementation details would not be known, but I could imagine being able to support both approaches.

Reflect only once

There is quit a bit of reflection going on to discover and the properties of both the domain events and the aggregate root internal state. But once this is done once the results will be cached and re-used for each sequential need. But I am sure this can improve quit a bit

Conventional limits

So what if I run into the limits of this conventional approach? Well the Event Store only cares about that the different interfaces are implemented, so you will be able to switch back to the BaseAggregateRoot solution at any time. This does mean that you will have to do some more coding, but you will have all the freedom to do what ever you need to do. And the different approaches can be used side by side.

One other limit is that if you instantiate the aggregate root yourself nothing will be intercepted and mixed-in so no state will change nor will the events be published.

Current state

Currently the code only supports very basic usages and there are some challenges ahead of it being truly useable. Think for example about other entities in the same aggregate managed by the aggregate root and collecting their events as well. Also think about adding and removing entities from a list which may need some configurable conventions so you can decide when something needs to be added or removed.

I am thinking about the ability to provide adapters to be able to handle certain state changes differently from the conventional way. One that I see a need for already is the ability to set the aggregate root Id, since this is not managed by the aggregate root but by the event provider mix-in.

Finally

Currently the functionality is very limited but I have tests passing proving that this is working so what I would like is to get some feedback on this approach. And yes I realize that this is very opinionated, and will not fit everybody’s approach. Having said that, keep the suggestions coming anyway.

My new blog is at at http://cre8ivethought.com/blog/index come and follow me there.

-Mark Nijhof

As you may have seen in my previous post “CQRS à la Greg Young” now our domain aggregate root is responsible for publishing domain events indicating that some internal state has changed. In fact state changes within our aggregate root are _only_ allowed through such domain events. Secondly the internal event handlers are _not_ allowed to have any sort of business logic in them, they are _only_ supposed to set or update the internal state of the aggregate root directly from the data the event carries. Using these rules you completely separate the business logic from the state changes. This separation enables us to replay historical domain events without any business logic being triggered bringing it back to the same state as the original aggregate root.

Why is this important? Well now we can use these same domain events for our persistence using an Event Store, this pattern by Martin Fowler is called “Event Sourcing”. Obviously you don’t want to process a credit card or send an e-mail every time you load an aggregate root from the event store. Also from the time the original domain event was recorded and when the aggregate root is loaded from the event store the business logic that decided a state change was needed could have changed, this should not affect the actual historical state change. So this separation is to be taken seriously.

Domain events can also be used to signal something to the outside world (taken from the aggregate roots view point) that something has happened without having an actual state change. When persisting our domain events we would not differentiate between those two different domain events.

All domain events should be named with the ubiquitous language in mind, meaning that they should closely represent what the user intended to do in the same language as the user would use to explain it to you. By keeping all these domain events we gain a huge amount of knowledge about what happened and why it happened.

This means that our aggregate root gets the added responsibility of tracking these domain events, but I don’t see this as being any different then for example the proxy that NHibernate generates for you, except perhaps that it is not a proxy and that you have more control over what happens. But it is true your aggregate root has these added responsibilities.

So let us take a look at how the aggregate root provides this functionality, for obvious reasons we use a base class for this, but really all that is needed is that the aggregate root implements the following two interfaces:

    1 namespace Fohjin.DDD.EventStore.Storage.Memento

    2 {

    3     public interface IOrginator

    4     {

    5         IMemento CreateMemento();

    6         void SetMemento(IMemento memento);

    7     }

    8 }

The IOrginator interface is for the snapshot functionality which is an optimization technique for speeding up loading aggregate roots from the Event Store. As you can see it is using the “Memento” patter from the Gang Of Four book. I wanted to get this interface out of the way first; it is not needed, but does provide a good optimization for loading aggregate roots.

    1 namespace Fohjin.DDD.EventStore

    2 {

    3     public interface IEventProvider

    4     {

    5         void Clear();

    6         void LoadFromHistory(IEnumerable<IDomainEvent> domainEvents);

    7         void UpdateVersion(int version);

    8         Guid Id { get; }

    9         int Version { get; }

   10         IEnumerable<IDomainEvent> GetChanges();

   11     }

   12 }

The IEventProvider interface is the most interesting interface of the two, this one defines how domain events can be retrieved from the aggregate root and how historical domain events can be loaded back. It also defines that each aggregate root must have an Id and a Version, both of these are used by the event store, the Id is obvious so I won’t go into that, the version on the other hand may not be that obvious. The version is used to detect concurrency violations, meaning this is used to prevent conflicts that occur because between the time the command was send and the aggregate root was saved an other user or process has updated the same aggregate root. In this case we would throw an Concurrency Violation Exception which currently results in a rollback. In a future post I plan to look into how you could try to deal with these concurrency violations automatically.

Using domain events for state change

Now we will take a look at how these interfaces are implemented and how the implementation is used. The way I am going to go through the code is as if you where using R# going from method to method. So in order to get a more overall impression  I would encourage you to look at the source code. The source code can be found here: http://github.com/MarkNijhof/Fohjin

Each aggregate root has to register the domain events and the internal event handlers with the base class. I am working on getting this as static information for the type since this will not change between different instances of the same type. As you can see I am registering the domain event type and an action to handle the specific type. As you can see the actions have the specific domain event as an input parameter.

    1 private void registerEvents()

    2 {

    3     RegisterEvent<ClientCreatedEvent>(onNewClientCreated);

    4     RegisterEvent<ClientMovedEvent>(onNewClientMoved);

    5 }

    6 

    7 private void onNewClientCreated(ClientCreatedEvent clientCreatedEvent)

    8 {

    9     Id = clientCreatedEvent.ClientId;

   10     _clientName = new ClientName(clientCreatedEvent.ClientName);

   11     _address = new Address(clientCreatedEvent.Street, clientCreatedEvent.StreetNumber, clientCreatedEvent.PostalCode, clientCreatedEvent.City);

   12     _phoneNumber = new PhoneNumber(clientCreatedEvent.PhoneNumber);

   13 }

   14 

   15 private void onNewClientMoved(ClientMovedEvent clientMovedEvent)

   16 {

   17     _address = new Address(clientMovedEvent.Street, clientMovedEvent.StreetNumber, clientMovedEvent.PostalCode, clientMovedEvent.City);

   18 }

The RegisterEvent method is defined in the BaseAggregateRoot class, here is a little bit of interesting logic going on where basically a new action is defined that has an IDomainEvent as an input parameter, that is how they can all be stored in the same Dictionary. Then inside this action the provided action is invoked where the input value is cast from an IDomainEvent to the actual expected type TEvent.

    1 private readonly Dictionary<Type, Action<IDomainEvent>> _registeredEvents;

    2 protected void RegisterEvent<TEvent>(Action<TEvent> eventHandler) where TEvent : class, IDomainEvent

    3 {

    4     _registeredEvents.Add(typeof(TEvent), theEvent => eventHandler(theEvent as TEvent));

    5 }

So if we would write the example out of what is actually happening for the Client Created Event then it would look like this example below, and this is what is being stored in the _registeredEvents.

    1 public void Delegate(IDomainEvent domainEvent)

    2 {

    3     onNewClientCreated(domainEvent as ClientCreatedEvent);

    4 }

And below here is the private apply method that is being called from two different methods in the aggregate root base class. The method retrieves the action that is registered for the provided domain event, and than it invokes the action with the domain event as the input parameter. The apply method takes an IDomainEvent instead of the specific domain event and because of that we have the above mentioned logic.

    1 private void apply(Type eventType, IDomainEvent domainEvent)

    2 {

    3     Action<IDomainEvent> handler;

    4 

    5     if (!_registeredEvents.TryGetValue(eventType, out handler))

    6         throw new UnregisteredDomainEventException(string.Format("The requested domain event '{0}' is not registered in '{1}'", eventType.FullName, GetType().FullName));

    7 

    8     handler(domainEvent);

    9 }

Let us take a look from where this apply method is being called, first we will look at some actual domain behavior in the aggregate root.

    1 public void Withdrawl(Amount amount)

    2 {

    3     Guard();

    4 

    5     IsBalanceHighEnough(amount);

    6 

    7     var newBalance = _balance.Withdrawl(amount);

    8 

    9     Apply(new CashWithdrawnEvent(newBalance, amount));

   10 }

First we execute all our valuable domain logic, the business behavior. Then when we are satisfied that everything is ok and we know what type of state change we need to execute and we Apply a new domain event with the new internal state. The Apply method used here is a protected method on the BaseAgregateRoot. Btw there is nothing stating that there can only be one outcome, i.e. only one type of domain event being Applied.

    1 protected void Apply<TEvent>(TEvent domainEvent) where TEvent : class, IDomainEvent

    2 {

    3     domainEvent.AggregateId = Id;

    4     domainEvent.Version = GetNewEventVersion();

    5     apply(domainEvent.GetType(), domainEvent);

    6     _appliedEvents.Add(domainEvent);

    7 }

When we Apply a domain event we will first assign the aggregate root Id to the event so that we can keep track to which aggregate root this event belongs to. Secondly we get a new version and assign this to the event, this is to maintain the correct order of the events. Then we call the apply method which will make the state change to the aggregate root. And finally we will add this domain event to the internal list of applied events. This is very similar with the dirty check of NHibernate (the idea, not the actual implementation).

This is all what what is needed to execute domain behavior and keep track of the domain events that have been used to update internal state of an aggregate root.

Getting the state changes

So now we have build up some internal state changes and we want to persist them to some sort of medium. I am not going to discuss how to actually persist these state changes, that is for a later post, all I want to show you now is how to get them out of the aggregate root. How about we start with the method GetChanges

    1 IEnumerable<IDomainEvent> IEventProvider.GetChanges()

    2 {

    3     return _appliedEvents

    4         .Concat(GetEntityEvents())

    5         .OrderBy(x => x.Version)

    6         .ToList();

    7 }

    8 

    9 private IEnumerable<IDomainEvent> GetEntityEvents()

   10 {

   11     return _entityEventProviders

   12         .SelectMany(entity => entity.GetChanges());

   13 }

Here we simply return all the applied domain events, by tracking these domain events we in effect track all the state changes that have happened since the aggregate root was instantiated. Here we also request all the applied domain events from all entities. Than new order the domain events by version. After having received and processed all the applied domain events we should Clear the aggregate root from all applied domain events so they won’t be persisted again.

    1 void IEventProvider.Clear()

    2 {

    3     _entityEventProviders.ForEach(x => x.Clear());

    4     _appliedEvents.Clear();

    5 }

Just a quick word about the entity event providers, in some cases you want to have domain behavior inside entities that are part of the aggregate but are not the aggregate root. Well in this case you want to have those entities generate domain events as well, and you want to get those as well when getting all changes. Same when clearing the domain also the changes inside each entity event provider should be cleared.

Before saving the changes in the aggregate root is finalized we also need to update the version of the aggregate root. This version will match the version of the last applied domain event.

Loading historical domain events

In a next post I’ll dig deeper into the event store but for now lets just assume you have a very nice way of storing these domain events and have the ability to retrieve them again.

As the IEventProvider interface nicely dictates there is a LoadFromHistory method that takes an IEnumerable<IDomainEvent> below here is the implementation of this method.

    1 void IEventProvider.LoadFromHistory(IEnumerable<IDomainEvent> domainEvents)

    2 {

    3     if (domainEvents.Count() == 0)

    4         return;

    5 

    6     foreach (var domainEvent in domainEvents)

    7     {

    8         apply(domainEvent.GetType(), domainEvent);

    9     }

   10 

   11     Version = domainEvents.Last().Version;

   12     EventVersion = Version;

   13 }

When you take a look in the for each loop you will notice that here we are calling apply again, please note that this is the private variant which is responsible for updating the internal state of the aggregate root and that these events are not added to the _appliedEvents collection, nor is the Id or Version updated. We don’t want to save these events again. After applying all the historical domain events we update the aggregate root version to the version of the last event.

The base class

I am using a base class to provide this functionality to all the different aggregate roots using inheritance and I know there are different opinions about this. So I wanted to highlight that you can achieve the same results by using composition. Your aggregate roots still need to implement the interfaces, but the implementation can be provided by using composition.

An other thing is that all the public methods in the BaseAggregateRoot are explicate interface implementation. I do this because I want to hide these details for any piece of code that is using the aggregate root as is, only when dealing with persistence we use the interface and get access to the explicit interface methods. Nice and clean.

Aggregate entities

Ok I have already mentioned the term entities and entity event providers, and I would like to focus on them for a bit. An entity is an domain object that is part of the same aggregate as the aggregate root, but is not the aggregate root it self, is however it is managed by the aggregate root. We manage state changes in these entities in the exact same way as we do this in the aggregate root, so each entity is also an event provider. There is a different interface for the entities then for the aggregate root so they can not be confused among each other.

    1 namespace Fohjin.DDD.EventStore

    2 {

    3     public interface IEntityEventProvider 

    4     {

    5         void Clear();

    6         void LoadFromHistory(IEnumerable<IDomainEvent> domainEvents);

    7         void HookUpVersionProvider(Func<int> versionProvider);

    8         IEnumerable<IDomainEvent> GetChanges();

    9         Guid Id { get; }

   10     }

   11 }

You may have also noticed the hookup version provider method, remember it

The problem is that we should deal with the whole aggregate as a whole so all state changes need to be persisted within the same transaction. So we want to have a single point to access the internal state of the whole aggregate as well as a single point to load the history back into the whole aggregate. In order to achieve this the aggregate root needs to register all the entity event providers so it can track them. To enable that we have an additional interface for our aggregate root to implement.

    1 namespace Fohjin.DDD.EventStore

    2 {

    3     public interface IRegisterEntities

    4     {

    5         void RegisterEntityEventProvider(IEntityEventProvider entityEventProvider);

    6     }

    7 }

Lets look at the implementation right away

    1 void IRegisterEntities.RegisterEntityEventProvider(IEntityEventProvider entityEventProvider)

    2 {

    3     entityEventProvider.HookUpVersionProvider(GetNewEventVersion);

    4     _entityEventProviders.Add(entityEventProvider);

    5 }

Now this is only a very simple collection that hold references to IEntityEventProviders which is used in the previous shown GetEntityEvents method. So getting out the changes is relatively simple this way. I also created a special collection that will automatically register entities when they are added to the collection.

Remember I mentioned the HookUpVersionProvider method, well this is used to get a reference to the method from the aggregate root that deals with assigning a new version to each event. We want a reference to the same version generator that the aggregate root uses because then all the versions of each domain event will be in sequence independently is the aggregate root or an entity created it.

    1 namespace Fohjin.DDD.Domain

    2 {

    3     public class EntityList<TEntity> : List<TEntity> where TEntity : IEntityEventProvider

    4     {

    5         private readonly IRegisterEntities _aggregateRoot;

    6 

    7         public EntityList(IRegisterEntities aggregateRoot)

    8         {

    9             _aggregateRoot = aggregateRoot;

   10         }

   11 

   12         public new void Add(TEntity entity)

   13         {

   14             _aggregateRoot.RegisterEntityEventProvider(entity);

   15             base.Add(entity);

   16         }

   17     }

   18 }

The collection takes a reference to the aggregate root it is part of in the constructor to be able to add each added entity event provider to the collection in the aggregate root.

Currently there is some duplication between the BaseAggregateRoot and the BaseEntity because they are inherited from different interfaces, I am sure there is some optimization possible there

There is finally one more thing to cover about this and that is how historical domain events are being passed into the correct entity, currently this is a bit ugly but I am working on a more elegant solution. Take a look at the code.

    1 private void registerEvents()

    2 {

    3     // Registration of Aggregate Root event handlers

    4 

    5     RegisterEvent<BankCardWasReportedStolenEvent>(onAnyEventForABankCard);

    6     RegisterEvent<BankCardWasCanceledByCLientEvent>(onAnyEventForABankCard);

    7 }

    8 

    9 private void onAnyEventForABankCard(IDomainEvent domainEvent)

   10 {

   11     IEntityEventProvider bankCard;

   12     if (!_bankCards.TryGetValueById(domainEvent.AggregateId, out bankCard))

   13         throw new NonExistingBankCardException("The requested bank card does not exist!");

   14 

   15     bankCard.LoadFromHistory(new[] { domainEvent });

   16 }

So each entity domain event will be registered here as well and are all passed to one specific event handler (one specific event handler for each different entity type). What happens is that we check if the specific event provider is present in the collection by looking for the Id, when the requested event provider is found the historical domain event will be loaded using the load from history method on the event provider.

The problem here is that the information which events the entity can produce is already registered, and that is in the entities them self’s. So by making that information statically available I should be able to auto register the entity event handlers.

Finally

I hope that this was a useful explanation of how the aggregate root works with the internal domain events, and that you would agree with me that it really is not very difficult. Next time I want to discuss the event store so we can take a look at persisting the domain events. I will also post a blog about making the entity registration more elegant and less manual work.

My new blog is at at http://cre8ivethought.com/blog/index come and follow me there.

-Mark Nijhof

Jan van Ryswyck put again a great deal of effort into getting the E-VAN recording of my CQRS presentation uploaded so quickly. We are only talking about one day, almost seems like he has nothing else to do Thanks Jan!

The recording can be found here: http://www.vimeo.com/7838858

When you create an account at Vimeo (free) then you can also download the recordings in even better quality.

The code that the presentation covers can be found here: http://github.com/MarkNijhof/Fohjin

I hope that many will provide their feedback, both good and bad as this is how I evolve.