At the end of the conference, we were interviewed by the local .NET magazine dNM and that video is now available here. We covered the background on things like DDD, CQRS, and the Cloud. I don’t think that either of us said anything earth-shattering but if you have half an hour, take a look:

I think I’ve just about drove everybody crazy now with my apparent zigzagging on CQRS.

Some people heard about CQRS first from one of my presentations and got all excited about it. Then I did some blogging which further drove people to CQRS (as did Greg Young and some others). As CQRS was just about to hit its stride with the Early Adopters, I started pushing a more balanced view – CQRS not as an answer, but as one of many questions. More recently I’ve pushed more strongly back against CQRS saying that it should be used rarely.

So what’s the missing piece?

If you’re in the Domain-Driven Design camp (as many doing CQRS are), then it’s Bounded Contexts.

If you’re in the Event-Driven SOA camp (a much smaller camp to be sure), then it’s Services.

The problem is the naming, because the DDD guys have their kinds of services which do not fit the definition for Service of the Event-Driven SOA approach.

Let me propose the term Autonomous Business Component for the purposes of this blog post to describe that thing which is both a DDD Bounded Context (have the shared BC part of the acronym) and an SOA Autonomous Services. Resulting in the nice short form: ABC (and everyone knows you need to have a good acronym if you want something to catch on).

What does this have to do with CQRS?

Nothing just yet. Well, at least, nothing directly to do with CQRS.

Although some proponents of CQRS have stated that it can and should be used as the top-most architectural pattern, both myself and Greg Young (arguably the first two to talk about it and the two who ultimately collaborated on naming it – and now Google knows we didn’t means “cars”) always recommended it as a pattern to be used one level down.

Although Greg and I have had many long discussions on the topic and do agree very much about what the overall structure should look like, I’ll try to avoid putting words in his mouth from this point on.

Before talking more about ABCs, let’s discuss the principle upon which they rest: The Single Responsibility Principle (SRP).

What does SRP have to with CQRS?

Many developers are familiar with SRP and have seen good results from using it. What we’re going to do is take this principle to the next level.

In Object Orientation (OO), data is encapsulated in an object. A good object does not expose its data to other objects to do with as they wish. Rather, it exposes methods that other objects can invoke, and those methods operate on the internal data.

SRP would guide us to not have the same data exist in two objects. For example, if we saw the customer’s first name as an internal data member of two objects, we’d be right to question that kind of duplication and move to refactor it away. However, when we see two systems doing the exact same thing – somehow that gets excused.

“Of course we need to be able to see the customer’s first name in the front-end website as well as in the back-end fulfillment system. How could we NOT have the customer’s first name in both those code-bases?”

And there’s the catch.

Who said that a system should be a single code-base?

But what about integration?

Although many times we do need to integrate existing systems together, sometimes we have the ability to change those systems. More importantly, when going to create a new solution, we can avoid getting ourselves into the problems that integration tries to solve.

Integrating with a system that cannot be changed can be done also by composing multiple ABCs, but that’s a topic for another post.

It is better to think of integration as a necessary evil – kind of like regular expressions and multi-threading; things to be avoided unless absolutely necessary.

“If you have a problem that you decide to use a regular expression to solve, you now have 2 problems.” Or so the saying goes. With multi-threading, you have a non-deterministic number of problems to solve.

If you thought you had duplicate responsibilities with 2 systems operating on the same data, how will introducing a 3rd code base (also known as “integration”) help? Remember that Single Responsibility Principle – our goal is to get it down to one.

OK, so how do ABCs do that?

In order for us to get back into alignment with SRP, that would require us to have responsibility for a single piece of data exist in one code base. Note that SRP makes no statements about how many physical places a given code base can be deployed to. Nor does it state that only a single technology can be in play – code that emits HTML can be packaged at design time together with rich-client code in the same solution.

If an ABC is responsible for a piece of data, it is responsible for it everywhere, and forever. No other ABC should see that data. That data should not travel between ABCs via remote procedure call (RPC) or via publish/subscribe. It is the ultimate level of encapsulation – SRP applied at the highest level of granularity.

This results in systems which are the result of deploying the components of multiple ABCs to the same physical place. The ABC which owns the customer name would have the necessary web code to render it in the e-commerce front-end and in the shipping back-end for printing on labels. This would mean that practically every screen in any UI is a composite of widgets owned by their respective ABCs.

This is ultimately what keeps the complexity of each ABC’s code base to a minimum.

But why not just use CQRS as the top-level pattern? ABCs are weird.

Imagine trying to create a single denormalized view model for the entire Amazon.com product page – product name, price, inventory, editorial review, customer comments, other products that customers viewed, other products that customers bought, etc.

Pretty complex, right?

How much duplication would you have for the page shown after you add an item to a cart? Once again, you need to show other products that customers bought, their names, images, prices, and inventory.

And then on the home page – items you might be interested in, names, images, prices.

And that’s only in the front-end system.

It’s not just the duplication, but how complex the code is for each one.

Instead of the duplication that top-level CQRS would bring you, consider an ABC responsible for products names and images that has just about the same view model composed on each of the above screens. The same with another ABC responsible for price.

You may be thinking that this would result in more queries to get the data to show on a page, and you’d be right. But it isn’t necessarily a classical N+1 Select problem, as the queries are bounded to the number of ABCs. Secondly, consider the ability to have well-tuned caching at the granularity of an ABC – something that would be much more difficult when dealing with everything as a single monolithic view model. In short, not only will it not be a performance problem, often it will actually improve performance.

OK – that explains “everywhere”, what about “forever”?

Forever is where things get interesting – or more accurately, when they get interesting.

Let’s talk about things like invoices.

One of the requirements in this area is that immutability. If the customer’s name was Jane Smith when they made their purchase, it doesn’t matter that they’ve since changed their name to Jane Jones, the invoice should still show Jane Smith.

Often developers push these types of requirements on the data warehouse guys – that’s where history gets handled. The only thing is that if your ABC owns the customer’s name, then no other code base can deal with it. If it’s your data, you have to handle all historical representations of it.

On the one hand, this would seem to kill the data warehouse. On the other hand, it means that the principles of data warehouses are now core to every code-base.

This means you don’t ever delete data (see my previous blog post on the subject), and you definitely don’t overwrite it with an update – even if you think you’re in a simple CRUD domain. The only case where you can get away with traditional CRUD is if we’re talking about private data – data that is only ever acted on by a single actor.

This sounds like the collaboration you talk about with CQRS

It’s similar in principle but different in practice.

In a collaborative domain, an inherent property of the domain is that multiple actors operate in parallel on the same set of data. A reservation system for concerts would be a good example of a collaborative domain – everyone wants the “good seats” (although it might be better call that competitive rather than collaborative, it is effectively the same principle).

A customer’s name would not fall under that category. It isn’t an inherent property of the domain for multiple actors to operate on that data. While there can be multiple readers, one can easily enforce a single writer without any adverse effects. Doing that with a reservation system would cause the online system to behave as if users were lining up in front of a box office – not a desirable outcome.

Private data would be something like a user’s shopping cart. Until they make a purchase, that data doesn’t need to be visible anywhere. Here you could theoretically do simple CRUD – that is, until the business realizes that there’s extremely valuable information to be extracted from the historical record of things people do with their carts.

I think you’re ready to make your point, so just make it already

OK – so we now realize that Update and Delete don’t exist in their traditional form. Delete is really just a kind of update, and update is effectively an “upsert” – a combination of update and insert to retain history. This can be done by having ValidFrom and ValidTo columns for our data.

In which case, Create is really just a special case of Upsert, which looks like this:

UPDATE Something SET ValidTo = NOW() WHERE Id=@Id AND ValidTo = NULL; INSERT INTO Something SET { regular values }, Id=@Id, ValidTo = NULL;

And then we’d have 2 forms of Read – reading the current state (ValidTo = NULL), and reading history (ValidFrom <= Instant AND (ValidTo >= Instant OR ValidTo = NULL))

Here we don’t need fancy N-Tier architectures, data transfer objects, service layers, or domain models. A simple 2-Tier approach could probably suffice. We don’t need a task-based UI, events, denormalized view models, or any of that CQRS stuff. This was at the crux of my previous anti-CQRS post.

The only thing is that this is exactly CQRS.

Say what?

Have we not effectively separated the responsibility of commands/upserts and queries/reads?

As Greg Young has said before, “the creation of 2 objects where there previously was one”.

Effectively 2 paths through our ABC.

CQRS.

Let me give you a second to gather your thoughts.

*

You see, CQRS is an approach, a mind-set – not a cookie cutter solution. Frameworks that guide you to applying CQRS exactly the same way everywhere are taking you in the wrong direction. The fact is that you couldn’t possibly know what your Aggregate Roots were before you figured out how to break your system down into ABCs. Attempting to create commands and events for everything will make you overcomplicate your solution.

So the built-in history of this model is event-sourcing?

Well, it’s not event-sourcing in the sense that we don’t necessarily have events. It achieves many of the benefits of event-sourcing by giving us the full history of what happened.

On the whole issue of replaying events to fix bugs – that’s a bit problematic, logically, unless we have a closed system. A closed system is one that doesn’t interact with anything else – no other systems, no users, nothing. As such, closed systems aren’t that common.

In an open system, one with users, let’s say there was a bug. This bug could have caused the wrong data to be written and/or shown to users. As such, users could have submitted subsequent commands based on that erroneous data that they would not have submitted otherwise. There’s no way for us to know.

The problem with replaying events when we fix the bug is that we’re in essence rewriting history – making it as if the user didn’t see the wrong data. The only problem is that we can’t know which events not to replay – we can’t automatically come up with the right events that should have come afterwards. We could try to sit together with our users and have them try to revise history manually, but our organization often isn’t in a bubble. Our users interacted with customers and suppliers. It isn’t feasible to try to undo the real-world impacts of this situation.

Why didn’t you just tell us this from the very beginning?

I did, you just weren’t listening.

You wanted a cookie cutter, and until you tried CQRS out as cookie cutter (and saw it create a bunch of complexity) you wouldn’t listen to anything else.

As developers, we’re trained to solve problems – the faster the better. Unfortunately, this causes us to be blind to things that don’t immediately present themselves as solutions.

When applying CQRS with ABCs, the solutions you end up with are very simple, but the process of getting there is quite hard and takes practice. Finding the boundaries of ABCs such that data isn’t duplicated between them and that data doesn’t travel between them either via RPC or publish/subscribe – it may feel impossible the first several times you try. Keep at it – it is almost always possible.

We haven’t touched on the whole saga/aggregate-root thing yet, but that isn’t as important until you can successfully apply the principles described here.

Also, this post has already gotten long enough, so it looks like now would be a good time to stop.

Until next time…

The problem

Let’s start with an image to describe the scenario:

The main issue we have here is that the values transaction 2 gets for A and B are those from T0 – before either transaction 1 or 3 completed. The reason this is an issue is that these old values (usually together with some message data) are used to calculate what the new state of C should be.

Traditional optimistic concurrency techniques won’t detect any problem if we don’t touch A or B in transaction 2.

In short, systems today are causing inconsistency.

Some solutions

1. Don’t have transactions which operate on multiple entities (which probably isn’t possible for some of your most important business logic).

2. Turn on multi-version concurrency control – this is called snapshot isolation in MS Sql Server.

Yes, you need to turn it on. It’s off by default.

The good news is that this will stop the writing of inconsistent data to your database.
The bad news is that it will probably cause your system many more exceptions when going to persist.

For those of you who are using transaction messaging with automatic retrying, this will end up as “just” a performance problem (unless you follow the recommendations below). For those of you who are using regular web/wcf services (over tcp/http), you’re “cross cutting” exception management will likely end up discarding all the data submitted in those requests (but since that’s what you’re doing when you run into deadlocks this shouldn’t be news to you).

The solution to the performance issues

Eventual consistency.

Funny isn’t it – all those people who were afraid of eventual consistency got inconsistency instead.

Also, it’s not enough to just have eventual consistency (like between the command and query sides of CQRS). You need to drastically decrease the size of your entities. And the best way of doing that is to partition those entities across multiple business services (also known in DDD lingo as Bounded Contexts) each with its own database.

This is yet another reason why I say that CQRS shouldn’t be the top level architectural breakdown. Very useful within a given business service, yes – though sometimes as small as just some sagas.

Next steps

It may seem unusual that the title of this post implies that SOA is the solution, yet the content clearly states that traditional HTTP-based web services are a problem. Even REST wouldn’t change matters as it doesn’t influence how transactions are managed against a database.

The SOA solution I’m talking about here is the one I’ve spent the last several years blogging about. It’s a different style of SOA which has services stretch up to contain parts of the UI as well as down to contain parts of the database, resulting in a composite UI and multiple databases. This is a drastically different approach than much of the literature on the topic – especially Thomas Erl’s books.

Unfortunately there isn’t a book out there with all of this in it (that I’ve found), and I’m afraid that with my schedule (and family) writing a book is pretty much out of the question. Let’s face it – I’m barely finding time to blog.

The one thing I’m trying to do more of is provide training on these topics. I’ve just finished a course in London, doing another this week in Aarhus Denmark, and another next month in San Francisco (which is now sold out). The next openings this year will be in Stockholm, London; Sydney Australia and Austin Texas will be coming in January of next year. I’ll be coming over to the US more next year so if you missed San Francisco, keep an eye out.

I wish there was more I could do, but I’m only one guy.

Hmm, maybe it’s time to change that.

Please accept my apologies for my part in the overly-complex software being created because of it.

I’ve tried to do what I could to provide a balanced view on the topic with posts like Clarified CQRS and Race Conditions Don’t Exist.

It looks like that wasn’t enough, so I’ll go right out and say it:

Most people using CQRS (and Event Sourcing too) shouldn’t have done so.

Should we really go back to N-Tier?

When not using CQRS (which is the majority of the time), you don’t need N-Tier either.

You see, if you’re not in a collaborative domain then you don’t have multiple writers to the same logical set of data as an inherent property of your domain. As such, having a single database where all data lives isn’t really necessary.

Data is inherently partitioned by who owns it.

Let’s take the online shopping cart as an example. There aren’t any use cases where users operate on each others’ carts – ergo, not collaborative, therefore not a good candidate for CQRS. Same goes for user profiles, and tons of other cases.

So why is it that we need a separate tier to run our business logic?

Originally, the application server tier was introduced for improved scalability, but specifically around managing the connection pool to the database. Increasing numbers of clients (when each had its own user/account for connecting to the database) caused problems. Luckily, most web applications side-step this problem – that is, until someone got the idea that the web server was only supposed to run the UI layer, and the Business Logic layer would be on a separate application server tier.

Rubbish – see Fowler’s First Law of Distribution: Don’t.

Keep it all on one tier. Same goes for smart clients.
No, Silverlight, you don’t count – architecturally speaking, you’re a glorified browser.

But what about scalability?

In a non-collaborative domain, where you can horizontally add more database servers to support more users/requests/data at the same time you’re adding web servers – there is no real scalability problem (caveat, until you’re Amazon/Google/Facebook scale).

Database servers can be cheap – if using MySQL/SQL Express/others.

But what about the built-in event-log CQRS/ES gives us?

Architectural gold-plating / stealing from the business.

Who put you in a position to decide that development time and resources should be diverted from short-term business-value-adding features to support a non-functional requirement that the business didn’t ask for?

If you sat down with them, explaining the long-term value of having an archive of all actions in the system, and they said OK, build this into the system from the beginning, that would be fine. Most people who ask me about CQRS and/or Event Sourcing skip this step.

Finally, you can usually implement this specific requirement with some simple interception and logging. Don’t over-engineer the solution. If using messaging, you can get this by turning on journaling, or if you want to centralize this archive, NServiceBus can forward all messages to a specific queue.

Don’t forget that this storage has a cost – including administration. Nothing is free.

What about the “proof of correctness” in Event Sourcing

I’ve heard statements made that when you use the events that flowed into/through your system AS your system’s data, rather than transforming those events to some other schema (relational or otherwise) and storing the result – you can prove that your system behaves correctly.

Let me put it this way:

No programming technique used by humans will prevent those same humans from creating bugs.
No testing technique used by humans will prevent those same humans from not catching those bugs.
* Automated tests – see programming technique.

While having a full archive of all events can allow us to roll the system back to some state, fix a bug, and roll forwards, that assumes that we’re in a closed system. We have users which are outside the system. If a user made a decision based on data influenced by the bug, there’s no automated way for us to know that, or correct for it as we roll forwards.

In short, we’re interested in the business’ behavior – as composed of user and system behavior. No proof can exist.

Umm, so where should we use it

If you’ve uncovered a scenario where you’re wondering “first-one-wins, or last-one-wins”, that’s often a good candidate for a place where CQRS could make sense. Then re-read my Race Conditions Don’t Exist post.

Also, CQRS should not be your top-level architectural pattern – that would be SOA.
CQRS, if used at all, would be used inside a service boundary only.

Given that SOA guides us away from having a given 3rd normal form entity exist in any one service, it is unlikely that the building blocks of your CQRS design will be those kinds of entities. Most 3rd normal form one-to-many and many-to-many relationships simply do not exist when doing SOA and CQRS properly.

Therefore, I’m sorry to say that most sample application you’ll see online that show CQRS are architecturally wrong. I’d also be extremely wary of frameworks that guide you towards an entity-style aggregate root CQRS model.

In Summary

So, when should you avoid CQRS?

The answer is most of the time.

Here’s the strongest indication I can give you to know that you’re doing CQRS correctly: Your aggregate roots are sagas.

And the biggest caveat – the above are generalizations, and can’t necessarily be true for every specific scenario. If you’re Greg Young, then you probably can (and will) decide on your own on these matters. For everybody else, please take these warnings to heart. There have been far too many clients that have come to me all mixed up with their use CQRS in areas where it wasn’t warranted.

If you want to know everything you need to know to apply CQRS appropriately, please come to my course – there is so much unlearning to do first that just can’t happen via a series of blog posts.

Let me just say this upfront – most inter-related entity models are NOT a domain model.
Here’s why: most transactions don’t respect entity boundaries.

That being said, you don’t always need a domain model.
The domain model pattern’s context is “if you have complicated and everchanging business rules” – right there on page 119 of Patterns of Enterprise Application Architecture.

Persisting the customer’s first name, last name, and middle initial – and later reading and showing that data does not sound either complicated or that it is really going to change that much.

Then there are things like credit limits, that may be on the customer entity as well. It is likely that there are business requirements that expect that value to be consistent with the total value of unpaid orders – data that comes from other entities.

The problem that is created is one of throughput.

Since databases lock an entire row/entity at a time, if one transaction is changing the customer’s first name, the database would block another transaction that tried to change the same customer’s credit limit.

The bigger your entities, the more transactions will likely need to operate on them in parallel, the slower your system will get as the number of transactions increases. This feeds back in on itself as often those blocked transactions will have operated already on some other entity, leaving those locked for longer periods of times, blocking even more transactions.

And the absurd thing is that the business never demanded that the customer’s first name be consistent with the credit limit.

What if we didn’t have a single Customer entity?

What if we had one that contained first name, last name, middle initial and another that contained things like credit limit, status, and risk rating. These entities would be correlated by the same ID, but could be stored in separate tables in the database. That would do away with much of the cascading locking effects drastically improving our throughput as load increases.

And you know what? That division would still respect the 3rd normal form.

Which of these entities do you think would be classified by the business under the “complicated and everchanging rules” category?

And for those entities that are just about data persistence – do you think it’s justified to use 3 tiers? Do we really need a view model which we transform to data transfer objects which we transform to domain objects which we transform to relational tables and then all the way back? Wouldn’t some simpler 2-tier programming suffice – dare I say datasets? Ruby on Rails?

Are we ready to leave behind the assumption that all elements of a given layer must be built the same way?

After I had finished speaking at QCon London last March, I sat down for a short interview with the guys from InfoQ chatting about topics from CQRS, to DDD, to NServiceBus. I’m happy to say that the interview is now online with a full (and mostly accurate) transcript as well as with an MP3 download link.

Get it here: Udi Dahan on CQRS, DDD and NServiceBus

Update

The recording of the talk is now online and can be found here.

You can find the slides for my talk here.

I’ve gotten some questions about my DDD presentation there based on Aaron Jensen’s pictures:

Yes – I talk with my hands. All the time.

That slide is quite an important one – I talked about it for at least 2 hours.

Here it is again, this time in full:

You may notice that the nice clean layered abstraction that the industry has gotten so comfortable with doesn’t quite sit right when looking at it from this perspective. The reason for that is that this perspective takes into account physical distribution while layers don’t.

I’ll have some more posts on this topic as well as giving a session in TechEd Europe this November.

Oh – and please do feel free to already send your questions in.

The real world doesn’t cascade

Let’s say our marketing department decides to delete an item from the catalog. Should all previous orders containing that item just disappear? And cascading farther, should all invoices for those orders be deleted as well? Going on, would we have to redo the company’s profit and loss statements?

Heaven forbid.

So, is Ayende wrong? Do we really need soft deletes after all?

On the one hand, we don’t want to leave our database in an inconsistent state with invoices pointing to non-existent orders, but on the other hand, our users did ask us to delete an entity.

Or did they?

When all you have is a hammer…

We’ve been exposing users to entity-based interfaces with “create, read, update, delete” semantics in them for so long that they have started presenting us requirements using that same language, even though it’s an extremely poor fit.

Instead of accepting “delete” as a normal user action, let’s go into why users “delete” stuff, and what they actually intend to do.

The guys in marketing can’t actually make all physical instances of a product disappear – nor would they want to. In talking with these users, we might discover that their intent is quite different:

“What I mean by ‘delete’ is that the product should be discontinued. We don’t want to sell this line of product anymore. We want to get rid of the inventory we have, but not order any more from our supplier. The product shouldn’t appear any more when customers do a product search or category listing, but the guys in the warehouse will still need to manage these items in the interim. It’s much shorter to just say ‘delete’ though.”

There seem to be quite a few interesting business rules and processes there, but nothing that looks like it could be solved by a single database column.

Model the task, not the data

Looking back at the story our friend from marketing told us, his intent is to discontinue the product – not to delete it in any technical sense of the word. As such, we probably should provide a more explicit representation of this task in the user interface than just selecting a row in some grid and clicking the ‘delete’ button (and “Are you sure?” isn’t it).

As we broaden our perspective to more parts of the system, we see this same pattern repeating:

Orders aren’t deleted – they’re cancelled. There may also be fees incurred if the order is canceled too late.

Employees aren’t deleted – they’re fired (or possibly retired). A compensation package often needs to be handled.

Jobs aren’t deleted – they’re filled (or their requisition is revoked).

In all cases, the thing we should focus on is the task the user wishes to perform, rather than on the technical action to be performed on one entity or another. In almost all cases, more than one entity needs to be considered.

Statuses

In all the examples above, what we see is a replacement of the technical action ‘delete’ with a relevant business action. At the entity level, instead of having a (hidden) technical WasDeleted status, we see an explicit business status that users need to be aware of.

The manager of the warehouse needs to know that a product is discontinued so that they don’t order any more stock from the supplier. In today’s world of retail with Vendor Managed Inventory, this often happens together with a modification to an agreement with the vendor, or possibly a cancellation of that agreement.

This isn’t just a case of transactional or reporting boundaries – users in different contexts need to see different things at different times as the status changes to reflect the entity’s place in the business lifecycle. Customers shouldn’t see discontinued products at all. Warehouse workers should, that is, until the corresponding Stock Keeping Unit (SKU) has been revoked (another status) after we’ve sold all the inventory we wanted (and maybe returned the rest back to the supplier).

Rules and Validation

When looking at the world through over-simplified-delete-glasses, we may consider the logic dictating when we can delete to be quite simple: do some role-based-security checks, check that the entity exists, delete. Piece of cake.

The real world is a bigger, more complicated cake.

Let’s consider deleting an order, or rather, canceling it. On top of the regular security checks, we’ve got some rules to consider:

If the order has already been delivered, check if the customer isn’t happy with what they got, and go about returning the order.

If the order contained products “made to order”, charge the customer for a portion (or all) of the order (based on other rules).

And more…

Deciding what the next status should be may very well depend on the current business status of the entity. Deciding if that change of state is allowed is context and time specific – at one point in time the task may have been allowed, but later not. The logic here is not necessarily entirely related to the entity being “deleted” – there may be other entities which need to be checked, and whose status may also need to be changed as well.

Summary

I know that some of you are thinking, “my system isn’t that complex – we can just delete and be done with it”.

My question to you would be, have you asked your users why they’re deleting things? Have you asked them about additional statuses and rules dictating how entities move as groups between them? You don’t want the success of your project to be undermined by that kind of unfounded assumption, do you?

The reason we’re given budgets to build business applications is because of the richness in business rules and statuses that ultimately provide value to users and a competitive advantage to the business. If that value wasn’t there, wouldn’t we be serving our users better by just giving them Microsoft Access?

In closing, given that you’re not giving your users MS Access, don’t think about deleting entities. Look for the reason why. Understand the different statuses that entities move between. Ask which users need to care about which status. I know it doesn’t show up as nicely on your resume as “3 years WXF”, but “saved the company $4 million in wasted inventory” does speak volumes.

One last sentence: Don’t delete. Just don’t.

My article on “employing the domain model pattern” has been published in the August edition of MSDN Magazine.

Here’s a short excerpt:

“In this article, we’ll go through the reasons to (and not to) employ the domain model pattern, the benefits it brings, as well as provide some practical tips on keeping the overall solution as simple as possible.”

Continue reading…

My previous post on Domain Events left some questions about how aggregate roots should be created unanswered. It would actually be more accurate to say how aggregate roots should *not* be created. It turns out that this is one of the less intuitive parts of domain-driven design and has been the source of many arguments on the matter. Let’s start with the wrong way:

   1:  using (ISession s = sf.OpenSession())

   2:  using (ITransaction tx = s.BeginTransaction())

   3:  {

   4:      Customer c = new Customer();

   5:      c.Name = "udi dahan";

   6:   

   7:      s.Save(c);

   8:      tx.Commit();

   9:  }

I understand that the code above is representative of how much code is written when using an object-relational mapper. Many would consider this code to follow DDD principles – that Customer is an aggregate root. Unfortunately – that is not the case. The code above is missing the real aggregate root.

There’s also the inevitable question of validation – if the customer object isn’t willing to accept a name with a space in it, should we throw an exception? That would prevent an invalid entity from being saved, which is good. On the other hand, exceptions should be reserved for truly exceptional occurrences. But if we don’t use exceptions, using Domain Events instead, how do we prevent the invalid entity from being saved?

All of these issues are handled auto-magically once we have a true aggregate root.

Always Get An Entity

Let’s start with the technical guidance – always get an entity. At least one. Also, don’t add any objects to the session or unit of work explicitly – rather, have some other already persistent domain entity create the new entity and add it to a collection property.

Looking at the code above, we see that we’re not following the technical guidance.

But the question is, which entity could we possibly get from the database in this case? All we’re doing is adding a customer.

And that’s exactly where the technical guidance leads us to the business analysis that was missing in this scenario…

Business Analysis

Customers don’t just appear out of thin air.

Blindingly obvious – isn’t it.

So why would we technically model our system as if they did? My guess is that we never really thought about it – it wasn’t our job. So here’s the breaking news – if we want to successfully apply DDD we do need to think about it, it is our job.

Going back to the critical business question:

Where do customers come from?

In the real world, they stroll into the store. In our overused e-commerce example, they navigate to our website. New customers that haven’t used our site before don’t have any cookies or anything we can identify them with. They navigate around, browsing, maybe buying something in the end, maybe not.

Yet, the browsing process is interesting in its own right:

• Which products did they look at?
• Did they use the search feature?
• How long did they spend on each page?
• Did they scroll down to see the reviews?

If and when they do finally buy something, all that history is important and we’d like to maintain a connection to it.

Actually, even before they buy something, what they put in their cart is the interesting piece. The transition from cart to checkout is another interesting piece. Do they actually complete the checkout process, or do they abandon it midway through?

Add to that when we ask/force them to create a user/login in our system.

Are they actually a customer if they haven’t bought anything?

We’re beginning to get an inkling that almost every activity that results in the creation of an entity or storing of additional information can be traced to a transition from a previous business state.

In any transition, the previous state is the aggregate root.

In the beginning…

Let’s start at the very beginning then – someone came to our site. Either they navigated here from some other web page, they clicked on an email link someone sent them, or they typed in our URL. This can be designed as follows:

   1:  using (ISession s = sf.OpenSession())

   2:  using (ITransaction tx = s.BeginTransaction())

   3:  {

   4:     var referrer = s.Get<Referrer>(msg.URL);

   5:     referrer.BroughtVisitorWithIp(msg.IpAddress);

   6:   

   7:     tx.Commit();

   8:  }

   9:   

And our referrer code could look something like this:

   1:  public void BroughtVisitorWithIp(string ipAddress)

   2:  {

   3:     var visitor = new Visitor(ipAddress);

   4:     this.NewVisitors.Add(visitor);

   5:  }

   6:   

This follows the technical guidance we saw at the beginning.

It also allows us to track which referrer is bringing us which visitors, through tracking those visitors as they become shoppers (by putting stuff in their cart), finally seeing which become customers.

We can solve the situation of not having a referrer by implementing the null object pattern which is well supported by all the standard object-relational mappers these days.

How it works internally

When we call a method on a persistent entity retrieved by the object-relational mapper, and the entity modifies its state like when it adds a new entity to one of its collection properties, when the transaction commits, here’s what happens:

The mapper sees that the persistent entity is dirty, specifically, that its collection property was modified, and notices that there is an object in there that isn’t persistent. At that point, the mapper knows to persist the new entity without us ever having to explicitly tell it to do so. This is sometimes known as “persistence by reachability”.

Where validation happens

Let’s consider the relatively trivial rule that says that a user name can’t contain a space.

Also, keep in mind that a registered user is the result of a transition from a visitor.

Here’s *one* way of doing that:

   1:  public class Visitor

   2:  {

   3:     public void Register(string username, string password)

   4:     {

   5:        if (username.Contains(" "))

   6:        {

   7:           DomainEvents.Raise<UsernameCantContainSpace>();

   8:           return;

   9:        }

  10:   

  11:        var user = new User(username, password);

  12:        this.RegisteredUser = u;

  13:     }

  14:  }

  15:   

This actually isn’t representative of most of the rules that will be found in the domain model, but it illustrates a way of preventing an entity from being created without our service layer needing to know anything. All the service layer does is get the visitor object and call the Register method.

Validation of string lengths, data ranges, etc is not domain logic and is best handled elsewhere (and a topic for a different post). The same goes for uniqueness.

Summary

The most important thing to keep in mind is that if your service layer is newing up some entity and saving it – that entity isn’t an aggregate root *in that use case*. As we saw above, in the original creation of the Visitor entity by the Referrer, the visitor class wasn’t the aggregate root. Yet, in the user registration use case, the Visitor entity was the aggregate root.

Aggregate roots aren’t a structural property of the domain model.

And in any case, don’t go saving entities in your service layer – let the domain model manage its own state. The domain model doesn’t need any references to repositories, services, units of work, or anything else to manage its state.

If you do all this, you’ll also be able to harness the technique of fetching strategies to get the best performance out of your domain model by representing your use cases as interfaces on the domain model like IRegisterUsers (implemented by Visitor) and IBringVisitors (implemented by Referrer).

And spending some time on business analysis doesn’t hurt either – unless customers really do fall out of the sky in your world

Background

Before diving right into the code, I wanted to take a minute to recall how we got here.

It started by looking for how to create fully encapsulated domain models.

The main assertion being that you do *not* need to inject anything into your domain entities.

Not services. Not repositories. Nothing.

Just pure domain model goodness.

Make Roles Explicit

I’m going to take the advice I so often give. A domain event is a role, and thus should be represented explicitly:

   1:  public interface IDomainEvent {}

If this reminds you of the IMessage marker interface in nServiceBus, you’re beginning to see where this is going…

How to define domain events

A domain event is just a simple POCO that represents an interesting occurence in the domain. For example:

   1:  public class CustomerBecamePreferred : IDomainEvent 

   2:  {

   3:      public Customer Customer { get; set; }

   4:  }

For those of you concerned about the number of events you may have, and therefore are thinking about bunching up these events by namespaces or things like that, slow down. The number of domain events and their cohesion is directly related to that of the domain model.

If you feel the need to split your domain events up, there’s a good chance that you should be looking at splitting your domain model too. This is the bottom-up way of identifying bounded contexts.

How to raise domain events

In your domain entities, when a significant state change happens you’ll want to raise your domain events like this:

   1:  public class Customer

   2:  {

   3:      public void DoSomething()

   4:      {

   5:          DomainEvents.Raise(new CustomerBecamePreferred() { Customer = this });

   6:      }

   7:  }

We’ll look at the DomainEvents class in just a second, but I’m guessing that some of you are wondering “how did that entity get a reference to that?” The answer is that DomainEvents is a static class. “OMG, static?! But doesn’t that hurt testability?!” No, it doesn’t. Here, look:

Unit testing with domain events

One of the things we’d like to check when unit testing our domain entities is that the appropriate events are raised along with the corresponding state changes. Here’s an example:

   1:  public void DoSomethingShouldMakeCustomerPreferred()

   2:  {

   3:      var c = new Customer();

   4:      Customer preferred = null;

   5:   

   6:      DomainEvents.Register<CustomerBecamePreferred>(

   7:          p => preferred = p.Customer

   8:              );

   9:   

  10:      c.DoSomething();

  11:      Assert(preferred == c && c.IsPreferred);

  12:  }

As you can see, the static DomainEvents class is used in unit tests as well. Also notice that you don’t need to mock anything – pure testable bliss.

Who handles domain events

First of all, consider that when some service layer object calls the DoSomething method of the Customer class, it doesn’t necessarily know which, if any, domain events will be raised. All it wants to do is its regular schtick:

   1:  public void Handle(DoSomethingMessage msg)

   2:  {

   3:      using (ISession session = SessionFactory.OpenSession())

   4:      using (ITransaction tx = session.BeginTransaction())

   5:      {

   6:          var c = session.Get<Customer>(msg.CustomerId);

   7:          c.DoSomething();

   8:   

   9:          tx.Commit();

  10:      }

  11:  }

The above code complies with the Single Responsibility Principle, so the business requirement which states that when a customer becomes preferred, they should be sent an email belongs somewhere else.

Notice that the key word in the requirement – “when”.

Any time you see that word in relation to your domain, consider modeling it as a domain event.

So, here’s the handling code:

   1:  public class CustomerBecamePreferredHandler : Handles<CustomerBecamePreferred>

   2:  { 

   3:     public void Handle(CustomerBecamePreferred args)

   4:     {

   5:        // send email to args.Customer

   6:     }

   7:  } 

This code will run no matter which service layer object we came in through.

Here’s the interface it implements:

   1:  public interface Handles<T> where T : IDomainEvent

   2:  {

   3:      void Handle(T args); 

   4:  } 

Fairly simple.

Please be aware that the above code will be run on the same thread within the same transaction as the regular domain work so you should avoid performing any blocking activities, like using SMTP or web services. Instead, prefer using one-way messaging to communicate to something else which does those blocking activities.

Also, you can have multiple classes handling the same domain event. If you need to send email *and* call the CRM system *and* do something else, etc, you don’t need to change any code – just write a new handler. This keeps your system quite a bit more stable than if you had to mess with the original handler or, heaven forbid, service layer code.

Where domain event handlers go

These handler classes do not belong in the domain model.

Nor do they belong in the service layer.

Well, that’s not entirely accurate – you see, there’s no *the* service layer. There is the part that accepts messages from clients and calls methods on the domain model. And there is another, independent part that handles events from the domain. Both of these will probably make use of a message bus, but that implementation detail shouldn’t deter you from keeping each in their own package.

The infrastructure

I know you’ve been patient, reading through all my architectural blah-blah, so here it is:

   1:  public static class DomainEvents

   2:  { 

   3:      [ThreadStatic] //so that each thread has its own callbacks

   4:      private static List<Delegate> actions;

   5:   

   6:      public static IContainer Container { get; set; } //as before

   7:   

   8:      //Registers a callback for the given domain event

   9:      public static void Register<T>(Action<T> callback) where T : IDomainEvent

  10:      {

  11:         if (actions == null)

  12:            actions = new List<Delegate>();

  13:   

  14:         actions.Add(callback);

  15:     }

  16:   

  17:     //Clears callbacks passed to Register on the current thread

  18:     public static void ClearCallbacks ()

  19:     {

  20:         actions = null;

  21:     }

  22:   

  23:     //Raises the given domain event

  24:     public static void Raise<T>(T args) where T : IDomainEvent

  25:     {

  26:        if (Container != null)

  27:           foreach(var handler in Container.ResolveAll<Handles<T>>())

  28:              handler.Handle(args);

  29:   

  30:        if (actions != null)

  31:            foreach (var action in actions)

  32:                if (action is Action<T>)

  33:                    ((Action<T>)action)(args);

  34:     }

  35:  } 

Notice that while this class *can* use a container, the container isn’t needed for unit tests which use the Register method.

When used server side, please make sure that you add a call to ClearCallbacks in your infrastructure’s end of message processing section. In nServiceBus this is done with a message module like the one below:

   1:  public class DomainEventsCleaner : IMessageModule

   2:  { 

   3:      public void HandleBeginMessage() { }

   4:   

   5:      public void HandleEndMessage()

   6:      {

   7:          DomainEvents.ClearCallbacks();

   8:      }

   9:  }

The main reason for this cleanup is that someone just might want to use the Register API in their original service layer code rather than writing a separate domain event handler.

Summary

Like all good things in life, 3rd time’s the charm.

It took a couple of iterations, and the API did change quite a bit, but the overarching theme has remained the same – keep the domain model focused on domain concerns. While some might say that there’s only a slight technical difference between calling a service (IEmailService) and using an event to dispatch it elsewhere, I beg to differ.

These domain events are a part of the ubiquitous language and should be represented explicitly.

CustomerBecamePreferred is nothing at all like IEmailService.

In working with your domain experts or just going through a requirements document, pay less attention to the nouns and verbs that Object-Oriented Analysis & Design call attention to, and keep an eye out for the word “when”. It’s a critically important word that enables us to model important occurrences and state changes.

What do you think? Are you already using this approach? Have you already tried it and found it broken in some way? Do you have any suggestions on how to improve it?

Let me know – leave a comment below.

Factory methods on repositories

In the podcast, Rob describes an ecommerce application with orders, customers, products – all the stuff you’ve come to expect. In his pre-DDD design, the order class had multiple constructors representing different rules. Feeling the pain in testing and maintainability, Rob looked to use DDD principles. What he did to get rid of these constructors was to make use of the repository by creating methods for the various cases, like OrderRepository.CreateOrderForGovernmentCustomer(/*data*/); .

While this is better than the multiple constructors, it still has a way to go. Analyzing what’s going on here we understand that the way the order is created is dependent upon who the user is. The rules dictating terms of payment are probably different for government customers. Not only that but we know that the order created needs to be connected to that user.

Aggregate Roots & Polymorphism

For all these reasons, it looks like user, or customer, is our aggregate root. Thus, rather than our service layer calling the above method on the repository, we first get the user object by id, then create the order like so:

IUser u = session.Get<IUser>(IdOfUserLoggedIn);
u.CreateOrder(/* data */);

This way, our service layer doesn’t need to perform all sorts of business logic (if the user is a gov’t user, do this, a corporate customer, do that, etc). All of that gets encapsulated by the domain. By leveraging some polymorphism, the session will return an instance of the correct class when we ask it for a user by id. Thus, logic relating to how gov’t users create orders is encapsulated in the GovernmentUser class.

I’ve found that this pattern of having polymorphic aggregate roots is very useful and broadly applicable.

Bounded Contexts

Further into the podcast, Rob talks about how separating his system into 2 bounded contexts simplified the code greatly. The understanding that accepting an order and fulfilling an order require different logic, different data, and thus, different domain model objects is DDD at its finest.

However, when talking about the total cost of the order, it wasn’t clear what was responsible for that. From a pure programming perspective, we might think that Total was simply a property on Order or, at most, a GetTotal() method. Yet by looking at what is involved in calculating the total of an order, a different picture emerges:

The total cost of an order obviously includes all relevant taxes. We need to take into account state and federal taxes, tax-free items at each level, etc. There’s a fair amount of logic here. Once we start to take into account promotions like “buy one, get one free”, things get even more involved. There are also cases where refunds are applied within the same order that impact the total and tax (no tax on refunds). Finally, when we include shipping charges, tax on shipping, and other rules between all of the above, it’s clear that if we put all of this in a single method, we’ve got ourselves a big bloated sack of … well, you get the picture.

Separating all of this logic into different bounded contexts makes sense.

That is, until you think about how you’re going to take these and stitch out of them a single result shown to the user. This is the advanced side of DDD and ties into SOA, so I’ll leave it for a different post.

In Closing

Working with DDD provides a great deal of value by tying our code much more closely to business concepts and encapsulating business rules in the domain model.

Starting down the DDD path is intuitive and the code that results (like u.CreateOrder) is very understandable. Yet, as more DDD principles like Bounded Contexts are put to use, developers often find themselves in unfamiliar, less-intuitive waters. This is to be expected.

Some developers (and vendors) look at DDD as nothing more than the domain model and repository patterns. The truth is that they’re just the beginning.

I hope that this post has given those of you just starting down the DDD path some feeling for how deep the rabbit hole goes, and I assure you that there are patterns in place to answer all your questions. While those beginning DDD often say that it gives names to things they’ve always been doing, or always wanted to do, I can assure you that the further down you go, that is less and less the case.

Be ready to have some basic architectural assumptions shaken

Value Objects Don’t Count

While the canonical example presented is Customer -> Address, and has a good treatment here for nHibernate, it isn’t architecturally representative.

Addresses are value objects. What this means is that if we have to instance of the Address class, and they both have the same business data, they are semantically equivalent. Customers, on the other had, are not value objects – they’re entities. If we have two customers with the same business data (both of them called Bob Smith), that does not mean they are semantically equivalent – they are not the same person.

All Entities

Therefore, for our purposes here we’ll use something different. Say we have an entity called Job which is something that a company wants to hire for. It has a title, description, skill level, and a bunch of other data. Say we also have another entity called Job Board which is where the company posts jobs so that applicants can see them, like Monster.com. A job board has a name, description, web site, referral fee, and a bunch of other data.

A job can be posted to multiple job boards. And a job board can have multiple jobs posted. A regular many to many relationship. At this point, we’re not even going to complicate the association.

This is simply represented in the DB with an association table containing two columns for each of the entity tables’ ids.

In the domain model, developers can also represent this with the Job class containing a list of JobBoard instances, and the JobBoard class containing a list of jobs.

It’s intuitive. Simple. Easy to implement. And wrong.

In order to make intelligent DDD choices, we’re going to first take what may seem to be a tangential course, but I assure you that your aggregate roots depend on it.

Moving forward with our example

Let’s say the user picks a job, and then ticks off the job boards where they want the job posted, and clicks submit.

For simplicity’s sake, at this point, let’s ignore the communication with the actual job sites, assuming that if we can get the association into the DB, magic will happen later causing the job to appear on all the sites.

Our well-intentioned developer takes the job ID, and all the job board IDs, opens a transaction, gets the job object, gets the job board objects, adds all the job board objects to the job, and commits, as follows:

   1:          public void PostJobToBoards(Guid jobId, params Guid[] boardIds)

   2:          {

   3:              using (ISession s = this.SessionFactory.OpenSession())

   4:              using (ITransaction tx = s.BeginTransaction())

   5:              {

   6:                  var job = s.Get<Job>(jobId);

   7:                  var boards = new List<JobBoard>();

   8:   

   9:                  foreach(Guid id in boardIds)

  10:                      boards.Add(s.Get<JobBoard>(id));

  11:   

  12:                  job.PostTo(boards);

  13:   

  14:                  tx.Commit();

  15:              }

  16:          }

In this code, Job is our aggregate root. You can see that is the case since Job is the entry point that the service layer code uses to interact with the domain model. Soon we’ll see why this is wrong.

** Notice that in this service layer code, our well-intentioned developer is following the rule that while you can get as many objects as you like, you are only allowed one method call on one domain object. The code called in line 12 is what you’d pretty much expect:

   1:          public void PostTo(IList<JobBoard> boards)

   2:          {

   3:              foreach(JobBoard jb in boards)

   4:              {

   5:                  this.JobBoards.Add(jb);

   6:                  jb.Jobs.Add(this);

   7:              }

   8:          }

Only that as we were committing, someone deleted one of the job boards just then. Or that someone updated the job board causing a concurrency conflict. Or anything that would cause one single association to not be created.

That would cause the whole transaction to fail and all changes to roll back.

Rightly so, thinks our well-intentioned developer.

But users don’t think like well-intentioned developers.

Partial Failures

If I were to go to the grocery store with the list my wife gave me, finding that they’re out of hazelnuts (the last item on the list), would NOT buy all the other groceries and go home empty handed, what do you think would happen?

Right. That’s how users look at us developers. Before running off and writing a bunch of code, we need to understand the business semantics of users actions, including asking about partial failures.

The list isn’t a unit of work that needs to succeed or rollback atomically. It’s actually many units of work. I mean, I wouldn’t want my wife to send me to the store 10 times to buy 10 items, so the list is really just a kind of user shortcut. Therefore, in the job board scenario, each job to job board connection is its own transaction.

This is more common than you might think.

Once you go looking for cases where the domain is forgiving of partial failures, you may start seeing more and more of them.

Aggregate Roots

In the original transaction where we tried to connect many job boards to a single job, we saw that the single job is the aggregate root. However, once we have multiple transactions, each connecting one job and one job board, the job board is just as likely an aggregate root as the job.

We can do   jobBoard.Post(job);    or     job.PostTo(jobBoard);

But we need just a bit more analysis to come to the right decision.

While we could just leave the bi-directional/circular dependency between them, it would be preferable if we could make it uni-directional instead. To do that, we need to understand their relationship:

If there was no such thing as “job”, would there be meaning to “job board” ? Probably not.

If there was no such thing as “job board”, would there be meaning to “job” ? Probably. Yes. Our company can handle the hiring process of a job regardless of whether the candidate came in through Monster.com or not.

From this we understand that the uni-directional relationship can be modelled as one-to-many from job board to job. The Job class would no longer have a collection of Job Board objects. In fact, it could even be in an assembly separate from Job Board and not reference Job Board in any way. Job Board, on the other hand, would still have a collection of Job objects.

Going back to the code above we see that the right choice is   jobBoard.Post(job);   

Job Board is the aggregate root in this case. Also, the many-to-many mapping has now dissolved, leaving behind a single one-to-many mapping.

Let that sink in a second.

But Wait…

While the GUI showing which jobs are posted on a given job board are well served by the above decision (simply traversing the object graph from Job Board to its collection of Jobs), that’s not the whole story. Another GUI needs to show administrative users which Job Boards a given Job has been posted to. Since we no longer have the domain-level connection, we can’t traverse myJob.JobBoards.

Our only option is to perform a query. That’s not so bad, but not as pretty as object traversal.

The real benefit is in chopping apart the Gordian M-to-N mapping knot and getting a cleaner, more well factored domain model.

That gives us much greater leverage for bigger, system-level decomposition.

We’re now all set to move up to a pub/sub solution between these aggregate roots, effectively upgrading them to Bounded Contexts. From there, we can move to full-blown internet-scale caching with REST for extra scalability on showing a job board with all its jobs.

In Closing

We often look at many-to-many relationships just like any other relationship. And from a purely technical perspective, we’re not wrong. However, the business reality around these relationships is often very different – forgiving of partial failures, to the point of actually requiring them.

Since the business folks who provide us with requirements rarely think of failure scenarios, they don’t specify that “between these two entities here, I don’t want transactional atomicity” (rolling our technical eyes – the idiots [sarcasm, just to make sure you don't misread me]).

Yet, if we were to spell out what the system will do under failure conditions when transactionally atomic, those same business folks will be rolling our eyes back to us.

What I’ve found surprises some DDD practitioners is how critical this issue really is to arriving at the correct aggregate roots and bounded contexts.

It’s also simple, and practical, so you won’t be offending the YAGNI police.

Related Content

From CRUD to Domain-Driven Fluency

[Podcast] Domain Models, SOA, and The Single Version of the Truth

My previous post on how to create fully encapsulated domain models introduced the concept of events as a core pattern of communication from the domain back to the service layer. In that post, I put up enough code to get the idea across but didn’t address issues like memory leaks and multi-threading. This post will show the solution to those two critical points.

I’ve snipped out one of the events in the previous example for brevity.

Previous API

The previous API looked like this:

   1:  public static class DomainEvents

   2:  {

   3:       public static event EventHandler GameReportedLost;

   4:       public static void RaiseGameReportedLostEvent()

   5:       {

   6:             if (GameReportedLost != null)

   7:                 GameReportedLost(null, null);

   8:       }

   9:   

  10:       public static event EventHandler CartIsFull;

  11:       public static void RaiseCartIsFull()

  12:       {

  13:             if (CartIsFull != null)

  14:                 CartIsFull(null, null);

  15:       }

  16:  }

One thing that we want to keep in the solution is that all the code to define events, their names, and the parameters they bring will be in one place – in this case, the DomainEvents class. One thing that we’d like to fix is the amount of code needed to define an event.

Previous Service Layer

Here’s what our previous service layer code looked like:

   1:  public class AddGameToCartMessageHandler :

   2:      BaseMessageHandler<AddGameToCartMessage>

   3:  {

   4:      public override void Handle(AddGameToCartMessage m)

   5:      {

   6:          using (ISession session = SessionFactory.OpenSession())

   7:          using (ITransaction tx = session.BeginTransaction())

   8:          {

   9:              ICart cart = session.Get<ICart>(m.CartId);

  10:              IGame g = session.Get<IGame>(m.GameId);

  11:   

  12:              Domain.DomainEvents.GameReportedLost +=

  13:                gameReportedLost;

  14:              Domain.DomainEvents.CartIsFull +=

  15:                cartIsFull;

  16:   

  17:              cart.Add(g);

  18:   

  19:              Domain.DomainEvents.GameReportedLost -=

  20:                gameReportedLost;

  21:              Domain.DomainEvents.CartIsFull -=

  22:                cartIsFull;

  23:   

  24:              tx.Commit();

  25:          }

  26:      }

  27:   

  28:      private EventHandler gameReportedLost = delegate { 

  29:            Bus.Return((int)ErrorCodes.GameReportedLost);

  30:          };

  31:   

  32:      private EventHandler cartIsFull = delegate { 

  33:            Bus.Return((int)ErrorCodes.CartIsFull);

  34:          };

  35:      }

  36:  }

Another thing that should be improved is the amount of code needed in the service layer.

Raising an event, though, should still be fairly simple – one line of code similar to DomainEvents.RaiseGameReportedLost().

New API

Here’s what the new API looks like:

   1:  public static class DomainEvents

   2:  {

   3:       public static readonly DomainEvent<IGame> GameReportedLost = 

   4:                                            new DomainEvent<IGame>;

   5:   

   6:       public static readonly DomainEvent<ICart> CartIsFull=

   7:                                            new DomainEvent<ICart>;

   8:  }

It looks like we’ve managed to bring down the complexity of defining an event.

Raising an event is slightly different, but still only one line of code (”this” refers to the Cart class that is calling this API): DomainEvents.CartIsFull.Raise(this);

New Service Layer

The advantage of having a disposable domain event allows us to use the “using” construct for cleanup.

   1:  public class AddGameToCartMessageHandler :

   2:      BaseMessageHandler<AddGameToCartMessage>

   3:  {

   4:      public override void Handle(AddGameToCartMessage m)

   5:      {

   6:          using (ISession session = SessionFactory.OpenSession())

   7:          using (ITransaction tx = session.BeginTransaction())

   8:          using (DomainEvents.GameReportedLost.Register(gameReportedLost))

   9:          using (DomainEvents.CartIsFull.Register(cartIsFull))

  10:          {

  11:              ICart cart = session.Get<ICart>(m.CartId);

  12:              IGame g = session.Get<IGame>(m.GameId);

  13:   

  14:              cart.Add(g);

  15:   

  16:              tx.Commit();

  17:          }

  18:      }

  19:   

  20:      private Action<IGame> gameReportedLost = delegate { 

  21:            Bus.Return((int)ErrorCodes.GameReportedLost);

  22:          };

  23:   

  24:      private Action<ICart> cartIsFull = delegate { 

  25:            Bus.Return((int)ErrorCodes.CartIsFull);

  26:          };

  27:      }

  28:  }

I also want to mention that you don’t necessarily have to have the same service layer object handle these events as that which calls the domain objects. In other words, we can have singleton objects handling these events for things like sending emails, notifying external systems, and auditing.

The Infrastructure

The infrastructure that makes all this possible (in a thread-safe way) is quite simple and made up of two parts, the DomainEvent that we saw being used above, and the DomainEventRegistrationRemover which handles the disposing:

   1:  using System;

   2:  using System.Collections.Generic;

   3:   

   4:  namespace DomainEventInfrastructure

   5:  {

   6:      public class DomainEvent<E> 

   7:      {

   8:          [ThreadStatic] 

   9:          private static List<Action<E>> _actions; 

  10:   

  11:          protected List<Action<E>> actions 

  12:          {

  13:              get { 

  14:                  if (_actions == null) 

  15:                      _actions = new List<Action<E>>(); 

  16:   

  17:                  return _actions; 

  18:              }

  19:          }

  20:   

  21:          public IDisposable Register(Action<E> callback) 

  22:          {

  23:              actions.Add(callback);

  24:              return new DomainEventRegistrationRemover(delegate

  25:                  {

  26:                      actions.Remove(callback);

  27:                  }

  28:              ); 

  29:          }

  30:   

  31:          public void Raise(E args) 

  32:          {

  33:              foreach (Action<E> action in actions) 

  34:                  action.Invoke(args);

  35:          }

  36:      }

  37:  }

  38:   

Note that the invocation list of the domain event is thread static, meaning that each thread gets its own copy – even though they’re all working with the same instance of the domain event.

Here’s the DomainEventRegistrationRemover – even simpler:

   1:  using System;

   2:   

   3:  namespace DomainEventInfrastructure

   4:  {

   5:      public class DomainEventRegistrationRemover : IDisposable 

   6:      {

   7:          private readonly Action CallOnDispose;

   8:   

   9:          public DomainEventRegistrationRemover(Action ToCall) 

  10:          {

  11:              this.CallOnDispose = ToCall; 

  12:          }

  13:   

  14:          public void Dispose() 

  15:          {

  16:              this.CallOnDispose.DynamicInvoke();

  17:          }

  18:      }

  19:  }

For your convenience, I’ve made these available for download here.

I also want to add that if you haven’t looked at the comments on the original post – there’s some really good stuff there (36 comments so far). Take a look.

Most people getting started with DDD and the Domain Model pattern get stuck on this. For a while I tried answering this on the discussion groups, but here we have a nice example that I can point to next time.

The underlying problem I’ve noticed over the past few years is that developers are still thinking in terms of querying when they need more data. When moving to the Domain Model pattern, you have to “simply” represent the domain concepts in code – in other words, see things you aren’t used to seeing. I’ll highlight that part in the question below so that you can see where I’m going to go with this in my answer:

I have an instance where I believe I need access to a service or repository from my entity to evaluate a business rule but I’m using NHibernate for persistence so I don’t have a real good way to inject services into my entity. Can I get some viewpoints on just passing the services to my entity vs. using a facade?

Let me explain my problem to provide more context to the problem.

The core domain revolves around renting video games. I am working on a new feature to allow customers to trade in old video games. Customers can trade in multiple games at a time so we have a TradeInCart entity that works similar to most shopping carts that everybody is familiar with. However there are several rules that limit the items that can be placed into the TradeInCart. The core rules are:

1. Only 3 games of the same title can be added to the cart.
2. The total number of items in the cart cannot exceed 10.
3. No games can be added to the cart that the customer had previously reported lost with regards to their rental membership.
    a. If an attempt is made to add a previously reported lost game, then we need to log a BadQueueStatusAddAttempt to the persistence store.

So the first 2 rules are easily handled internally by the cart through an Add operation. Sample cart interface is below.

   1:  class TradeInCart{

   2:      Account Account{get;}

   3:      LineItem Add(Game game);

   4:      ValidationResult CanAdd(Game game);

   5:      IList<LineItems> LineItems{get;}

   6:  }

However the #3 rule is much more complicated and can’t be handled internally by the cart, so I have to depend on external services. Splitting up the validation logic for a cart add operation doesn’t seem very appealing to me at all. So I have the option of passing in a repository to get the previously reported lost games and a service to log bad attempts. This makes my cart interface ugly real quick.

   1:  class TradeInCart{

   2:      Account Account{get;}

   3:      LineItem Add(

   4:          Game game, 

   5:          IRepository<QueueHistory> repository, 

   6:          LoggingService service);

   7:   

   8:      ValidationResult CanAdd(

   9:          Game game, 

  10:          IRepository<QueueHistory> repository, 

  11:          LoggingService service);

  12:   

  13:      IList<LineItems> LineItems{get;}

  14:  }

The alternative option is to have a TradeInCartFacade that handles the validations and adding the items to the cart. The façade can have the repository and services injected though DI which is nice, but the big negative is that the cart ends up totally anemic.

Any thought on this would be greatly appreciated.

Thanks,
Jesse

As I highlighted above, the thing that will help you with your business rules is to introduce the Customer object (that you probably already have) with the property GamesReportedLost (an IList<Game>). Your TradeInCart would have a reference to the Customer object and could then check the rule in the Add method.

Before I go into the code, it looks like your Account object might be used the same way, but your description of the domain doesn’t mention accounts, so I’m going to assume that that’s unrelated for now:

   1:  public class Customer{

   2:   

   3:      /* other properties and methods */

   4:   

   5:      private IList<Game> gamesReportedLost;

   6:      public virtual IList<Game> GamesReportedLost 

   7:      { 

   8:          get

   9:          {

  10:              return gamesReportedLost;

  11:          }

  12:          set

  13:          {

  14:              gamesReportedLost = value;

  15:          }

  16:      }

  17:  }

Keep in mind that the GamesReportedLost is a persistent property of Customer. Every time a customer reports a game lost, this list needs to be kept up to date. Here’s the TradeInCart now:

   1:  public class TradeInCart

   2:  {

   3:      /* other properties and methods */

   4:   

   5:      private Customer customer;

   6:      public virtual Customer Customer

   7:      { 

   8:          get { return customer; }

   9:          set { customer = value; }

  10:      }

  11:   

  12:      private IList<LineItem> lineItems;

  13:      public virtual IList<LineItem> LineItems

  14:      {

  15:          get { return lineItems; }

  16:          set { lineItems = value; }

  17:      }

  18:   

  19:      public void Add(Game game)

  20:      {

  21:          if (lineItems.Count >= CONSTANTS.MaxItemsPerCart)

  22:          {

  23:              FailureEvents.RaiseCartIsFullEvent();

  24:              return;

  25:          }

  26:   

  27:          if (NumberOfGameAlreadyInCart(game) >=

  28:              CONSTANTS.MaxNumberOfSameGamePerCart)

  29:          {

  30:              FailureEvents

  31:                .RaiseMaxNumberOfSameGamePerCartReachedEvent();

  32:              return;

  33:          }

  34:   

  35:          if (customer.GamesReportedLost.Contains(game))

  36:              FailureEvents.RaiseGameReportedLostEvent();

  37:          else

  38:              this.lineItems.Add(new LineItem(game));

  39:      }

  40:   

  41:      private int NumberOfGameAlreadyInCart(Game game)

  42:      {

  43:          int result = 0;

  44:   

  45:          foreach(LineItem li in this.lineItems)

  46:              if (li.Game == game)

  47:                  result++;

  48:   

  49:          return result;

  50:      }

  51:  }

  52:   

  53:  public static class FailureEvents

  54:  {

  55:      public static event EventHandler GameReportedLost;

  56:      public static void RaiseGameReportedLostEvent()

  57:      {

  58:           if (GameReportedLost != null)

  59:               GameReportedLost(null, null);

  60:      }

  61:   

  62:      public static event EventHandler CartIsFull;

  63:      public static void RaiseCartIsFullEvent()

  64:      {

  65:           if (CartIsFull != null)

  66:               CartIsFull(null, null);

  67:      }

  68:   

  69:      public static event EventHandler MaxNumberOfSameGamePerCartReached;

  70:      public static void RaiseMaxNumberOfSameGamePerCartReachedEvent()

  71:      {

  72:           if (MaxNumberOfSameGamePerCartReached != null)

  73:               MaxNumberOfSameGamePerCartReached(null, null);

  74:      }

  75:  }

Your service layer class that calls the Add method of TradeInCart would first subscribe to the relevant events in FailureEvents. If one of those events is raised, it would do the necessary logging, external system calls, etc.

As you can see, the API of TradeInCart doesn’t need to make use of any external repositories, nor do you need to inject any other external dependencies in.

One thing I didn’t do in the above code to keep it “short” is to define the relevant custom EventArgs for bubbling up the information as to which game was reported lost or already have 3 of those in the cart. That is something that definitely should be done so that the service layer can pass this information back to the client.

Here’s a look at Service Layer code:

   1:  public class AddGameToCartMessageHandler :

   2:      BaseMessageHandler<AddGameToCartMessage>

   3:  {

   4:      public override void Handle(AddGameToCartMessage m)

   5:      {

   6:          using (ISession session = SessionFactory.OpenSession())

   7:          using (ITransaction tx = session.BeginTransaction())

   8:          {

   9:              TradeInCart cart = session.Get<TradeInCart>(m.CartId);

  10:              Game g = session.Get<Game>(m.GameId);

  11:   

  12:              Domain.FailureEvents.GameReportedLost +=

  13:                gameReportedLost;

  14:              Domain.FailureEvents.CartIsFull +=

  15:                cartIsFull;

  16:              Domain.FailureEvents.MaxNumberOfSameGamePerCartReached +=

  17:                maxNumberOfSameGamePerCartReached;

  18:   

  19:              cart.Add(g);

  20:   

  21:              Domain.FailureEvents.GameReportedLost -=

  22:                gameReportedLost;

  23:              Domain.FailureEvents.CartIsFull -=

  24:                cartIsFull;

  25:              Domain.FailureEvents.MaxNumberOfSameGamePerCartReached -=

  26:                maxNumberOfSameGamePerCartReached;

  27:   

  28:              tx.Commit();

  29:          }

  30:      }

  31:   

  32:      private EventHandler gameReportedLost = delegate { 

  33:            Bus.Return((int)ErrorCodes.GameReportedLost);

  34:          };

  35:   

  36:      private EventHandler cartIsFull = delegate { 

  37:            Bus.Return((int)ErrorCodes.CartIsFull);

  38:          };

  39:   

  40:      private EventHandler maxNumberOfSameGamePerCartReached = delegate { 

  41:            Bus.Return((int)ErrorCodes.MaxNumberOfSameGamePerCartReached);

  42:          };

  43:      }

  44:  }

It’s important to remember to clean up your event subscriptions so that your Service Layer objects get garbage collected. This is one of the primary causes of memory leaks when using static events in your Domain Model. I’m hoping to find ways to use lambdas to decrease this repetitive coding pattern. You might be thinking to yourself that non-static events on your Domain Model objects would be easier, since those objects would get collected, freeing up the service layer objects for collection as well. There’s just on small problem:

The problem is that if an event is raised by a child (or grandchild object), the service layer object may not even know that that grandchild was involved and, as such, would not have subscribed to that event. The only way the service layer could work was by knowing how the Domain Model worked internally – in essence, breaking encapsulation.

If you’re thinking that using exceptions would be better, you’d be right in thinking that that won’t break encapsulation, and that you wouldn’t need all that subscribe/unsubscribe code in the service layer. The only problem is that the Domain Model needs to know that the service layer had a default catch clause so that it wouldn’t blow up. Otherwise, the service layer (or WCF, or nServiceBus) may end up flagging that message as a poison message (Read more about poison messages). You’d also have to be extremely careful about in which environments you used your Domain Model – in other words, your reuse is shot.

Conclusion

I never said it would be easy

However, the solution is simple (not complex). The same patterns occur over and over. The design is consistent. By focusing on the dependencies we now have a domain model that is reusable across many environments (server, client, sql clr, silverlight). The domain model is also testable without resorting to any fancy mock objects.

One closing comment – while I do my best to write code that is consistent with production quality environments, this code is more about demonstrating design principles. As such, I focus more on the self-documenting aspects of the code and have elided many production concerns.

Do you have a better solution?

Something that I haven’t considered?

Do me a favour – leave me a comment. Tell me what you think.

For instance, in an HR system, the process of interviewing candidates – wouldn’t you just insert, update, and delete these Appointment objects?

If I were to put on my domain-driven hat, I would describe those requirements differently – interview appointments have a lifecycle: proposed, accepted, cancelled, etc. It seems that only a user of the role HR Interviewer should be able to make appointments for themselves, so the service layer code would probably look something like this:

using (ISession session = SessionFactory.OpenSession())
using (ITransaction tx = session.BeginTransaction())
{
    ICandidateInterviewer interviewer = session.Get<ICandidateInterviewer>(message.InterviewerId);
    ICandidate candidate = session.Get<ICandidate>(message.CandidateId);

    interviewer.ScheduleInterviewWith(candidate).At(message.RequestedTime);
    tx.Commit();
}

The “ScheduleInterviewWith” method accepts an ICandidate and returns an IAppointment. IAppointment has a method “At” which accepts a DateTime parameter and returns void – just changes the data of the appointment. The state of the appointment at creation time would probably be proposed. The appointment object would probably be added to the list of appointments for that interviewer – that’s what will cause it to be persisted automatically.

Later, when the candidate accepts the meeting, we could have the following method on ICandidate – void Accept(IAppointment); that would obviously check that the candidate is the right person for that interview, the appointment’s current state (not cancelled), etc – finally updating its state. What part of this looks like create, update, delete? If that’s what your service layer to domain interaction looks like, do you now know what your messages will be looking like?CRUD seems to be what most of us are familiar with. Moving to domain-driven thinking takes time and practice, but is well worth it. Contrast this with a more traditional O/R mapping solution:

using (ISession session = SessionFactory.OpenSession())
using (ITransaction tx = session.BeginTransaction())
{
    ICandidateInterviewer interviewer = session.Get<ICandidateInterviewer>(message.InterviewerId);
    ICandidate candidate = session.Get<ICandidate>(message.CandidateId); 

    Appointment a = new Appointment(); 

    a.Interviewer = interviewer;
    interviewer.Appointments.Add(a); 

    a.Candidate = candidate;
    candidate.Appointments.Add(a); 

    a.Time = message.RequestedTime; 

    session.Save(a);  

    tx.Commit();
} 

As you can see, we’ve got simpler, more expressive, and more testable code when employing the domain model pattern, than using “just” O/R mapping. I’m not saying that the domain model pattern doesn’t need O/R mapping in the background for it to work. But that’s just it – the persistence gunk needs to be in the background and the business logic needs to be encapsulated.

So, while I’ll agree with Dave that the Domain Model is more lifestyle than pattern, I would argue against these conclusions:

If this post had a point, it’s only to share the idea that Domain Model is a big, big thing. It’s probably overkill in a lot of cases where you have simple applications that have very simple purposes.

As you just saw in the example above, there is no “overkill” to be seen. The domain model in the example wasn’t “a big, big thing”.

The domain model. Use it.

Why not have a better lifestyle?  

Rishi asks:

Hi Udi,
First of all, thanks for all the posts and info you share, it is very insightful compared to loads n’ loads of marketing bull and vendor whitepapers. Ok, I have two questions for you.

1. I want to create a SOA-based LOB application/platform and I generally understand the ‘tenets of services’ and reasons for the same. However, as you may well know, there is a lot of interdependency between business constructs (such as a customer with an order, or a delivery with a product construct). Now, should we share these constructs within a tightly-coupled and domain-based “system” which exposes a number of services to the outside world and use the constructs directly inside the so-called “system” boundary. Or on the opposite spectrum have a number of autonomous and independent services that expose, own, and share certain business constructs or at least part of the data that represents them as a whole. For example, an order service will need to interact with a customer construct, which primarily/essentially is (or should be?) owned by a customer profile service – in this context, with clear, direct, and immediate inter-dependency what is preferable? Where do we draw the enclosing line?

2. In a line of business application, reporting and shaping data are a given necessity. Now, with autonomous and independent services which define business constructs in their contextual ways, how do we practically shape, combine, and filter data across various services? We certainly can’t do joins over multiple services in a practical way? And as some suggest, if we are to maintain duplicate or master data elsewhere, it just seems very messy to me – just consider having 3 versions of an order services, with 2 versions of support services, and ‘n’ number of other services to comb data from. Further, for reporting and also analytical purposes we really need to have business data structured in a well-defined manner, which for all purposes needs to be the “single version of the truth”. I can’t see granular services, with all its tenets, sitting nicely with such other requirements of the business – and yet I am not even asking them to be real-time. How do we meet such business requirements in your view with SOA?

Hope the above makes sense!

Cheers,
Rishi

PS: I use the word business construct purposefully, and it does not directly attribute to a well-defined programmable entity (in object-oriented way, that is).

Download via the Dr. Dobb’s site.

Or download directly here.

Additional References

• Ask Udi Podcast #000–Does SOA mean the end of OO?
• Ask Udi Podcast #009–Master Data Management and SOA
• Ask Udi Podcast #016–How does Extract, Transform, Load fit with SOA?

Want more?

Check out the “Ask Udi” archives.

Got a question?

Send Udi your question to answer on the show.

Ayende and I had an email conversation that started with me asking what would happen if I added an Order to a Customer’s “Orders” collection, when that collection was lazy loaded. My question was whether the addition of an element would result in NHibernate hitting the database to fill that collection. His answer was a simple “yes”. In the case where a customer can have many (millions) of Orders, that’s just not a feasible solution. The technical solution was simple – just define the Orders collection on the Customer as “inverse=true”, and then to save a new Order, just write:

Although it works, it’s not “DDD compliant”

In Ayende’s post Architecting for Performance he quoted a part of our email conversation. The conclusion I reached was that in order to design performant domain models, you need to know the kinds of data volumes you’re dealing with. It affects both internals and the API of the model – when can you assume cascade, and when not. It’s important to make these kinds of things explicit in the Domain Model’s API.

How do you make “transparent persistence” explicit?

The problem occurs around “transparent persistence”. If we were to assume that the Customer object added the Order object to its Orders collection, then we wouldn’t have to explicitly save orders it creates, so we would write service layer code like this:

On the other hand, if we designed our Domain Model around the million orders constraint, we would need to explicitly save the order, so we would write service layer code like this:

But the question remains, how do we communicate these guidelines to service layer developers from the Domain Model? There are a number of ways, but it’s important to decide on one and use it consistently. Performance and correctness require it.

Solution 1: Explicitness via Return Type

The first way is a little subtle, but you can do it with the return type of the “CreateOrder” method call. In the case where the Domain Model wishes to communicate that it handles transparent persistence by itself, have the method return “void”. Where the Domain Model wishes to communicate that it will not handle transparent persistence, have the method return the Order object created.

Another way to communicate the fact that an Order has been created that needs to be saved is with events. There are two sub-ways to do so:

Solution 2: Explicitness via Events on Domain Objects

The first is to just define the event on the customer object and have the service layer subscribe to it. It’s pretty clear that when the service layer receives a “OrderCreatedThatRequiresSaving” event, it should save the order passed in the event arguments.

The second realizes that the call to the customer object may come from some other domain object and that the service layer doesn’t necessarily know what can happen as the result of calling some method on the aggregate root. The change of state as the result of that method call may permeate the entire object graph. If each object in the graph raises its own events, its calling object will have to propagate that event to its parent – resulting in defining the same events in multiple places, and each object being aware of all things possible with its great-grandchild objects. That is clearly bad.

What [ThreadStatic] is for

So, the solution is to use thread-static events.

[Sidebar] Thread-static events are just static events defined on a static class, where each event has the ThreadStaticAttribute applied to it. This attribute is important for server-side scenarios where multiple threads will be running through the Domain Model at the same time. The easiest thread-safe way to use static data is to apply the ThreadStaticAttribute.

Solution 3: Explicitness via Static Events

Each object raises the appropriate static event according to its logic. In our example, Customer would call:

And the service layer would write:

The advantage of this solution is that it requires minimal knowledge of the Domain Model for the Service Layer to correctly work with it. It also communicates that anything that doesn’t raise an event will be persisted transparently behind the appropriate root object.

Statics and Testability

I know that many of you are wondering if I am really advocating the use of statics. The problem with most static classes is that they hurt testability because they are difficult to mock out. Often statics are used as Facades to hide some technological implementation detail. In this case, the static class is an inherent part of the Domain Model and does not serve as a Facade for anything.

When it comes to testing the Domain Model, we don’t have to mock anything out since the Domain Model is independent of all other concerns. This leaves us with unit testing at the single Domain Class level, which is pretty useless unless we’re TDD-ing the design of the Domain Model, in which case we’ll still be fiddling around with a bunch of classes at a time. Domain Models are best tested using State-Based Testing; get the objects into a given state, call a method on one of them, assert the resulting state. The static events don’t impede that kind of testing at all.

What if we used Injection instead of Statics?

Also, you’ll find that each Service Layer class will need to subscribe to all the Domain Model’s events, something that is easily handled by a base class. I will state that I have tried doing this without a static class, and injecting that singleton object into the Service Layer classes, and in that setter having them subscribe to its events. This was also pulled into a base class. The main difference was that the Dependency Injection solution required injecting that object into Domain Objects as well. Personally, I’m against injection for domain objects. So all in all, the static solution comes with less overhead than that based on injection.

Summary

In summary, beyond the “technical basics” of being aware of your data volumes and designing your Domain Model to handle each use case performantly, I’ve found these techniques useful for designing its API as well as communicating my intent around persistence transparency. So give it a try. I’d be grateful to hear your thoughts on the matter as well as what else you’ve found that works.

Related posts:

• Fetching Strategy Design – showing how to separate the concern of eager loading from both your Domain Model and your Service Layer.
• Better Domain-Driven Design Implementation – showing the basics of how valuable interfaces between your Domain Model and the Service Layer can be.
• Lazy Loading, and how messaging fixes everything again – describing the advantage of O/R mapping your message classes as well.
• Query Objects vs Methods on a Repository – discussing the scalability (in terms of number of developers and queries) of Query Objects.

I love you, Oren.

I know that the ADO.NET Entity Framework guys are open to this as well, but I’m pretty sure that the “Entity Model” thinking will hold them back. You just can’t divorce data and behavior – not when employing state machines or decorators.

I’m sold.

The first is that of keeping Service Layer classes independent of Domain Model classes. The reason this is desirable is that the two families change on independent axis. Service Layer classes are affected by changes to the service’s external interface, as well as the interfaces of other services it depends on. Domain Model classes change to support changing business rules internal to the service. The solution is quite simply to introduce a set of interfaces between the two.

The second is tied to performance. When retrieving data from the database, we’d like to cross the wire only once bringing with us all the data we need in order to perform the work required. Lazy loading helps us in one way while hurting us in another. For connected objects that we don’t need when retrieving our target object, lazy loading prevents them from being loaded. However, for connected objects that we do need, lazy loading will cause us to return to the database to retrieve each of those objects in turn (sets of the same kind of object are still one DB call). If those objects need to be traversed as well in order to retrieve other objects, we can see that one simple request can cause many (MANY!) calls to the DB. These problems of latency and throughput are solved by eagerly (in one DB call) fetching and loading all the objects we need.

Here’s the package diagram for the solution so that we’ll have a reference for the following discussion.

Now, the class that is best suited to issue this call to eagerly load all objects is the service layer class, since it is aware of what specific use case we’re in. However, the service layer class does not necessarily know exactly what classes will be used in the domain to handle that request. Obviously, this set of classes may change as the domain model and the database schema change. We can therefore say that is not the service layer class’ responsibility to handle the definition of which classes need to be loaded. Only the Domain Model has that knowledge. So we need some way to pass the knowledge of the request type into the Domain Model.

In Object/Role Modeling terms, we represent that request type as a role. And roles are represented by interfaces. So we create an interface in the Domain Model which represents the request type. That interface will most likely contain only one method – the method which the service layer class will call.

After we have the first role, we can build other things around it, like fetching strategies. We can then define other classes who fullfil the role of “I’m his fetching strategy”. Those classes will expose a property defining the exact set of classes to load, when using NHibernate we use HQL.

Here’s the sequence diagram showing how this works.

One question that you might ask is what if there is more than one class that implements the same interface? How could the infrastructure know which class it should be loading? The answer is simple. You shouldn’t do that. Having two classes fulfilling the same role will get you in trouble even if you don’t use this design. The Single Responsibility Principle should be our guiding light.

In summary, achieving high performance is possible when using Domain Models and Object/Relational Mapping, but requires minimizing calls to the database. This design decreases coupling between all the cooperating parts of the solution without giving up the ability to optimize over a specific technology.

Download the full detailed design (in HTML format). I’ll be offering the edittable Enterprise Architect format shortly.

From some pointers about how to use (and not to use) these tools, see why object-relational mapping sucks.

Martin Fowler’s has this to say about the Domain Model Pattern:

At its worst business logic can be very complex. Rules and logic describe many different cases and slants of behavior, and it’s this complexity that objects were designed to work with. A Domain Model creates a web of interconnected objects, where each object represents some meaningful individual, whether as large as a corporation or as small as a single line on an order form.

In short, using Object-Oriented techniques to handle the complexity.

A more comprehensive discussion about what happens when it is not used can be found under the Anemic Domain Model Anti-Pattern:

The basic symptom of an Anemic Domain Model is that at first blush it looks like the real thing. There are objects, many named after the nouns in the domain space, and these objects are connected with the rich relationships and structure that true domain models have. The catch comes when you look at the behavior, and you realize that there is very little behavior on these objects. Indeed often these models come with design rules that say that you are not to put any domain logic in the the domain objects. Instead there are a set of service objects which capture all the domain logic. These services live on top of the domain model and use the domain model for data.

The fundamental horror of this anti-pattern is that it’s so contrary to the basic idea of object-oriented design; which is to combine data and process together. The anemic domain model is really just a procedural style design…

In terms of Domain-Driven Design, this pattern is also known as Domain Layer.

Domain Models do a lot for encapsulating Business Rules, thus making them amenable to automated testing. This hinges on keeping the Domain Model independent of things related to Data Access.

It is therefore almost required to use some kind of Object/Relational Mapping tool to make it possible to persist objects belonging to the domain model to databases and other kinds of storage.

The use of DataSets in .NET is often a sign of the Anemic Domain Model Anti-Pattern.

One thing to keep in mind when working on a domain model is that you probably won’t get it “right” the first time, and will have re-work the division of responsibility a couple of times. Techniques like Test-Driven Development help out immensely for that.

The answer is simple.

You don’t have to.

Or, if you think you do, you’re probably using them wrong.

An O/R mapper should NOT live in its own tier.

Object/Relational Mappers never stand alone. They are used to provide persistence for something else – either for the Domain Model Pattern or for the Active Record pattern.

In terms of scalability, again these patterns usually don’t stand by themselves, but rather are hosted by something else. When used on the client side, say in a smart client application, then scalability isn’t often considered. There are some kinds of smart clients where hitting the database on most user interactions will bring the system to its knees, but that’s again an issue of database scalability. The common solution is some kind of client-side caching.

Anyway, the two main parameters you need to look at for your common and high-load scenarios when using an O/R mapper are these:

• How many times do you hit the DB per business action.
• How many objects/records/rows/columns do you bring into memory per business action.

You should be looking at appropriate uses of Lazy Loading for both of them.

Finally, keep in mind that O/R mappers are only part of your solution. Measure and optimize wisely.

In a previous post I described the two common scenarios for fetching an object from the database. More importantly, I showed the importance of having a different fetching strategy in the case of retrieving data for the purposes of passing it to someone else, and in the case of going to update that same data. Ayende and others looked at the solution I described and wanted something simpler. So here it is.

When working in a tiered deployment, client code needs to talk to some “service” (and I use the term lightly) to get the data. That same service may also contain a rich domain model which handles the business logic around updating its data. In this case, the lazy loading behavior of the domain model will be such as to bring the highest performance to the business logic of updating the data. The question then becomes, how do we retrieve that same data with lazy-loading behavior that will yield high performance or is suitable for serializing and sending back to the client.

Were we to model the interaction between client and service using message-exchange patterns, and used a design that kept those messages (and their data structures) independent of any other implementation details (POJO/POCO/PONO style), we could just O/R map those classes too.

What this means is that the class GetAllCustomersMessageHandler would respond with a CustomersDataMessage that contained a list of CustomerInfo objects. The CustomerInfo class is separate from the Customer class found within the service’s domain model. However, this does not mean that the message handler cannot write the following line of code:

IList<CustomerInfo> customersToSerialize = mySession.GetAll<CustomerInfo>();

This is Message/Relational Mapping without going all the way to XML/Relational Mapping as Jesse suggest here (although he ignores the whole issue of implementing Domain Models or Active Records using an O/R Mapper).

What this solution enables us to do is to define different lazy-loading behaviors for the Customer and CustomerInfo classes. Other things that are nice about this solution is that it builds on all the existing design patterns already found in a message-based, domain-driven system without adding anything new. On the other hand, if you do require numerous lazy-loading behaviors for performance reasons, the more generic fetching strategy I described before is your best bet.

What design issues are better handled by option one (query objects) or option two (methods on a repository)?

Option 1:

No custom repository per persistence type. All calls are done on IDbConversation. Fetching objects with custom queries is done like so:

IList<T> IDbConversation.PerformQuery(IQuery<T> query);

and then specific classes implement IQuery<T>, for instance, GetCustomersWithOutstandingDebtForLastQuarter which implements IQuery<ICustomer>. This implementation is responsible for translating the query into the appropriate representation for the persistence framework – say a chain of ICriteria in terms of NHibernate.

This results in loose coupling between queries, such that changing the interface of one would not touch code used by another.

By putting all queries in the same parent namespace “Queries”, we get the nice intellisense support of typing “IList<ICustomer> customers = this.IDbConversation.PerformQuery(Queries.” and getting the list of available options.

Option 2: (the more common)

One custom repository per persistence type. The repository talks with IDbConversation. The repository exposes methods for custom queries.

IList<Customer> CustomerRepository.GetCustomersWithOutstandingDebtForLastQuarter();

The repository translates the query to the specific persistence framework.

This results in less moving parts. In order to find a specific query you just type “this.CustomerRepository.” and the list of available methods shows up with intellisense.

Since all code is in the same class, changing the implementation/interface of one query/method may cause unintended side effects.

–

As you can probably tell, I’m for option one. It also fits nicely with my fetching strategy design, which I’m going to post the detailed design for shortly.

What are your thoughts?

[Also posted on the Domain Driven Design group here.]