Avoid coupling the sender of a request to its receiver by giving more than one object a chance to handle the request. Chain the receiving objects and pass the request along the chain until an object handles it. – Gang of Four

Variations of this pattern are the basis for Servlet Filters, IIS Modules and Handlers and several open source projects I’ve had the opportunity to work with including Sync4J, JAMES, Log4Net, Unity and yes, even Joomla. It’s an essential tool in the OO toolbox and key in transforming rigid procedural code into a composable Domain Specific Language.

I’ve blogged about this pattern before so what’s new this time?

1. The next filter in the chain is provided via a delegate parameter rather than a property
2. The project is hosted on github
3. There is a NuGet package for it

How does it work?

It’s pretty simple, there is just one interface to implement and it looks like this:

public interface IFilter<T, TOut>

{

    TOut Execute(T context, Func<T, TOut> executeNext);

}

Basically, you get an input to operate on and a value to return. The executeNext parameter is a delegate for the next filter in the chain. The filters are composed together in a chain which is referred to as a Pipeline in the Tamarack framework. This structure is the essence of the Chain of Responsibility pattern and it facilitates some pretty cool things:

• Modify the input before the next filter gets it
• Modify the output of the next filter before returning
• Short circuit out of the chain by not calling the executeNext delegate

Show me examples!

Consider a block of code to process a blog comment coming from a web-based rich text editor. There are probably several things you’ll want to do before letting the text into your database.

public int Submit(Post post)

{

    var pipeline = new Pipeline<Post, int>()

        .Add(new CanoncalizeHtml())

        .Add(new StripMaliciousTags())

        .Add(new RemoveJavascript())

        .Add(new RewriteProfanity())

        .Add(new GuardAgainstDoublePost())

        .Finally(p => repository.Save(p));

    var newId = pipeline.Execute(post);

    return newId;

}

What about dependency injection for complex filters? Take a look at this user login pipeline. Notice the generic syntax for adding filters by type. Those filters are built-up using the supplied implementation of System.IServiceProvider. My favorite is UnityServiceProvider.

public bool Login(string username, string password)

{

    var pipeline = new Pipeline<LoginContext, bool>(serviceProvider)

        .Add<WriteLoginAttemptToAuditLog>()

        .Add<LockoutOnConsecutiveFailures>()

        .Add<AuthenticateAgainstLocalStore>()

        .Add<AuthenticateAgainstLdap>()

        .Finally(c => false);

    return pipeline.Execute(new LoginContext(username, password));

}

Here’s another place you might see the chain of responsibility pattern. Calculating the spam score of a block of text:

public double CalculateSpamScore(string text)

{

    var pipeline = new Pipeline<string, double>()

        .Add<SpamCopBlacklistFilter>()

        .Add<PerspcriptionDrugFilter>()

        .Add<PornographyFilter>()

        .Finally(score => 0);

    return pipeline.Execute(text);

}

Prefer convention over configuration? Try this instead:

public double CalculateSpamScore(string text)

{

    var pipeline = new Pipeline<string, double>()

        .AddFiltersIn("Tamarack.Example.Pipeline.SpamScorer.Filters")

        .Finally(score => 0);

    return pipeline.Execute(text);

}

Let’s look at the IFilter interface in action. In the spam score calculator example, each filter looks for markers in the text and adds to the overall spam score by modifying the result of the next filter before returning.

public class PerspcriptionDrugFilter : IFilter<string, double>

{

    public double Execute(string text, Func<string, double> executeNext)

    {

        var score = executeNext(text);

        if (text.Contains("viagra"))

            score += .25;

        return score;

    }

}

In the login example, we look for the user in our local user store and if it exists we’ll short-circuit the chain and authenticate the request. Otherwise we’ll let the request continue to the next filter which looks for the user in an LDAP repository.

public class AuthenticateAgainstLocalStore : IFilter<LoginContext, bool>

{

    private readonly IUserRepository repository;

    public AuthenticateAgainstLocalStore(IUserRepository repository)

    {

        this.repository = repository;

    }

    public bool Execute(LoginContext context, Func<LoginContext, bool> executeNext)

    {

        var user = repository.FindByUsername(context.Username);

        if (user != null)

            return user.IsValid(context.Password);

        return executeNext(context);

    }

}

Why should I use it?

It’s pretty much my favorite animal. It’s like a lion and a tiger mixed… bred for its skills in magic. – Napoleon Dynamite

It’s simple and mildly opinionated in effort to guide you and your code into The Pit of Success. It’s easy to write single responsibility classes and use inversion of control and composition and convention over configuration and lots of other goodness. Try it out. Tell a friend.

public UserIndexViewModel GetIndexViewModel(int pageSize, int pageNumber) {
    var model = new UserIndexViewModel();

    var allUsers = Session.CreateCriteria<User>();

    model.Total = CriteriaTransformer
        .TransformToRowCount(allUsers)
        .UniqueResult<int>();

    model.Users = allUsers
        .SetFirstResult(pageSize * (pageNumber - 1) + 1)
        .SetMaxResults(pageSize)
        .AddOrder<User>(u => u.LastName, Order.Asc)
        .List<User>();

    return model;
}

There isn’t much going on here, but it could be better. I’m looking at the arguments pageSize and pageNumber. Notice how they both start with the prefix “page”. That’s a smell. The common prefix means the arguments are related, so let’s apply the Introduce Parameter Object refactoring and see what happens.

public class Page {
    private readonly int number;
    private readonly int size;

    public Page(int number, int size) {
        this.number = number;
        this.size = size;
    }

    public int Size {
        get { return size; }
    }

    public int Number {
        get { return number; }
    }

    public int FirstResult {
        get { return size * (number - 1) + 1; }
    }
}

What did we accomplish?

• Creating the parameter object gave us a place to put the logic of calculating the first result of the current page. This logic would otherwise be scattered around the application and even though it’s simple, it’s error prone.
• The logic of calculating the first result is testable.

[Test]
public void Should_calculate_first_result_of_current_page() {
    Assert.That(new Page(1, 20).FirstResult, Is.EqualTo(1));
    Assert.That(new Page(2, 20).FirstResult, Is.EqualTo(21));
    Assert.That(new Page(3, 20).FirstResult, Is.EqualTo(41));
}

It’s not rocket science, but it still deserves a test. Our other option is spinning up Cassini and clicking around to make sure we got it right. That’s just silly. A little piece of me dies each time I press F5 to run a manual test.

Anyway, there is this thing that happens with single responsibility classes. Because their purpose is crisp, it draws out robustness. In this case, I’m thinking about what we should we do if we get zero or a negative value for page number. I’m a fail fast kind of guy, so I’d probably go with a guard clause.

public Page(int number, int size) {
    GuardAgainstLessThanOne(number);
    ...
}

But you could silently correct it if that’s how you roll:

public int Number {
    get { return Math.Max(1, number); }
}

The point is that this is an obvious scenario to consider when looking at such a special purpose object. All too often though, bits of logic are mixed together like 32 kindergarteners sitting next to each other on a rug during a lesson. The room is one fart or tickle away from erupting into total kaos. It’s roughly half teaching and half crowd control, only without the rubber bullets and pepper spray. Not surprisingly, overcrowded classrooms don’t work that well and over-ambitous functions don’t work that well either. Each little bit of logic needs some one on one with you. Give it a chance to be all it can be by pulling it aside and getting to know it a little better. You might be surprised.

I recently saw this question on stackoverflow:

There were good points on both sides, but the majority of responses were from closet interface haters succumbing to the mob effect to say "me too". On the other side of the argument, many took cover behind regurgitated responses like interfaces are for mocking dependencies in unit tests and because people that write books say you should use them. So how is it that scores of professional software developers don’t understand or can’t communicate why and how to use the most fundamental of object-oriented language features? Perhaps there is a clue in the details of the original question:

Is there some hidden benefit of using an interface when you have 1 version of a class and no immediate need to create an interface?

The scattered and ineffectual responses are an unfortunate casualty of the ubiquitous poor online examples found on the Internet. No doubt you’ve seen something like this before:

public interface IVehicle {
    int NumberOfPassengers { get; }
}

public class Car : IVehicle {
    public int NumberOfPassengers { get { return 4; } }
}

public class Bus : IVehicle {
    public int NumberOfPassengers { get { return 20; } }
}

I can’t help but have visions of rich objects that model the physical world so well they put an end to wars and world hunger. You know, methods like Bark() on a Dog object. These examples aren’t wrong per se, but they usher the reader down a predictable and dead-end path. It’s like the horribly cliché nine dots puzzle in which the goal is to link all 9 dots using four straight lines or less, without lifting the pen.

Common sense suggests it can’t be done because we have subconsciously imposed a false restriction that the lines must be within the boundaries of the square (I won’t insult you with the hopelessly worn out catch phrase). The point I’m trying to make here is the examples out there unwittingly set us up for failure. In social science this is called framing. The human brain is an impressive problem solving machine, but we can be easily fooled by framing a problem in a way that our stereotypes and assumptions obscure the often obvious answer.

In the case of interfaces, the examples suggest the concrete implementations are mutually exclusive physical concepts like Car and Bus, or perhaps SqlUserStore and LdapUserStore. It’s an easy concept to latch on to, and it’s the bane of good object oriented design.

To think of a user store as a thing is a mistake. IUserStore defines a seam in which responsibility crosses a boundary. In an MVC application, it’s the seam between the controller’s routing responsibility and the model’s business logic. If you only have one implementation of IUserStore , then you’d better take another look because that’s a smell.

The place to start looking is within your one and only implementation. Where is the logic about sending a confirmation email or checking if the username is available? Chances are it ended up in the controller leaving your model anemic or it ended up in your model violating the single responsibility principle. Either way it’s a big fail sandwich.

Again, this is because of the false assumption that implementations are mutually exclusive as in the Car and Bus example. In other words, if I have a Car , then I don’t have a Bus. This is the wrong way to think of objects. Of course they can be mutually exclusive, but they are far more powerful when they are composable. Consider these implementations of IUserService:

• EmailConfirmationUserService
• ValidatingUserService
• SqlUserService
• CachingUserService

Each concern is orthogonal to each other concern and they are combined together to create the overall behavior of the system. The interface facilitates composition which is the key to high-quality, robust software. So the real problem isn’t that interfaces are overused, it’s that interfaces are squandered.

public class Product {
    public int Id { get; set; }

    [Required]
    public string Description { get; set; }

    [Required]
    [RegularExpression(@"^\$?\d+(\.(\d{2}))?$")]
    public decimal UnitPrice { get; set; }
}

Just for the record, this is a cool bit of code that was released to the community for backseat drivers like me to use and complain about. I’m really only bitter because I can’t use it. Let’s take a peek at the source code to see why:

/// <summary>
/// An implementation of IModelBinder which is designed to be a replacement
/// default model binder, adding the functionality of validation via the validation
/// attributes in System.ComponentModel.DataAnnotations from .NET 4.0.
/// </summary>
public class DataAnnotationsModelBinder : DefaultModelBinder {
    ...
}

The problem with this class is that it’s not just about validation. It’s more about binding with validation sprinkled in. The author even states this as a design goal with the comment “designed to be a replacement default model binder.” This is a violation of the Single Responsibility Principle and it’s the reason I can’t use it. The DefaultModelBinder does some basic reflection mapping of form elements to model properties. That’s cool, but what about a controller action that takes json, xml, or anything slightly more complicated than what the default binder can handle?

I’ll tell you what happens. You write a custom model binder which is pretty easy and happens to be a pretty rad extension point in the MVC framework. Consider this model binder that deserializes json:

public class JsonModelBinder<T> : IModelBinder {
    private string key;

    public JsonModelBinder(string requestKey) {
        this.key = requestKey;
    }

    public object BindModel(ControllerContext controllerContext, ...) {
        var json = controllerContext.HttpContext.Request[key];
        return new JsonSerializer().Deserialize<T>(json);
    }
}

That’s pretty cool, but now I’ve lost my validation! This my friend is the evil of inheritance and the epic fail of the DataAnnotationsModelBinder. So what’s wrong with inheritance, isn’t that what OOP is all about? The short answer is no (the long answer is also no.)

Human sacrifice, dogs and cats living together… mass hysteria! — Dr. Peter Venkman

Inheritance is pretty enticing especially coming from procedural-land and it often looks deceptively elegant. I mean all I need to do is add this one bit of functionality to another other class, right? Well, one of the problems is that inheritance is probably the worst form of coupling you can have. Your base class breaks encapsulation by exposing implementation details to subclasses in the form of protected members. This makes your system rigid and fragile.

The more tragic flaw however is the new subclass brings with it all the baggage and opinion of the inheritance chain. Why does a model that enforces validation attributes care how the model is constructed? The answer is it shouldn’t, and to add insult to injury, the better design is actually easier to implement. Listen closely and you may hear the wise whispers of our forefathers…

Use the decorator pattern.

Is this really going to solve all my problems? The short answer is yes. Let’s take a look:

public class BetterDataAnnotationsModelBinder : IModelBinder {
    private IModelBinder binder;

    public BetterDataAnnotationsModelBinder(IModelBinder binder) {
        this.binder = binder;
    }

    public object BindModel(ControllerContext controllerContext, ...) {
        var model = binder.BindModel(controllerContext, bindingContext);
        AddValidationErrorsToModelState(model, controllerContext);
        return model;
    }

    ...
}

Now all this class does is enforce validation and we can use whatever model binder we want to construct our object. Let’s wire this up in the Global.asax real quick:

var productModelBinder = new JsonModelBinder<Product>("product");

ModelBinders.Binders.Add(
    typeof(Product),
    new BetterDataAnnotationsModelBinder(productModelBinder));

This is cool for the following reasons:

1. We are not coupled to the DefaultModelBinder. This means we don’t know or care about the structure and implementation details of it so it’s free to change in the next version of ASP.NET MVC.
2. The code is simpler because it is only about validation.
3. The behavior is composable. This means we can add validation to any model binder (like our json model binder) and bolt on more responsibilities with a chain of decorators. How about converting DateTime fields to UTC or striping formatting characters from phone numbers?
4. It’s easy to test.

You can substitute a decorator for a subclass in most cases and in most cases it’s the right choice. You’re better off making the decorator your default choice and only settle for inheritance when you really need it.

…don’t be jealous that I’ve been chatting online with babes all day. Besides, we both know that I’m training to be a cage fighter. — Kip

The built-in model binder can handle the easy fields like FirstName, LastName, and Email, but it doesn’t know how to deal with the roles. This is where the custom model binder comes in:

public class UserModelBinder : IModelBinder {
    private readonly IModelBinder binder;

    public UserModelBinder(IModelBinder binder) {
        this.binder = binder;
    }

    public object BindModel(ControllerContext controllerContext, ...) {
        var user = (User)binder.BindModel(controllerContext, bindingContext);
        AddRoles(user, controllerContext);
        return user;
    }

    private static void AddRoles(User user, ControllerContext controllerContext) {
        foreach (var role in GetRoles(controllerContext)) {
            user.Add(role);
        }
    }

    private static IEnumerable<Role> GetRoles(ControllerContext controllerContext) {
        var roles = controllerContext.HttpContext.Request["roles"];
        if (roles == null) yield break;
        foreach (var roleId in roles.Split(',')) {
            yield return (Role)Convert.ToInt32(roleId);
        }
    }
}

And it gets wired-up in the Global.asax like this:

var defaultBinder = new DataAnnotationsModelBinder();
ModelBinders.Binders.DefaultBinder = defaultBinder;
ModelBinders.Binders.Add(typeof(User), new UserModelBinder(defaultBinder));

Because UserModelBinder is a decorator, it preserves the base functionality (like validation) of the default binder and only adds the part about mapping the roles. This is good stuff because it keeps construction of the model out of the controller. That’s the Single-Responsibility Principle in action.

Command Query Separation

The two functions AddRoles, and GetRoles are an example of command query separation (CQS). It would be easy to combine those two functions together and in fact that’s how it looked at first. So why bother separating them? Well it doesn’t really matter in this simple case, but it’s like how I tell my 3 year-old son to move his milk cup away from the edge of the table. I figure it’s a good habit that will prevent a few spills in the long run. The idea with CQS is there is a natural seam between finding objects and doing stuff with them. I buy that. I expect GetRoles to be more volatile than AddRoles or at least change for different reasons.

I made a few tweaks to a captcha library I found here and basically wrapped their CaptchaImage object in a service interface to use in my application. Pretty easy stuff, but I didn’t get it right the first time.

What’s wrong with this class? (hint: it’s highlighted in yellow)

public class HttpContextCacheCaptchaProvider : ICaptchaProvider
{
    private const string httpContextCacheKey = "4D795A45-8015-475C-A6C4-765B09EB9955";
    private ICaptchaImageFactory factory;
    private HttpContextBase context;

    public HttpContextCacheCaptchaProvider(ICaptchaImageFactory factory, HttpContextBase context)
    {
        this.factory = factory;
        this.context = context;
    }

    public void Render(Stream stream)
    {
        CaptchaImage captchaImage = factory.Create();

        context.Cache[httpContextCacheKey] = captchaImage.Text;

        using (Bitmap bitmap = captchaImage.RenderImage())
        {
            bitmap.Save(stream, ImageFormat.Jpeg);
        }
    }

    public bool Verify(string text)
    {
        string captchaText = (string)context.Cache[httpContextCacheKey];

        if (text == null || captchaText == null)
            return false;
        else
            return text.ToLower().Equals(captchaText.ToLower());
    }
}

Perhaps your nose can lead you in the right direction. The smell is hard to test, and it’s hard to test because it requires mocking the HttpContextBase. You might say “no problem, I can blast out a stub with Moq in no time” but you’re missing the real problem. That would be like taking aspirin for a brain tumor.

It’s not a tumor

The real problem is this class is violating the Single Responsibility Principle (SRP) by doing more than one thing. I don’t mean the two methods Render() and Verify(), those are a cohesive unit operating on the same data. The other thing is lifetime management. Look how simple the class gets when you invert control and take out the notion of lifetime management:

[Serializable]
public class LifetimeManagedCaptchaProvider : ICaptchaProvider
{
    private ICaptchaImageFactory factory;
    private string captchaText;

    public LifetimeManagedCaptchaProvider(ICaptchaImageFactory factory)
    {
        this.factory = factory;
    }

    public void Render(Stream stream)
    {
        CaptchaImage captchaImage = factory.Create();

        captchaText = captchaImage.Text;

        using (Bitmap bitmap = captchaImage.RenderImage())
        {
            bitmap.Save(stream, ImageFormat.Jpeg);
        }
    }

    public bool Verify(string text)
    {
        if (text == null || captchaText == null)
            return false;
        else
            return text.ToLower().Equals(captchaText.ToLower());
    }
}

Now this class is a breeze to test and all you have to do is register it like this:

Container.RegisterType<ICaptchaProvider, LifetimeManagedCaptchaProvider>(
    new HttpSessionStateLifetimeManager());

The moral of the story is let your IoC container do things it’s good at.