In which the author outlines the method used in Calidus to parse a set of tokens into a new type of statement.

Concrete
Creating a new statement in Calidus is simple. A lot of utilities, methods and classes are available to make creating a statement a breeze.

Creating the basic classes

The first thing to do is to make sure that all parts are in place. The statement class itself must be declared. This class is derived from the AccessModifierStatement because an indexer can have an access modifier, and the base AccessModifierStatement class provides a few methods to work with these access modifiers.

The basic code for the statement factory class is also needed. In order to make this parsing as easy as possible the factory is derived from the FluentStatementFactory class to gain access to statement expressions. These statement expressions provide a fluent interface to declare the requirements for a statement.

Since Calidus is test-driven, a set of tests are needed to indicate that the statement is parsed correctly. For a factory, define a base test class that derives from CalidusTestBase. This class provides a set of utility methods and classes such as a TokenCreator and a StatementCreator that can be used by Calidus tests.

The TDD aficionado’s will notice that this is technically not a valid test: an additional unit test should be created to validate the context checking separately. However, this test already checks that the context is called through the mock repository in the VerifyAll-method. An extra test provides no additional advantage here.

Next, define a series of tests to indicate what is needed, and in this case a single test will suffice. Some additional information is needed to make this test work, so the basic frame of the test class must be expanded to suit the requirements for mocking.

This test code defines a mock statement context that indicates that the list of tokens to be parsed by the factory was found inside a class. The token list to parse is also created here.

Making it work

The following code is fairly simple as there are only two requirements for an indexer statement. First of all, it is part of a class: it can only be defined where the parent of the statement is the scope of a class. Second, an indexer statement consists of the This-keyword followed by a square bracket open. Both requirements can be expressed in code.

Combining these two pieces of codes validates both the context and the tokens, and running the unit tests with this code now yields a nice green bar.

In which the author outlines the basics of Calidus, the most important concepts and classes and how to use them.

Concrete

Calidus is not a terribly complex application. There are no zillion classes to get to know, there are no hard words or hidden meanings and most things do exactly what they sound like. In order to take full advantage of Calidus and develop custom parts such as rules it is important to know some of the inner workings of Calidus. This part is intended for advanced users and is a must-read for developers.

Characters

Technically, the smallest part of Calidus is the character, provided by the builtin character class. The concept of a character is not explicitly present in Calidus because no rule validation is performed on characters, but since they are the base element on which a token is built they deserve an honorable mention.

Tokens

A token is the smallest usefull part of the Calidus model. A token can be described as a collection containing at least one character, grouped together in the builtin String class. A token is either:

• A single-character token, such as a SpaceToken or a TabToken
• A single string token, such as an IdentifierToken or a NameSpaceToken
• A multiple string token, such as a LineCommentToken

Calidus uses Coco/R to parse source code into tokens. This means that the list of tokens recognized by Calidus is almost exactly the same as the list of tokens recognized by Coco/R. There are some exceptions to this rule: whitespace is not normally part of the Coco/R parser’s returned token types and is therefore provided by an additional parser.

Tokens that cannot be parsed as a more specific token are GenericTokens.

Statements

A statement is a collection containing at least one token. What exactly constitutes a statement is somewhat determined by the C# language: in most cases the end of a statement is a semicolon. For if, for, while constructs and the likes the end of a statement is the closing round bracket ‘)’, and for attributes the end of a statement is the closing square bracket ‘]’.

The statement parser groups tokens together by splitting them at certain well-defined places, the most common example of this is when a semicolon was encountered. There are other ways to group statements, which include using brackets, newlines and other special token types.

Parsing token groups to see if they match a statement definition is a complex operation, and the definition of what constitutes a statement can differ greatly.  One thing that creates a lot of complexity is the amount of whitespace separating tokens, which may or may not be relevant depending on the context. To make token parsing easy Calidus provides a fluent interface that allows a declarative statement definition.

Statements that cannot be parsed as a more specific statement are GenericStatements.

Lines

Lines are probably the easiest elements in the Calidus model. A line is just a line: it is a collection of tokens that reside on the same line. Lines are the only elements that can have rules associated with them but do not have any native support for pluggable definitions and extensions: what constitutes a line can never change and is fixed by Calidus.

Blocks

Blocks are logical groupings of at least one statement. Blocks have very wide definitions: a series of using statements in a file are grouped into a block because they are related, but so are all elements in the source file since they compose the FileBlock.  The entire contents of a class constitutes a ClassBlock, and blocks are also the place where an if, while, for, do while, foreach… statement is present along with the code that is run as part of it.

Rules

Calidus is a source style validation tool, and the constraints placed on the source are coded into rules. Rules can be put on top of the following Calidus elements:

• Statements, based off of StatementRuleBase
• Lines, based off of LineRuleBase
• Blocks, based off of BlockRuleBase

Tokens do not have rules associated with them as a token itself cannot be invalid. For example, a line comment is parsed into a LineCommentToken, but validating this token must be done through the statement that contains this token which is the LineCommentStatement.

Calidus rules are automatically configured by the class reponsible for creating them, allowing a user to use a pre-built rule but apply some customization to it. A good example of this principle is the MemberNameMatchesPatternRule, where a class member’s name is validated against a regex pattern. The pattern itself has a default setting, which can be adjusted to meet the developers needs.  This is unlike Microsoft’s StyleCop tool, which has several rules used to validate member names, each of which must be enabled or disabled and might not even meet the requirements when a naming pattern is used that is not built into the application. Rule configuration can be done through the main Calidus GUI.

7. Release early. Release often. And listen to your customers.

- Eric Raymond

For some time now I have been working on a project. It originally started out as a little tool I wanted to use for myself, but then decided that it might be worth to publish the project. Ever since the first parts were ready I’ve had several moments where I thought ‘Hey, just a little more and I can publish’. But I never did.

The reason for this is simple: every time you round up a feature there is always one more to add, one more thing to refactor, one more part to clean up. If you are ever going to start a project with the intention of making it public – open source or not – you might as well publish it now, because you’ll always be just one step away.

I am therefore making a promise: I will take two weeks to wrap up the features I am now working on (there are currently two left). I will publish the project by october 31st.

If I don’t, I’m buying you all a beer.

Ubiquitous Language is the term Eric Evans uses in Domain Driven Design for the practice of building up a common, rigorous language between developers and users. This language should be based on the Domain Model used in the software – hence the need for it to be rigorous, since software doesn’t cope well with ambiguity.
– Martin Fowler

Abstract

In which the author outlines the basics of the ‘Ledger Pattern’, an addition to the ubiquitous language and domain model to help facilitate a more natural approach to DDD and OO. It is specifically designed to deal with issues of validation and object creation that occur during object instantiation.

Concrete

Some things are obvious.  Some things are very obvious. And some things are so obvious that you actually need to take a step back in order to see them.  Udi Dahan helped me take that step back some time ago with his article ‘Don’t create aggregate roots‘.  While I agree with him on most of what he details in his post, I feel that something is missing.

What Udi points out is that we should never create instances of domain objects from the service layer (or command handler layer, whatever the layer is that coördinates calls to domain objects). Instead, it is the responsibility of an aggregate root to create a new entity that belongs to his aggregate.  In some cases, this is obvious:

public class Order
{
  public void AddOrderLine(OrderLine line)
  {
    orderLines.Add(line);
  }

  public void AddOrderLine(Product product, int quantity)
  {
    orderLines.Add(new OrderLine(product, quantity));
  }
}

The latter method is actually the better: it is very easy to perform validation on the parameters passed before the orderline object is constructed.  This is closely linked to something I blogged on before: domain object validation is done on a context basis.

And even if you believe that validation can be done, consider the example where we create a customer

public void Handle(CreateCustomerCommand cmd)
{
  ICustomerRepository repo = RepositoryFactory.Get();
  Customer customer = new Customer(cmd.FirstName, cmd.LastName);
  repo.Save(customer);
}

Where is the validation code now? Is it in the constructor? If so, what if we need different validation logic? What if our application goes from being an application used in a store to a web application? Now a customer comes through your website and you need to ensure that an email-address is supplied. We have to face facts: this solution is not adequate.

What we need is a domain concept that fits with the ‘this object can add customers’. So we use our common sense: in the store, the Employee-object can add a user. But who adds employees? Well, that would be the store owner. But where does he come from?

Back up a minute. In the past few sentences I’ve introduced a whole slew of new terms into the ubiquitous language. All of these need to be modeled, coded, tested and used. And what have we really achieved? Nothing much. No matter how far up the chain you push things, at some point you will run into a simple truth: you need an object that is not created and stored in the normal run of the system but that has been present from the start. Therefore I propose the following guideline:

For every aggregate root that is not the entity of any other aggregate root that can act as its creator, define an artificial aggregate root.

I call this artificial root a ledger, because it performs a function similar to an  order or purchase ledger.  Our customers are prime candidates for this: unless the ubiquitous language explicitly calls for some other object to create customers our CustomerLedger takes care of creating and deleting customers.  Note that all these ledgers to is provide a place to create and delete instances, updates are still processed by the actual domain objects.

Ledgers are also a prime place for validation: if a customer must have a first and last name, the ledger validates this. If our customers are now registering through the website the ledger can be extended to handle the adding of customers with the associated required validation of email addresses.

The odd thing about legders is that they are aggregate roots (and therefore entities) that have no identity*. All instances of a ledger class are equal to each other (disregarding lazy-loading and the likes) because they always contain the same data.

Here is a code example detailing what a ledger looks like.  This uses my implementation of the Notification Pattern to let the repository check if the object is in a valid state and to allow it to report this to the presentation layer.

public class CustomerLedger
{
  private IList errorList;

  public CustomerLedger()
  {
    errorList = new List();
  }

  public IList Customers { get; set; }

  public ICommandResult AddCustomer(String firstName, String lastName)
  {
    Validate.IsNotNullOrEmpty(firstName, "First name null or empty", errorList);
    Validate.IsNotNullOrEmpty(lastName, "Last name null or empty", errorList);

    if(errorList.Count == 0)
      Customers.Add(new Customer(firstName, lastName);

    return new CommandResult(errorList);
  }
}

This code is seemingly not very different from regular aggregate root code, and rightly so!  The only actual difference is the way the object is treated from the repository.

public interface ICustomerLedgerRepository
{
  CustomerLedger Get();
  ICommandResult Save(CustomerLedger ledger);
}

No id’s, no fancy lookups: there is no difference between the instances*.

Conclusion

The ledger concept is quite confusing at first, and it is a certain risk to implement: it can be confusing to users, domain experts and programmers alike. To introduce the concept into the ubiquitous language is to soil this language with something that is inherently a technical concern, but at the same time a valid domain problem. Everything that enters your system has an origin, and you need to model this origin up to a certain point.If you talk in terms of roles rather than objects it is a lot easier to introduce: the concept of a ‘CustomerAdder’ makes sense: your system needs something that adds customers.

Technically, this can not be considered a design pattern. But I’m going to call it the ‘Ledger Pattern‘ anyway. It’s either that or calling it ‘the concept formerly known as the artifical aggregate root for aggregate roots that lack natural aggregate roots in the ubiquitous language’. Let’s see you type that ten times in a heated mailing list discussion.

* All my ledgers actually do have an identity to facilitate ORM mapping and retrieval. This means that every aggregate root that is managed by a ledger also has a foreign key that points to this ledger. My database contains a ledger-table which contains an id and the name of the legder.

The term “default constructor” refers to a constructor that is automatically generated in the absence of explicit constructors (and perhaps under other circumstances); this automatically provide constructor is usually a nullary constructor. In specification or discussion of some languages, “default constructor” may additionally refer to any constructor that may be called without arguments, either because it is a nullary constructor or because all of its parameters have default values.
– Wikipedia

Abstract

In which the author outlines why default constructors on domain objects are not a ‘code smell’ for NHibernate and are actually required in most situations.

Concrete

I remember when I first started working with (N)Hibernate. It seemed like  a great tool: no more writing SQL queries, no more writing mapping code, but there was that expletive requirement to have a default no-arguments constructor. So I made that private as to not allow the constructor to be abused, but it still seemed bad: the domain object needs to conform to what an infrastructure framework wants.  It is only now, years after my first encounter with NHibernate, that I see that having a default constructor is not a bad thing. If anything, default constructors on domain objects are good things.

Let’s look at the reason why we need constructors. The raison d’être for a constructor is to force code that news up an instance of a class to provide other objects that said class needs.  In the context of domain layer and domain objects we tend to think of this as ‘creating the object in a state that is valid’. But what is a valid state?  When talking with programmers, analysts or domain experts it’s very easy to define what is a valid state.  In a classical order system with customers valid state will probably include a customer having a first name, last name and valid address details.  But is this really such a big requirement that we have to validate this in the constructor?

Weather or not a domain object is valid is in some cases not up to the object itself, and this is especially true for new instances.  Fact of the matter is that the only thing that determines if a domain object is valid is context.  Why does a customer need a first name, last name and an address? Because we need to be able to ship orders to him.

Read that again. We need to ship orders to him. If we are not shipping orders we do not need to validate anything. This brings the concept of validation into a totally different area. We no longer need to think about validating domain objects after creation, we are now validating pre-conditions for object creation.  This validation is always external to the object being created, allowing you to use the same domain object for different use-cases, without the need to write, test and maintain a gazillion different constructors, or even worse – deal with constructors that have the same parameters but different validation requirements. (The question of where the actual validation occurs for certain domain objects – such as aggregate roots – is a matter I’l talk about in a different post.)

Conclusion

And that, ladies and gentlemen, is why I like default constructors. Because I really don’t care if my domain objects are valid or not. All I care about is that they are valid in the context I’m using them in. And validating that can be done with re-useable code, tried and tested through unittests and talks with domain experts. Full of DDD and OO goodness, just the way I like it.