DaedTech

Stories about Software

By

Flyweight

Quick Information/Overview

Pattern Type Structural
Applicable Language/Framework Agnostic OOP
Pattern Source Gang of Four
Difficulty Easy

Image courtesy of dofactory

Up Front Definitions

  1. Client: Code that uses the flyweight implementation
  2. Concrete Flyweight: A class that actually implements the abstract class/interface flyweight.
  3. Extrinsic State: State that is not common to the flyweights and varies per instance.
  4. Flyweight: An interface that defines and exposes the extrinsic state.
  5. Flyweight Factory: Class used by clients to retrieve instances of the flyweights.
  6. Intrinsic State: State that is common across all flyweights of the same type.

The Problem

Most of these design patterns posts deal with compile-time problems brought about by painting oneself into a corner with design decisions. In other words, if you make certain missteps when designing a system, it becomes rigid and difficult to change in the future. Patterns such as the Factories, Composite, Decorator, etc., all address prevention of such missteps by isolating responsibilities and making change management simple. Today, the problem we’re going to look at is a runtime problem rather than a compile-time problem.

Let’s say that you’re asked to create a model that simulates the distribution of mail in the USA for a given day. You start by establishing some pretty reasonable business objects to represent the domain concepts in question: letters and postcards. Each of these things has certain properties you’re going to need to keep track of, such as dimensions and postage, so that you can report in aggregate on paper usage, revenues, etc. Here is your first crack at business objects:

public abstract class MailPiece
{
    public abstract decimal Postage { get; set; }
    public abstract decimal Width { get; set; }
    public abstract decimal Height { get; set; }
    public abstract decimal Thickness { get; set; }
 
    public int DestinationZip { get; set; }
}
public class Letter : MailPiece 
{
    public override decimal Postage { get; set; }
    public override decimal Width { get; set; }
    public override decimal Height { get; set; }
    public override decimal Thickness { get; set; }
 
    public Letter()
    {
        Postage = 0.46M;
        Width = 11.5M;
        Height = 6.125M;
        Thickness = 0.25M;
    }
}
public class Postcard : MailPiece
{
    public override decimal Postage { get; set; }
    public override decimal Width { get; set; }
    public override decimal Height { get; set; }
    public override decimal Thickness { get; set; }
 
    public Postcard()
    {
        Postage = 0.33M;
        Width = 6.0M;
        Height = 4.25M;
        Thickness = 0.016M;
    }
}

Alright, awesome. Now, according to the USPS, there are 563 million mail pieces processed in the USA each day (as of 2011). So, let’s just use that as our loop counter, and off we’ll go:

static void Main(string[] args)
{
    var pieces = new List<MailPiece>();
    for (long index = 0; index < 563000000; index++)
    {
        pieces.Add(new Letter() { DestinationZip = (int)(index % 100000) });
    }
 
    Console.ReadLine();
}

Satisfied, you fire up the program to make sure everything here is in good working order–although, really, why bother? I mean, what could possibly go wrong? The program chugs along for a bit, and it strikes you that it’s taking a while and your desktop is starting to crawl. You fire up the process manager and see this:

Danger, Will Robinson

Yikes! That’s… troubling. You start to wonder if maybe you should intervene and stop the program, but Visual Studio isn’t being very responsive and you can’t even seem to get it to hit a breakpoint. Just as you’re contemplating drastic action, Visual Studio mercifully puts an end to things:

OutOfMemory

You’re not very close to getting all of the records in, so you decide to divide the original 563 million by 24 in order to model the mail being processed on an hourly basis, but that’s really all the more granular that you can do. You fire up the program again to run with 23,458,333 and hit out of memory once again.

So, What to Do?

If you look at your creation of letters (and presumably later, postcards) you should notice that there’s a fair bit of waste here. For every letter you create, you’re creating four decimals that are exactly the same for every letter, which means that you’re storing four unnecessary decimals for all but one of the letters you create, which in turn means that you’re storing somewhere in the neighborhood of two billion unnecessary decimal instances in memory. Whoah.

Let’s try a different approach. What we really seem to want here is 23 and a half million zip codes and a single letter. So let’s start off simply by building a list of that many zip codes and seeing what happens:

static void Main(string[] args)
{
    var pieces = new List<MailPiece>();
    for (long index = 0; index < 23458333; index++)
    {
        pieces.Add(new Letter() { DestinationZip = (int)(index % 100000) });
    }
 
    Console.ReadLine();
}

Woohoo! That runs, and for the first time we have something that doesn’t crash. But what we’re really looking to do is cycle through all of those mail pieces, printing out their zip, postage, and dimensions. Let’s start off by cheating:

static void Main(string[] args)
{
    var zipCodes = new List<int>();
    var letter = new Letter();
    for (int index = 0; index < 23458333; index++)
    {
        zipCodes.Add(index % 100000);
        Console.Write(string.Format("Zip code is {0}, postage is {1} and height is {2}",
            zipCodes[index], letter.Postage, letter.Height));
    }
 
    Console.ReadLine();
}

That gets us what we want, but there’s a lot of ugliness. The client class has to know about the exact mechanics of the mail piece’s printing details, which is a no-no. It also has the responsibility for keeping track of the flyweight letter class. There are better candidates for both of these responsibilities. First of all, let’s move the mechanism for printing information into the mail piece class itself.

public abstract class MailPiece
{
    public abstract decimal Postage { get; set; }
    public abstract decimal Width { get; set; }
    public abstract decimal Height { get; set; }
    public abstract decimal Thickness { get; set; }
 
    public string GetStatistics(int zipCode)
    {
        return string.Format("Zip code is {0}, postage is {1} and height is {2}",
            zipCode, Postage, Height);
    }
}

Notice that we’ve removed the settable “DestinationZip” and added a method that prints piece statistics, given a zip code. That allows us to simplify the client code:

static void Main(string[] args)
{
    var zipCodes = new List<int>();
    var letter = new Letter();
    for (int index = 0; index < 23458333; index++)
    {
        zipCodes.Add(index % 100000);
        string pieceStatistics = letter.GetStatistics(zipCodes[index]);
        Console.Write(pieceStatistics);
    }
 
    Console.ReadLine();
}

Asking the letter object for its statistics definitely feels like a better approach. It’s nice to get that bit out of the client implementation, particularly because it will now work for postcards as well and any future mail pieces that we decide to implement. But we’re still worrying about instance management of the flyweights in the client class, which really doesn’t care about them. Let’s introduce a new class:

public class MailPieceFactory
{
    private readonly Dictionary<char, MailPiece> _mailPieces = new Dictionary<char,MailPiece>();
 
    public MailPiece GetPiece(char key)
    {
        if (!_mailPieces.ContainsKey(key))
            _mailPieces[key] = BuildPiece(key);
 
        return _mailPieces[key];            
    }
 
    private static MailPiece BuildPiece(char key)
    {
        switch (key)
        {
            case 'P': return new Postcard();
            default: return new Letter();
        }
    }
}

Here we have a public method called “GetPiece” to which we pass a key indicating what sort of piece we want. As far as client code goes, that’s all that matters. Under the hood, we’re managing the actual flyweights. If the dictionary doesn’t have key we’re interested in, we build a piece for that key. If it does, we simply return the flyweight from the hash. (Note that the scheme of indexing them by characters will scale, but isn’t really optimal at the moment–you could use an enumeration here, restrict the set of allowed keys with preconditions, or have a special default scheme.)

Let’s see what the client code looks like.

static void Main(string[] args)
{
    var factory = new MailPieceFactory();
    var zipCodes = new List<int>();
 
    for (int index = 0; index < 23458333; index++)
    {
        zipCodes.Add(index % 100000);
        var randomPiece = factory.GetPiece(GetRandomKey());
        string pieceStatistics = randomPiece.GetStatistics(zipCodes[index]);
        Console.Write(pieceStatistics);
    }
 
    Console.ReadLine();
}
 
private static char GetRandomKey()
{
    return new Random().Next() % 2 == 0 ? 'P' : 'L';
}

There. Now the client code doesn’t worry at all about keeping track of the flyweights or about how to format the statistics of the mail piece. It simply goes through a bunch of zip codes, creating random pieces for them, and printing out their details. (It could actually dispense with the list of zip codes, as implemented, but leaving them in at this point underscores the memory benefit of the flyweight pattern.)

There’s now some nice extensibility here as well. If we implemented flats or parcels, it’d be pretty easy to accommodate. You’d just add the appropriate class and then amend the factory, and you’d be off and running. When dealing with scales of this magnitude, memory management is always going to be a challenge, so using a pattern up front that reuses and consolidates common information will be a big help.

A More Official Explanation

According to dofactory, the purpose of the Flyweight pattern is:

Use sharing to support large numbers of fine-grained objects efficiently.

The Flyweight pattern requires that you take the objects whose information you want to share for scaling purposes and divide their state into two categories: intrinsic and extrinsic. Intrinsic state is the state that will be shared across all instances of the same type of object, and extrinsic state is the state that will be stored outside of the instance containing common information. The reason for this division is to allow as much commonality as possible to be stored in a single object. In a way, it is reminiscent of simple class inheritance where as much common functionality as possible is abstracted to the base class. The difference here is that a single instance stores common information and an external interest holds the differences.

To make the most of the pattern, flyweight creation and management is abstracted into one class (the factory), intrinsic state to another set of classes (the concrete flyweights), and extrinsic state management to a third class (the client). Separating these concerns allows the client to incur only the memory overhead of the part of an object that varies while still reaping all of the benefits of OOP and polymorphism. This is a powerful optimization.

Other Quick Examples

  1. The iconic example of the Flyweight pattern is to have flyweights represent characters in a word processing document, with the extrinsic state of position in the document.
  2. Another use is rendering in graphical applications with many similar shapes or patterns on the screen in configurable locations.
  3. It can also be used to represent some fungible commodity of which there are many in a video game, such as enemies, soldiers, scenery elements, etc.
  4. One of the more interesting and practical examples is string “interning” in C#

A Good Fit – When to Use

As the cost of memory and disk space continues to plummet, emphasis on this pattern is seeming to wane a bit. However, there will always be occasions in which resource management and optimization are crucial, and bottlenecks will always exist where even liberally purchased resources need to be used wisely. The flyweight pattern is a good fit any time you have redundant, common state in many objects that you’re creating. If you find yourself in this position, the pattern is really a no-brainer since it’s simple and costs very little to implement in terms of code complexity.

Square Peg, Round Hole – When Not to Use

This isn’t the kind of pattern where you’re likely to go out looking for excuses to try it out since it solves a very specific problem that is different from a lot of other patterns. I would exercise caution more when choosing extrinsic and intrinsic state in that you’re going to experience downstream pain if you label things “intrinsic” that actually can vary. Doing this threatens to break the pattern and the abstraction that you’ve created since modifying state that’s categorized as intrinsic will mean that your flyweights are no longer interchangeable and you’re going to start getting stuff wrong.

So this isn’t a good fit if you don’t have a good grasp yet on what should be extrinsic and what should be intrinsic. It’s also a bad fit if all state is extrinsic, as then there is no gain from the pattern. Another potential misuse that’s always worth mentioning with an optimization strategy is premature optimization. While I personally consider the elimination of duplication at runtime simply to be good design, I’d say that you might want to consider not bothering with the additional compile-time complexity if you’re not going to have very many objects. If, for instance, you were simulating twenty pieces of mail instead of tens of millions, it might not be worth the additional complexity.

So What? Why is this Better?

This one pretty much sells itself. In the example above, you can run the code without crashing or altering your data structures. Generally speaking, this is a pattern that helps you reduce your application’s memory footprint simply by creating a clever abstraction and shuffling the internal representation. If you can identify when there will be common information in volume, you can separate it from the unique information and make sure you’re being as efficient as possible.

By

Factory Method

Quick Information/Overview

Pattern Type Creational
Applicable Language/Framework Agnostic OOP
Pattern Source Gang of Four
Difficulty Moderate — slightly easier than Abstract Factory

Image courtesy of dofactory

Up Front Definitions

  1. Creator: This is the basic, abstract factory interface.
  2. Concrete Creator: Inheritor factory classes that implement some actual object creation scheme.
  3. Product: This is the base/abstract polymorphic object that gets created by the factories.

The Problem

Let’s say that you’re coding up some kind of game and in this game a character navigates a world and encounters various entities with which to interact, including enemies. You’re starting out with a very bare bones proof of concept, and here is your sketch of some enemies:

public abstract class Enemy
{
    public abstract string Attack();
}

public class Dragon : Enemy
{
    public override string Attack()
    {
        return "You've been torched with fire breath!";
    }
}

public class Gator : Enemy
{
    public override string Attack()
    {
        return "You've been chomped!";
    }
}

public class HouseFly : Enemy
{
    public override string Attack()
    {
        return "You've been annoyed!";
    }
}

public class MotherInLaw : Enemy
{
    public override string Attack()
    {
        return "You've been guilt-tripped!";
    }
}

public class ChuckNorris : Enemy
{
    public override string Attack()
    {
        return "Your entire existence has been erased from space-time in one devastating but magnificent master-stroke!";
    }
}

The concrete enemies return a string representation of their attack, which you will, no-doubt, later transform into some kind of first class attack object or even graphic as the game moves along, but for now, you just want to get the concept right. To get things going, you create the following class:

public class GameNarrative
{
    public void MoveMainCharacterTo(string placeName)
    {
        if (placeName == "swamp")
            InteractWithEnemy(new Gator());
    }

    private void InteractWithEnemy(Enemy enemy)
    {
        Console.Write(enemy.Attack());
    }
}

You want to keep things clean, so you abstract an interaction method, knowing that at some point this will probably mean something different than dumping to Console. From there, you’re now left to figure out the enemy situation based on where the character goes and you’re off to a good start since gators tend to hang out in swamps. Let’s add in a few more scenarios:

public void MoveMainCharacterTo(string placeName)
{
    if (placeName == "swamp")
        InteractWithEnemy(new Gator());
    else if (placeName == "starbucks" || placeName == "family reunion")
        InteractWithEnemy(new MotherInLaw());
    else if (placeName == "middleEarth")
        InteractWithEnemy(new Dragon());
    else if (placeName == "texas truck stop")
        InteractWithEnemy(new ChuckNorris());
    else
        InteractWithEnemy(new HouseFly());
}

Now you’re off and running. You decide that HouseFly is a good enemy to use in this case, since it seems like a good stock enemy ala the “Goombas” in Super Mario Brothers or Foot Soldiers in the Teenage Mutant Ninja Turtles (I’m probably dating myself a bit here). But wait a minute — house flies could happen anywhere. Let’s say that they’re the else condition, but they also have a 50/50 chance of appearing in the other places. Hmmm… let’s introduce an abstraction to hide the ugly and annoying details of randomization and do this:

public void MoveMainCharacterTo(string placeName)
{
    if (placeName == "swamp")
    {
        if (_randomizer.IsRandomCoinFlipHeads())
            InteractWithEnemy(new Gator());
        else
            InteractWithEnemy(new HouseFly());
    }
    else if (placeName == "starbucks" || placeName == "family reunion")
    {
        if (_randomizer.IsRandomCoinFlipHeads())
            InteractWithEnemy(new MotherInLaw());
        else
            InteractWithEnemy(new HouseFly());
    }
    else if (placeName == "middleEarth")
    {
        if (_randomizer.IsRandomCoinFlipHeads())
            InteractWithEnemy(new Dragon());
        else
            InteractWithEnemy(new HouseFly());
    }
    else if (placeName == "texas truck stop")
    {
        if (_randomizer.IsRandomCoinFlipHeads())
            InteractWithEnemy(new ChuckNorris());
        else
            InteractWithEnemy(new HouseFly());
    }
    else
        InteractWithEnemy(new HouseFly());
}

Ew, that’s starting to smell a bit, but no time to worry about that now. Your efforts here have led to some angel investment capital and now the pressure is on. You use that money to hire a UX/gameplay expert so that he can worry about the gaming decisions while you focus on architecture. He tells you that you need to introduce the concept of difficulty and that Chuck Norris can be anywhere except Middle Earth but only if the difficulty level is set to 5 or more. But Chuck Norris is a family man himself, so he’ll only attack you at a family reunion on a really high difficulty level like 10. Otherwise, he’ll wait until you leave. Hmmm….

public void MoveMainCharacterTo(string placeName)
{
    if (placeName == "swamp")
    {
        if (_difficultyLevel > 5)
        {
            switch (_randomizer.PickANumberOneThrough(3))
            {
                case 1: InteractWithEnemy(new Gator()); break;
                case 2: InteractWithEnemy(new HouseFly()); break;
                case 3: InteractWithEnemy(new ChuckNorris()); break;
            }
        }
        else
        {
            if (_randomizer.IsRandomCoinFlipHeads())
                InteractWithEnemy(new Gator());
            else
                InteractWithEnemy(new HouseFly());
        }
    }
    else if (placeName == "starbucks")
    {
        if (_difficultyLevel > 5)
        {
            switch (_randomizer.PickANumberOneThrough(3))
            {
                case 1: InteractWithEnemy(new MotherInLaw()); break;
                case 2: InteractWithEnemy(new HouseFly()); break;
                case 3: InteractWithEnemy(new ChuckNorris()); break;
            }
        }
        else
        {
            if (_randomizer.IsRandomCoinFlipHeads())
                InteractWithEnemy(new MotherInLaw());
            else
                InteractWithEnemy(new HouseFly());
        }
    }
    else if (placeName == "family reunion")
    {
        if (_difficultyLevel > 10)
        {
            switch (_randomizer.PickANumberOneThrough(3))
            {
                case 1: InteractWithEnemy(new Gator()); break;
                case 2: InteractWithEnemy(new HouseFly()); break;
                case 3: InteractWithEnemy(new ChuckNorris()); break;
            }
        }
        else
        {
            if (_randomizer.IsRandomCoinFlipHeads())
                InteractWithEnemy(new Gator());
            else
                InteractWithEnemy(new HouseFly());
        }
    }
    else if (placeName == "middleEarth")
    {
        if (_randomizer.IsRandomCoinFlipHeads())
            InteractWithEnemy(new Dragon());
        else
            InteractWithEnemy(new HouseFly());
    }
    else if (placeName == "texas truck stop")
    {
        if (_randomizer.IsRandomCoinFlipHeads())
            InteractWithEnemy(new ChuckNorris());
        else
            InteractWithEnemy(new HouseFly());
    }
    else
    {
        if (_difficultyLevel > 5)
        {
            if (_randomizer.IsRandomCoinFlipHeads())
                InteractWithEnemy(new ChuckNorris());
            else
                InteractWithEnemy(new HouseFly());
        }
        else
            InteractWithEnemy(new HouseFly());
    }
}

You look at this and realize that you’re definitely whipping up some spaghetti code here, but no time for that now. Your game designer tells you that you need a new mode of the game where instead of interacting with the enemies you talk with them first. The logic for encountering the enemies is exactly the same and you still need your old code, but you need it in a new module. Oh, and you should probably add a few new enemies that you find in a few new places. And house flies should probably stop appearing after difficulty level 7. Oh, and dragons can appear in Starbucks sometimes after a successful battle with MotherInLaw. Oh, and gators can appear at your family reunion if you have it in Florida.

Here’s the code for that… just kidding. You’re probably not going to read subsequent posts if I destroy your eyesight with the code I’m describing.

So, What to Do?

As has become customary in this section, let’s examine what went wrong. Most of the time it’s the point at which copying and pasting start, but not in this case. Another good tell in this series of posts where things go off the rail is when I start trotting out excuses for what ‘you’ are doing in the second person narrative. As soon as things are a little ugly because ‘you’ have a deadline or ‘your’ project manager is riding you, that’s usually when things went wrong. Here is no exception. Let’s rewind to the second code snippet, representative of a simpler time:

public void MoveMainCharacterTo(string placeName)
{
    if (placeName == "swamp")
        InteractWithEnemy(new Gator());
    else if (placeName == "starbucks" || placeName == "family reunion")
        InteractWithEnemy(new MotherInLaw());
    else if (placeName == "middleEarth")
        InteractWithEnemy(new Dragon());
    else if (placeName == "texas truck stop")
        InteractWithEnemy(new ChuckNorris());
    else
        InteractWithEnemy(new HouseFly());
}

This is alright, though I would argue that we can make a nice improvement here. Notice that we’re following a pretty consistent pattern here: we check place name and then we invoke the same method on a polymorphic object that varies with place name. It might seem like a trivial bit of redundancy, but these add up as you leave them in and, I would argue, poison the well when it comes to future design decisions. Broken Window Theory and all that. So let’s change the code to this:

public void MoveMainCharacterTo(string placeName)
{
    var enemy = GenerateLocalEnemyFor(placeName);
    InteractWithEnemy(enemy);
}

private static Enemy GenerateLocalEnemyFor(string placeName)
{
    switch (placeName)
    {
        case "swamp": return new Gator();
        case "starbucks":
        case "family reunion": return new MotherInLaw();
        case "middleEarth": return new Dragon();
        case "texas truck stop": return new ChuckNorris();
        default: return new HouseFly();
    }
}

Notice that there’s now only one call to “InteractWithEnemy” and we’ve split the functionality of mapping place name to en enemy instance from the functionality of interacting with the enemy in a nod to the SRP. You also might notice that we have implemented what has come to be a common variant of the original Factory Method pattern, which is the static factory method. A static factory method is a stateless method that takes in some criteria and spits back a matching polymorphic instance of the common base return type. For instance, this method says “if the place is middle earth, we need a dragon enemy.”

With this refactoring accomplished, let’s take on the next requirement, which is that house flies can occur anywhere with a 50% probability. Before our heads start rushing with design patterns and complex implementations, let’s consider what might be the easiest way to get this working. Didja think of this:

public void MoveMainCharacterTo(string placeName)
{
    var enemy = GenerateLocalEnemyFor(placeName, _randomizer);
    InteractWithEnemy(enemy);
}

private static Enemy GenerateLocalEnemyFor(string placeName, IRandomizeThings randomizer)
{
    if (randomizer.IsRandomCoinFlipHeads())
        return new HouseFly();

    switch (placeName)
    {
        case "swamp": return new Gator();
        case "starbucks":
        case "family reunion": return new MotherInLaw();
        case "middleEarth": return new Dragon();
        case "texas truck stop": return new ChuckNorris();
        default: return new HouseFly();
    }
}

Notice how easy that is with a little bit of logic separation. But, if that implementation strategy were going to hold up, there’d be no meat to this post, so let’s press on. Chuck Norris can be anywhere except for Middle Earth and a family reunion if the difficulty level is at least 5 and anywhere except Middle Earth if the difficulty level is at least 10. At this point it’s important to recognize what’s happening here and it’s easier to do so now with this factored road down which we’ve started. What’s happening is that what was originally a simple mapping from place name to enemy inheritor is becoming muddied by a growing number of additional factors. And what’s a good way to handle additional complexity in an object oriented programming language? Well, encapsulate it in an object.

The idea of centering the enemy generation around places is appealing since that’s how we originally conceived of it, so let’s stick with that. The family reunion one seems to be the most complicated, so let’s take a look at that:

public class FamilyReunionFactory
{
    private readonly IRandomizeThings _randomizer;

    public FamilyReunionFactory(IRandomizeThings randomizer)
    {
        _randomizer = randomizer;
    }

    public Enemy GetEnemy(int difficultyLevel)
    {
        if (difficultyLevel < 10)
            return _randomizer.ChooseAtRandom<Enemy>(new HouseFly(), new MotherInLaw());
        else
            return _randomizer.ChooseAtRandom<Enemy>(new HouseFly(), new MotherInLaw(), new ChuckNorris());
    }
}

(I added a “choose at random” method to the interface of signature T ChooseAtRandom<T>(params T[] thingsToChoose) to keep the emphasis on the factory class as much as possible rather than distracting with worries about random implementation. I acknowledge that this would have made the problem code a little less noisy, but it still would have been headed down a bad street with creeping complexity)

Cool! Now the GameNarrative class doesn’t need to worry about the creeping complexity around what goes into the decision of which enemy to generate beside the place name. We have a class with the single responsibility of figuring out how enemies get generated for the family reunion location. But how does this fit with the original class? Well, let’s take a look at an interim solution. Here is an updated, no-longer-static factory method:

private Enemy GenerateLocalEnemyFor(string placeName)
{
    switch (placeName)
    {
        case "swamp": return new Gator();
        case "starbucks":
        case "family reunion": return new FamilyReunionFactory(_randomizer).GetEnemy(_difficultyLevel);
        case "middleEarth": return new Dragon();
        case "texas truck stop": return new ChuckNorris();
        default: return new HouseFly();
    }
}

Notice that instead of directly instantiating an enemy when we’re at the family reunion, we delegate that task to our newly created factory. Let’s make a factory for each place now so that we can remove that awkward GetEnemy call and keep this method clean. In order to do this and return a factory instead of an enemey, we’re also going to need to make these factories polymorphic cousins of one another, by defining an interface (could also be an abstract base, which is less decoupled but allows implementation of a common constructor).

public interface IFamilyReunionFactory
{
    Enemy GetEnemy(int difficultyLevel);
}

And, with that in place and all of the other factories defined (elided), here is the new narrative class:

public class GameNarrative
{
    private readonly IRandomizeThings _randomizer;

    private readonly int _difficultyLevel;

    public GameNarrative(IRandomizeThings randomizer, int difficultyLevel)
    {
        _randomizer = randomizer;
        _difficultyLevel = difficultyLevel;
    }

    public void MoveMainCharacterTo(string placeName)
    {
        var enemyFactory = GetEnemyFactory(placeName);
        var enemy = enemyFactory.GetEnemy(_difficultyLevel);
        InteractWithEnemy(enemy);
    }

    private IEnemyFactory GetEnemyFactory(string placeName)
    {
        switch (placeName)
        {
            case "swamp": return new SwampFactory(_randomizer);
            case "starbucks": return new StarbucksFactory(_randomizer);
            case "family reunion": return new FamilyReunionFactory(_randomizer);
            case "middleEarth": return new MiddleEarthFactory(_randomizer);
            case "texas truck stop": return new TexasTruckStopFactory(_randomizer);
            default: return new DefaultFactory(_randomizer);
        }
    }

    private void InteractWithEnemy(Enemy enemy)
    {
        Console.Write(enemy.Attack());
    }
}

That’s looking pretty darn legible now. But it’s not just that the code is easy to read or even that it’s separated into factored methods and classes. The important thing here is conformance to SRP and the fact that it’s easy to find what needs to change and change it independently of other concerns. Think back to the change request that broke our spirit earlier. Adding new enemies? Piece of cake — just add classes for them and then add them to the random generation in the factories that are eligible to generate them. Porting enemy generation? Just make the GetEnemyGeneration method (or some variant of it) publicly accessible and call it elsewhere. All of the new enemy generation business rules? Put them in their appropriate factories. Cross cutting rules? Create a base factory class. These tasks are now quite manageable.

A More Official Explanation

The stated purpose of the Factory Method design pattern (from dofactory) is:

Define an interface for creating an object, but let subclasses decide which class to instantiate. Factory Method lets a class defer instantiation to subclasses.

This creational pattern is also sometimes referred to as “virtual constructor” because of the way it separates the promise of object creation from the implementation via polymorphism. Be it an interface or abstract base class, the abstract definition defines a contract for the generation of polymorphic entities and then delegates that work to implementers/inheritors.

This has the powerful benefit of allowing flexibility and following of the open/closed principle not just for creation of objects but for strategies for object creation. In our example above, the IEnemyFactory is the Creator, the various factories are the Concrete Creators and the enemies are Products. We have the ability with this implementation to seamlessly add new enemies but also to seamlessly add new schemes for generating enemies. If we wanted to add a location called “mountains” with its own unique set of denizens to the game, this would be straightforward and have nearly 0 bearing on existing code.

It is worth noting the conceptual similarity to Abstract Factory at this point and pointing out that the jump from Factory Method to Abstract Factory is just the addition of more polymorph families. For instance, if each location had enemies, terrain, and allies, Abstract Factory would be a good fit. That said, the transition from Factory Method to Abstract Factory is extremely violent to the code base since the addition of methods to the factory require changes to all implementers. Thus it is probably good to spend some effort up front reasoning about what the factory should do, particularly if the concrete factories are spread far and wide (unless you are using an abstract base class and then there is some reprieve here as you can specify default behavior).

Other Quick Examples

  1. An enterprise application capable of pulling information from multiple persistence models (factory methods to create DAOs).
  2. A GUI intensive application that generates controls/forms/pages on the fly depending on user interaction.

A Good Fit – When to Use

This is an interesting one circa 2012 because it seems like a decent amount of the heavy lifting that I used to see this pattern do has been replaced by IoC containers or plugin architectures. In other words, the Gang of Four made it fashionable to move complex instance creation into its own place in your code, and the Unit Test/TDD crowd later made it fashionable to move it out of your code altogether. It’s also been squeezed on the other side, so to speak, by the prevalence of the “poor man’s factory method” — a simple static method that returns polymorphs representing a common interface or base class.

But in reality, this pattern has its own niche not covered by either of these situations. IoC containers and, to some extent, plugin architectures are really about decisions made at application start time. The point of abstracting them out of the codebase is to allow application behavior to be changed without rebuilding and re-deploying. Factory Method as I would advocate covers a subtly different usage scenario wherein the polymorphic type is not known at application startup. An obvious example (and the one we covered in this post) is where the user supplies input that governs which object should be created in some way.

But this could still mean using the static method rather than the class hierarchy of Factory Method. I would recommend the latter specifically in situations where the logic surrounding instance creation is more complex than switching over a simple argument or two and/or likely to grow and change with time (the aforementioned Open/Closed Principle). If you find that you have a static factory method that’s ballooning in size and cyclomatic complexity it’s probably time to consider a factory method hierarchy.

Square Peg, Round Hole – When Not to Use

The inverse of various situations described in the previous section is a good place to start. You probably don’t want to use this pattern for very simple scenarios (say, switching over an enum or character to create instances) and you probably don’t want to use it for decision that can be made prior to runtime as that introduces more complexity and indirection to your application than necessary. Another place that you’d avoid this is when you need an abstract factory because you’re creating object families.

As always, YAGNI applies, and factories are sort of iconic in representing over-engineering in OOP. I once heard a cynical but funny quote (don’t recall who originally said it, but if you know, please comment): “some people think they’ll use java to solve their problems — now they have a problem factory.” This is obviously tongue in cheek, but the implied point about pattern happy enterprise development shines through. It’s easy to get pretty elaborate when abstracting instance creation out of plumbing and service code (and I love the practice) but there’s a fine line between this and creating too many levels of indirection. Be careful that you actually need these factories and aren’t just speculatively abstracting. As a rule of thumb, I’d say that you should be able to look at them and think “man, it’s a good thing I pulled that into a class.”

So What? Why is this Better?

As show in the example, when judiciously used, the Factory Method pattern can transform what would have been a snarl of instantiation spaghetti into a well separated, maintainable set of classes. The “after” in this picture shows code that conforms to established OOP principles such as the Open/Closed Principle and the Single Responsibility Principle (you can throw Liskov in there too since there’s a lot of polymorphism here).

Once this is in place, adding new target/product objects for creation is a segregated and approachable problem and adding new creation schemes becomes quite easy. It’s also straightforward to separate creation from use in your code as well, leading to a lot of architectural flexibility. And, properly applied, it’s a good mechanism for avoiding the bane of programming existence — copy and paste coding.

By

Facade

Quick Information/Overview

Pattern Type Structural
Applicable Language/Framework Agnostic OOP
Pattern Source Gang of Four
Difficulty Easy

Up Front Definitions

The Problem

Let’s say that you work on a web based piece of software that processes orders for customers in some sort of retail capacity and that there is a framework for a lot of existing operations with which you have to deal. You’re tasked with creating the UI for taking orders from customers. At your disposal, you have three handy functionalities: an order DAO for storing order information to the database, a receipt printer for printing receipts, and an email sender for sending confirmation emails. These things exist in different assemblies and your presentation layer assembly, fortunately, has references to all of them.

So, you write some code that looks like this:

public class OrderViewModel
{
    private readonly EmailSender _emailSender;
    private readonly ReceiptPrinter _receiptPrinter;
    private readonly OrderDao _orderDao;

    public OrderViewModel(EmailSender emailSender, ReceiptPrinter receiptPrinter, OrderDao orderDao)
    {
        _emailSender = emailSender;
        _receiptPrinter = receiptPrinter;
        _orderDao = orderDao;
    }

    public void HandleOrderExecuted(Order order)
    {
        ExecuteOrder(order);
    }

    private void ExecuteOrder(Order order)
    {
        _orderDao.StoreOrder(order);
        _emailSender.SendEmail(new OrderEmail(order));
        _receiptPrinter.PrintReceiptForOrder(order);
    }
}

Life is good. Your customer can now issue an order through your page and the view model that supports it. Making note of your success, your manager hands you a requirement to display recommendations to the screen following an order. Luckily, there is a module called RecommendationEngine that you can use for just such an occasion:

public class OrderViewModel
{
    private readonly EmailSender _emailSender;
    private readonly ReceiptPrinter _receiptPrinter;
    private readonly OrderDao _orderDao;
    private readonly RecommendationEngine _recommendationEngine;

    public ObservableCollection<Recommendation> Recommendations { get; set; }

    public OrderViewModel(EmailSender emailSender, ReceiptPrinter receiptPrinter, OrderDao orderDao, RecommendationEngine engine)
    {
        _emailSender = emailSender;
        _receiptPrinter = receiptPrinter;
        _orderDao = orderDao;
        _recommendationEngine = engine;
        Recommendations = new ObservableCollection<Recommendation>();
    }

    public void HandleOrderExecuted(Order order)
    {
        ExecuteOrder(order);
    }

    private void ExecuteOrder(Order order)
    {
        _orderDao.StoreOrder(order);
        _emailSender.SendEmail(new OrderEmail(order));
        _receiptPrinter.PrintReceiptForOrder(order);

        PouplateRecommendations();
    }

    private void PouplateRecommendations()
    {
        Recommendations.Clear();
        foreach (var myRecommendation in _recommendationEngine.GetRecommendations())
            Recommendations.Add(myRecommendation);
    }
}

Excellent. Well, mostly, anyway. This class’s constructor is starting to get a little busy and it depends on sort of a hodgepodge of other assemblies. But, it’s probably nothing — adding that additional assembly reference for the recommendation engine was probably just an anomaly.

Besides, your manager is so impressed that it’s time to assign you to a different screen. As it turns out, there is the traditional order placement screen and a new express one for frequent customers. So, you need to write a new screen and ViewModel, which you do. Since you’ve already implemented the order execution logic, you just copy and paste it and the field declarations into the new ViewModel, initializing the fields in the constructor. You’re not thrilled about the copy and paste, but whatcha gonna do?

At this point, your manager points out a requirement that nobody had considered: users might want to access a virtual copy of their receipts later. You notice an assembly containing a class called ReceiptDao that sounds promising, and you add that:

public class OrderViewModel
{
    private readonly EmailSender _emailSender;
    private readonly ReceiptPrinter _receiptPrinter;
    private readonly OrderDao _orderDao;
    private readonly ReceiptDao _receiptDao;
    private readonly RecommendationEngine _recommendationEngine;

    public ObservableCollection<Recommendation> Recommendations { get; set; }

    public OrderViewModel(EmailSender emailSender, ReceiptPrinter receiptPrinter, OrderDao orderDao, RecommendationEngine engine, ReceiptDao receiptDao)
    {
        _emailSender = emailSender;
        _receiptPrinter = receiptPrinter;
        _orderDao = orderDao;
        _recommendationEngine = engine;
        _receiptDao = receiptDao;
        Recommendations = new ObservableCollection<Recommendation>();
    }

    public void HandleOrderExecuted(Order order)
    {
        ExecuteOrder(order);
    }

    private void ExecuteOrder(Order order)
    {
        _orderDao.StoreOrder(order);
        _emailSender.SendEmail(new OrderEmail(order));
        _receiptPrinter.PrintReceiptForOrder(order);
        _receiptDao.Save(order);

        PouplateRecommendations();
    }

    private void PouplateRecommendations()
    {
        Recommendations.Clear();
        foreach (var myRecommendation in _recommendationEngine.GetRecommendations())
            Recommendations.Add(myRecommendation);
    }
}

Well, problem solved, though that dependency list is growing. The order logic now stores the receipt. You promote it and get a defect back from QA that the express ordering system doesn’t store virtual receipts the way the normal one does. Oops. Such is life when you copy and paste program — you forgot to change the other implementation. Ah, well, happens to the best of us.

But now, you get a series of assignments from the manager to add more functionality from other modules while simultaneously adding more places from which an order can be placed. That means adding a lot of code to the two implementations that already exist, bloating them, and then copying and pasting the resulting monstrosity to various other locations.

So, What to Do?

As always in this section, it’s important to identify where things went wrong. It’s debatable as to whether adding that fourth dependency was a problem or not — that constructor is getting pretty busy at this point and the dependency fan out is climbing. However, in and of itself, that may not be a problem.

It stops being debatable (as it always does) when they copying and pasting starts. That’s bad. Any time you find yourself doing that you’re failing at design. In this case, the most obvious fix is the one that will lead us to a better path. Specifically, we need to factor the duplicated code into a class. So, let’s introduce a class called OrderService:

public class OrderService
{
    private readonly EmailSender _emailSender;
    private readonly ReceiptPrinter _receiptPrinter;
    private readonly OrderDao _orderDao;
    private readonly ReceiptDao _receiptDao;
    private readonly RecommendationEngine _recommendationEngine;

    public OrderService(EmailSender emailSender, ReceiptPrinter receiptPrinter, OrderDao orderDao, ReceiptDao receiptDao, RecommendationEngine recommendationEngine)
    {
        _emailSender = emailSender;
        _receiptPrinter = receiptPrinter;
        _orderDao = orderDao;
        _receiptDao = receiptDao;
        _recommendationEngine = recommendationEngine;
    }

    public void ExecuteOrder(Order order)
    {
        _orderDao.StoreOrder(order);
        _emailSender.SendEmail(new OrderEmail(order));
        _receiptPrinter.PrintReceiptForOrder(order);
        _receiptDao.Save(order);
    }

    public IEnumerable<Recommendation> GetRecommendations()
    {
        return _recommendationEngine.GetRecommendations();
    }
}

Now, this service class can be used by any ViewModel client without duplicating logic. Here’s what the client now looks like:

public class OrderViewModel
{
    private readonly OrderService _service;

    public ObservableCollection<Recommendation> Recommendations { get; set; }

    public OrderViewModel(OrderService service)
    {
        _service = service;
        Recommendations = new ObservableCollection<Recommendation>();
    }

    public void HandleOrderExecuted(Order order)
    {
        _service.ExecuteOrder(order);
        PouplateRecommendations();
    }

    private void PouplateRecommendations()
    {
        Recommendations.Clear();
        foreach (var myRecommendation in _service.GetRecommendations())
            Recommendations.Add(myRecommendation);
    }
}

The only duplication that might occur here is injecting and invoking the service (though that can be fixed among the ViewModels, but that’s beyond the scope of this post). We’ve eliminated the duplication that makes things like adding the receipt storage a pain point. Also, observe that if we put the service in a separate assembly from the ViewModels, we can now remove the assembly references to the various lower level services such as EmailSender, ReceiptPrinter, etc.

While this separation may seem like pushing our problems out a layer, there is a real benefit to doing this. Specifically, presentation layer classes should not be concerned with locating lower level components. They should be allowed to focus on marshaling data for presentation. Following the single responsibility principle suggests that presenting order confirmation to the user and navigating the mechanics of the subsystems required for an order are two separate responsibilities.

The five (and growing) dependencies that have been added to the constructor of the service to spare the ViewModel are still problematic in terms of good design. This could be fixed with further facades, if the application is large enough to support conceptual sub-layers. That is, there could be a general DAO facade and a general externalities facade that took care of the dao functions and email/receipts/recommendations respectively. This scheme would have the service knowing only about two collaborators instead of five while deepening the call stack hierarchy.

Another approach might be to consolidate some of these assemblies or classes at lower layers, if possible. It might also be reasonable, depending on the situation, simply to leave this service class alone, having abstracted this sub-system out of the presentation layer.

A More Official Explanation

DoFactory defines Facade as a pattern that aims to:

Provide a unified interface to a set of interfaces in a subsystem. Façade defines a higher-level interface that makes the subsystem easier to use.

This is pretty straightforward to understand and it constitutes one of the most basic and fundamental patterns of programming. Facades provide a layer of abstraction, hiding low level details from client code in favor of broader, easier to understand interactions. I have blogged extensively about the subject of abstraction, if you’d like a more in-depth treatment of the concept.

In general, facades form the back bone of solid architecture in code bases by virtue of hiding conceptually difficult details behind conceptually simple points of access. The crux of this pattern is hiding and managing complexity.

Other Quick Examples

Other incarnations of the Facade Pattern include:

  1. The iconic example of mortgage applications where lenders, banks, inspectors, etc are all necessary to complete the single process.
  2. A unified or single class that you write to hide an ugly third-party API or series of APIs.
  3. In a very real sense, the structure of a class is a bit of a facade since implementation details (private fields and members) are hidden behind the facade of the public API.

A Good Fit – When to Use

Facade is good any time you want to hide details of a process from client code. This can apply, as I mentioned, at the assembly/module level and it can even apply at the class and method level. If you practice good software design this is a pattern that you will find yourself using constantly. It is the essence of providing good abstractions.

Square Peg, Round Hole – When Not to Use

The main usage anti-pattern of a facade is providing a layer or “wrapper” that really does nothing or fails to simplify things for clients. There can be a fine line between organizing code and hiding details and introducing pointless layering, so it is important to consider whether the facade that you’re adding is either (1) making things easier or (2) hiding details that should be hidden. If it’s doing neither of these things, it probably shouldn’t exist.

So What? Why is this Better?

Generally speaking, facades can help eliminate redundant logic and they can simplify interaction with a system. These are two of the most important considerations in all of software. Redundancy is the bane of maintainability and abstraction is the backbone of understandable systems. Well placed facades (such as layered architecture, for instance) provide both in one shot. The end result is that your code will be well factored and decoupled, easy to maintain, and easy to reason about.

By

Decorator

Quick Information/Overview

Pattern Type Structural
Applicable Language/Framework Agnostic OOP
Pattern Source Gang of Four
Difficulty Easy

Up Front Definitions

  1. Decorator: An object that is both an inherits from and operates on another object.
  2. Component: Abstract target base class (or interface) of the decorator pattern.
  3. Target: For the purposes of this post, I use this term interchangeably with Component.

The Problem

Let’s say that you have to model employees at a company, and all employees have a name, an hourly wage, and a bio that describes them. Furthermore, these items are going to be determined by the type of employee that each employee is (they can be Workers, Managers, or Executives for now, but there might be more later). Since this begs for an extensible, polymorphic structure, you create the following class structure and program to take it for a test drive:

public abstract class Employee
{
    public string Name { get; protected set; }

    public double HourlyWage { get; protected set; }

    public string EmployeeBio { get; protected set; }

    protected Employee(string name, double hourlyWage, string bio)
    {
        HourlyWage = hourlyWage;
        Name = name;
        EmployeeBio = bio;
    }
}

public class Worker : Employee
{
    public Worker(string name) : base(name, 12.5, "Rank and File") { }
}

public class Manager : Employee
{
    public Manager(string name) : base(name, 25.0, "Line Manager") { }
}

public class Executive : Employee
{
    public Executive(string name) : base(name, 50.0, "Bigwig") { }
}

class Program
{
    static void Main(string[] args)
    {
        var myEmployees = new List();
        myEmployees.Add(new Worker("Jim Halpert"));
        myEmployees.Add(new Manager("Michael Scott"));
        myEmployees.Add(new Executive("Jan Levenson"));

        PrintAllEmployees(myEmployees);
    }

    private static void PrintAllEmployees(ListmyEmployees)
    {
        foreach (var myEmployee in myEmployees)
        {
            Console.WriteLine(String.Format("{0}, {1}, makes {2} per hour.", myEmployee.Name, myEmployee.EmployeeBio, myEmployee.HourlyWage));
        }
        Console.ReadLine();
    }
}

Simple enough. This is nice and clean because later, if we want to add a new type of employee (maybe Toby from HR), we can just create a new type of employee through inheritance, and the print function will hum happily along. This is classic Open/Closed Principle stuff. Different types of employees define their own attributes, and there are no ugly enums called “EmployeeType” — life is good.

Now, let’s say that an industrious project manager gets wind of the rave reviews your office modeling program has gotten for its usability and clean design and decides to hitch his wagon to your effort. You get a request coming in that employees be able to be distinguished as “high performers”. Any employee with the “high performer” designation should be paid 10% more than non-high performer counterparts, and this recognition should be reflected in the employee’s bio. So, you change the code to look like this:

public abstract class Employee
{
    public string Name { get; protected set; }

    public double HourlyWage { get; protected set; }

    public string EmployeeBio { get; protected set; }

    protected Employee(string name, double hourlyWage, string bio, bool isHighPerformer = false)
    {
        HourlyWage = hourlyWage;
        Name = name;
        EmployeeBio = bio;
        if (isHighPerformer)
        {
            HourlyWage *= 1.10;
            EmployeeBio = EmployeeBio + ", High Performer";
        }
    }
}

public class Worker : Employee
{
    public Worker(string name, bool isHighPerformer = false) : base(name, 12.5, "Rank and File", isHighPerformer) { }
}

public class Manager : Employee
{
    public Manager(string name, bool isHighPerformer = false) : base(name, 25.0, "Line Manager", isHighPerformer) { }
}

public class Executive : Employee
{
    public Executive(string name, bool isHighPerformer = false) : base(name, 50.0, "Bigwig", isHighPerformer) { }
}

class Program
{
    static void Main(string[] args)
    {
        var myEmployees = new List();
        myEmployees.Add(new Worker("Jim Halpert", true));
        myEmployees.Add(new Manager("Michael Scott"));
        myEmployees.Add(new Executive("Jan Levenson"));

        PrintAllEmployees(myEmployees);
    }

    private static void PrintAllEmployees(ListmyEmployees)
    {
        foreach (var myEmployee in myEmployees)
        {
            Console.WriteLine(String.Format("{0}, {1}, makes {2} per hour.", myEmployee.Name, myEmployee.EmployeeBio, myEmployee.HourlyWage));
        }
        Console.ReadLine();
    }
}

Hmmm… polymorphic structure still looks good, and the optional parameter even allows you to implement this functionality as a non-breaking change for client code, but the constructors are starting to get a little noisy and unfocused. It’s also not necessarily awesome that you had to touch every class constructor in the polymorphic structure, but whatever, project management is happy and hopefully they don’t ask for more stuff like that.

And, turns out they don’t. Instead, they want to be able to record the fact that some employees are members of the corporate “safety team”, responsible for knowing how fire extinguishers work and counting people during fire drills and whatnot. So, during the normal print, safety team membership should be reflected in the bio, but it should also be possible to see what a safety team member’s team responsibility is.

Here we have a classic inheritance situation… sort of. Safety team members are still normal employees (meaning any safety team member must be worker, manager or exec), so they can’t inherit from the abstract base employee class. And, it doesn’t make sense to add safety team information and implementation to any existing classes, since none of them necessarily represent safety team members. So, you suppose they’ll just have to inherit from the three classes we’ve defined so far, like this:

public abstract class Employee
{
    public string Name { get; protected set; }

    public double HourlyWage { get; protected set; }

    public string EmployeeBio { get; protected set; }

    protected Employee(string name, double hourlyWage, string bio, bool isHighPerformer = false)
    {
        HourlyWage = hourlyWage;
        Name = name;
        EmployeeBio = bio;
        if (isHighPerformer)
        {
            HourlyWage *= 1.10;
            EmployeeBio = EmployeeBio + ", High Performer";
        }
    }
}

public class Worker : Employee
{
    public Worker(string name, bool isHighPerformer = false) : base(name, 12.5, "Rank and File", isHighPerformer) { }
}

public class SafetyTeamWorker : Worker
{
    public string SafetyDescription { get; set; }

    public SafetyTeamWorker(string name, bool isHighPerformer = false) : base(name, isHighPerformer)
    {
        EmployeeBio += ", Safety Team Member";
    }
}

public class Manager : Employee
{
    public Manager(string name, bool isHighPerformer = false) : base(name, 25.0, "Line Manager", isHighPerformer) { }
}

public class SafetyTeamManager : Manager
{
    public string SafetyDescription { get; set; }

    public SafetyTeamManager(string name, bool isHighPerformer = false) : base(name, isHighPerformer)
    {
        EmployeeBio += ", Safety Team Member";
    }
}

public class Executive : Employee
{
    public Executive(string name, bool isHighPerformer = false) : base(name, 50.0, "Bigwig", isHighPerformer) { }
}

public class SafetyTeamExecutive : Executive
{
    public string SafetyDescription { get; set; }

    public SafetyTeamExecutive(string name, bool isHighPerformer = false) : base(name, isHighPerformer)
    {
        EmployeeBio += ", Safety Team Member";
    }
}

class Program
{
    static void Main(string[] args)
    {
        var myEmployees = new List();
        myEmployees.Add(new Worker("Jim Halpert", true));
        myEmployees.Add(new SafetyTeamManager("Michael Scott"));
        myEmployees.Add(new Executive("Jan Levenson"));

        PrintAllEmployees(myEmployees);
    }

    private static void PrintAllEmployees(ListmyEmployees)
    {
        foreach (var myEmployee in myEmployees)
        {
            Console.WriteLine(String.Format("{0}, {1}, makes {2} per hour.", myEmployee.Name, myEmployee.EmployeeBio, myEmployee.HourlyWage));
        }
        Console.ReadLine();
    }
}

Uh, oh. This is starting to smell. You’re not thrilled about creating three classes when what you really wanted was one class, and you’re really not thrilled about the fact that the three classes are copy and paste jobs of one another. But, no time for all that clean code claptrap now, you’re getting more requirements in from the project manager and you’ve got to get things done. They system also has to be able to track whether employees are on the softball team and, if so, what position they play. So that means, another three copy and paste classes. Except, wait a minute, safety team members can be softball players too. So, we really need to add another 6 copy and paste classes, bringing the total to 9 copies and 3 that we started with:

public abstract class Employee
{
    public string Name { get; protected set; }

    public double HourlyWage { get; protected set; }

    public string EmployeeBio { get; protected set; }

    protected Employee(string name, double hourlyWage, string bio, bool isHighPerformer = false)
    {
        HourlyWage = hourlyWage;
        Name = name;
        EmployeeBio = bio;
        if (isHighPerformer)
        {
            HourlyWage *= 1.10;
            EmployeeBio = EmployeeBio + ", High Performer";
        }
    }
}

public class Worker : Employee
{
    public Worker(string name, bool isHighPerformer = false) : base(name, 12.5, "Rank and File", isHighPerformer) { }
}

public class SoftballPlayingWorker : Worker
{
    public string Position { get; set; }

    public SoftballPlayingWorker(string name, bool isHighPerformer = false) : base(name, isHighPerformer)
    {
        EmployeeBio += ", Softball Player";
    }
}

public class SafetyTeamWorker : Worker
{
    public string SafetyDescription { get; set; }

    public SafetyTeamWorker(string name, bool isHighPerformer = false) : base(name, isHighPerformer)
    {
        EmployeeBio += ", Safety Team Member";
    }
}

public class SoftballPlayingSafetyTeamWorker : SafetyTeamWorker
{
    public string Position { get; set; }

    public SoftballPlayingSafetyTeamWorker(string name, bool isHighPerformer = false) : base(name, isHighPerformer)
    {
        EmployeeBio += ", Softball Player";
    }
}

public class Manager : Employee
{
    public Manager(string name, bool isHighPerformer = false) : base(name, 25.0, "Line Manager", isHighPerformer) { }
}

public class SoftballPlayingManager : Manager
{
    public string Position { get; set; }

    public SoftballPlayingManager(string name, bool isHighPerformer = false) : base(name, isHighPerformer)
    {
        EmployeeBio += ", Softball Player";
    }
}

public class SafetyTeamManager : Manager
{
    public string SafetyDescription { get; set; }

    public SafetyTeamManager(string name, bool isHighPerformer = false) : base(name, isHighPerformer)
    {
        EmployeeBio += ", Safety Team Member";
    }
}

public class SoftballPlayingSafetyTeamManager : SafetyTeamManager
{
    public string Position { get; set; }

    public SoftballPlayingSafetyTeamManager(string name, bool isHighPerformer = false) : base(name, isHighPerformer)
    {
        EmployeeBio += ", Softball Player";
    }
}

public class Executive : Employee
{
    public Executive(string name, bool isHighPerformer = false) : base(name, 50.0, "Bigwig", isHighPerformer) { }
}

public class SoftballPlayingExecutive : Executive
{
    public string Position { get; set; }

    public SoftballPlayingExecutive(string name, bool isHighPerformer = false) : base(name, isHighPerformer)
    {
        EmployeeBio += ", Softball Player";
    }
}

public class SafetyTeamExecutive : Executive
{
    public string SafetyDescription { get; set; }

    public SafetyTeamExecutive(string name, bool isHighPerformer = false) : base(name, isHighPerformer)
    {
        EmployeeBio += ", Safety Team Member";
    }
}

public class SoftballPlayingSafetyTeamExecutive : SafetyTeamExecutive
{
    public string Position { get; set; }

    public SoftballPlayingSafetyTeamExecutive(string name, bool isHighPerformer = false) : base(name, isHighPerformer)
    {
        EmployeeBio += ", Softball Player";
    }
}

class Program
{
    static void Main(string[] args)
    {
        var myEmployees = new List();
        myEmployees.Add(new Worker("Jim Halpert", true));
        myEmployees.Add(new SafetyTeamManager("Michael Scott"));
        myEmployees.Add(new SoftballPlayingSafetyTeamExecutive("Jan Levenson"));

        PrintAllEmployees(myEmployees);
    }

    private static void PrintAllEmployees(ListmyEmployees)
    {
        foreach (var myEmployee in myEmployees)
        {
            Console.WriteLine(String.Format("{0}, {1}, makes {2} per hour.", myEmployee.Name, myEmployee.EmployeeBio, myEmployee.HourlyWage));
        }
        Console.ReadLine();
    }
}

Suddenly, you’ve got a train-wreck on your hands. After you track down a few hard-to-fix defects that resulted from the wrong inheritance scheme when you forgot to change “Worker” to “Manager” in one of your copy-paste implementations, the project manager tells you that there’s no time for refactoring because now you need to be able to who who is on the Party Planning Committee and who is a member of the Finer Things Club. Your 12 classes just became 36 and then 108.

The only option at this point is clearly to write a program that can automate generating this code for you. That, or retire.

So, What to Do?

As is often the case in this series of posts, the important thing is to retrace our steps and figure out where things went off the rails. And, as is even more often the case, our problems started as soon as we started duplicating code, and they got worse the more egregiously we did it. So, where do we go from here? It’s simpler in this post than in some of the others — let’s start by deleting all of these misguided inheritors and revert to the state we were in immediately after defining our optional “isHighEarner” parameter (we’ll get to that later).

Now, let’s add a class called “EmployeDecorator”. It will inherit from Employee and be abstract. If you’ll recall, when implementing the safety team requirement, we dismissed the possibility of safety team inheriting from Employee directly because safety team members also needed to be Workers, Managers, or Executives, but we’re going to introduce a way around that problem:

public abstract class EmployeeDecorator : Employee
{
    private readonly Employee _target;
    protected Employee Target { get { return _target; } }

    public EmployeeDecorator(Employee target)
    {
        _target = target;
        Name = target.Name;
        HourlyWage = target.HourlyWage;
        EmployeeBio = EmployeeBio;
    }
}

Notice that this decorator object curiously both inherits from and wraps Employee, and proceeds to seed its own properties with those of the employee. This allows the decorator to look to clients as though it is the object its wrapping. This has some powerful ramifications, as we can see here:

public class SafetyTeamMember : EmployeeDecorator
{
    public string SafetyDescription { get; set; }

    public SafetyTeamMember(Employee target) : base(target)
    {
        EmployeeBio += "Safety Team Member ";
    }
}

Now, we can add safety team member functionality to an employee simply by taking an employee and injecting it into the constructor of the concrete decorator. As we do this, we trust the decorator to apply the appropriate modifications to the employee and expose the properties that we would demand of the employee. So, in this case decorator adds bio information and when we query its bio, we get the employee’s information plus the “decoration” of the addition to the bio. On top of that, we can set this object’s “Safety Description”. In effect, we’re extending the functionality of an object without inheriting directly from it. The common ancestor is, however necessary, as this is what gives us access to the protected members of employee. Here is the client instantiation logic:

static void Main(string[] args)
{
    var myEmployees = new List();
    myEmployees.Add(new Worker("Jim Halpert", true));
    var myManager = new Manager("Michael Scott");
    myEmployees.Add(new SafetyTeamMember(myManager));
    myEmployees.Add(new Executive("Jan Levenson"));

    PrintAllEmployees(myEmployees);
}

And this results in the same printed information. Now, let’s implement our softball player requirement and set Michael Scott up as both a softball player and a safety team member.

public class SoftballPlayer : EmployeeDecorator
{
    public string Position { get; set; }

    public SoftballPlayer(Employee target) : base(target)
    {
        EmployeeBio += "Softball Player, ";
    }
}

class Program
{
    static void Main(string[] args)
    {
        var myEmployees = new List();
        myEmployees.Add(new Worker("Jim Halpert", true));
        Employee myManager = new Manager("Michael Scott");
        myManager = new SoftballPlayer(myManager);
        myEmployees.Add(new SafetyTeamMember(myManager));
        myEmployees.Add(new Executive("Jan Levenson"));

        PrintAllEmployees(myEmployees);
    }

    private static void PrintAllEmployees(ListmyEmployees)
    {
        foreach (var myEmployee in myEmployees)
        {
            Console.WriteLine(String.Format("{0}, {1} makes {2} per hour.", myEmployee.Name, myEmployee.EmployeeBio, myEmployee.HourlyWage));
        }
        Console.ReadLine();
    }
}

Now, Michael is a real Rennaisance Man, and it only took 3 extra classes rather than 12. And, that number will raise to 5, rather than 108, with the next set of project management requirements. So, we’re setting pretty, but we can do even better — we can refactor the higher performer functionality to be part of another decorator as well, to achieve this finished product:

public abstract class Employee
{
    public string Name { get; protected set; }

    public double HourlyWage { get; protected set; }

    public string EmployeeBio { get; protected set; }

    protected Employee() { }

    protected Employee(string name, double hourlyWage, string bio)
    {
        HourlyWage = hourlyWage;
        Name = name;
        EmployeeBio = bio;
    }
}

public class Worker : Employee
{
    public Worker(string name) : base(name, 12.5, "Rank and File, ") { }
}

public class Manager : Employee
{
    public Manager(string name) : base(name, 25.0, "Line Manager, ") { }
}

public class Executive : Employee
{
    public Executive(string name) : base(name, 50.0, "Bigwig, ") { }
}

public abstract class EmployeeDecorator : Employee
{
    private readonly Employee _target;
    protected Employee Target { get { return _target; } }

    public EmployeeDecorator(Employee target)
    {
        _target = target;
        Name = target.Name;
        HourlyWage = target.HourlyWage;
        EmployeeBio = target.EmployeeBio;
    }
}

public class SafetyTeamMember : EmployeeDecorator
{
    public string SafetyDescription { get; set; }

    public SafetyTeamMember(Employee target) : base(target)
    {
        EmployeeBio += "Safety Team Member, ";
    }
}

public class SoftballPlayer : EmployeeDecorator
{
    public string Position { get; set; }

    public SoftballPlayer(Employee target) : base(target)
    {
        EmployeeBio += "Softball Player, ";
    }
}

public class HighPerformer : EmployeeDecorator
{
    public HighPerformer(Employee target) : base(target)
    {
        EmployeeBio += " High Performer,";
        HourlyWage *= 1.10;
    }
}

class Program
{
    static void Main(string[] args)
    {
        var myEmployees = new List();
        Employee myWorker = new Worker("Jim Halpert");
        myEmployees.Add(new HighPerformer(myWorker));
        Employee myManager = new Manager("Michael Scott");
        myManager = new SoftballPlayer(myManager);
        myEmployees.Add(new SafetyTeamMember(myManager));
        myEmployees.Add(new Executive("Jan Levenson"));

        PrintAllEmployees(myEmployees);
    }

    private static void PrintAllEmployees(ListmyEmployees)
    {
        foreach (var myEmployee in myEmployees)
        {
            Console.WriteLine(String.Format("{0}, {1} makes {2} per hour.", myEmployee.Name, myEmployee.EmployeeBio, myEmployee.HourlyWage));
        }
        Console.ReadLine();
    }
}

Now, that weird extra parameter is gone — “high performance” is now something added to employees rather than ingrained. And, the high performance decorator illustrates nicely that decorators can serve either or both of two purposes: extending functionality and/or modifying the target (“component”).

A More Official Explanation

Turning once again to dofactory (UML diagram image came from here as well), a more formal definition of the Decorator Pattern is to:

Attach additional responsibilities to an object dynamically. Decorators provide a flexible alternative to subclassing for extending functionality.

The key thing to note in our process or refactoring toward the Decorator pattern is that we were defining a scheme whereby employees could be given ancillary responsibilities without changing their fundamental makeup. In our example, all employees have a wage, name, and bio, but not all employees are safety team members, high earners, etc. The Decorator pattern allows us to reflect this reality by attaching these ancillary responsibilities in ad hoc fashion, and without adding any properties to the Employee class or sub-classes that may not be used.

The Decorator Pattern is a means for extending a class’s functionality without either modifying that class or inheriting from that class. It takes advantage of the nature of inheritance to gain access to the class’s protected members in order to expose new state modifying behavior to its clients.

Other Quick Examples

Here are some other places that the Decorator pattern is used:

  1. GUI scenarios where a GUI component may have many tangentially related properties (e.g. a window may have scrollbars, which are not really intrinsic to the Window itself, but handy to be able to add)
  2. “Stream” objects (Java) that add behavior to application I/O by decorating the basic I/O implementation.
  3. Anywhere that there is a significant desire to extend the main functionality of an object hierarchy, such as a series of customizations to an invoice or order object.

A Good Fit – When to Use

The Decorator pattern makes sense to use if you have an object hierarchy that you want to keep pretty much as-is, but you want to add some custom, kind of one-off behavior to it. In the example above, we like the employee hierarchy and don’t really want to clutter it up, but we would like to capture the fact that employees can also occasionally have other, custom behaviors. This makes senses if we extend the example to the GUI components like windows as well. We may sometimes want Windows to have scrollbars, but that doesn’t mean there is a need to have ScrollbarWindow, HorizontalScrollbarWindow, VerticalScrollbarWindow, BothScrollbarWindow, etc for every conceivable type of window.

In fact, that type of combinatorial explosion of types is another definite call for the Decorator pattern. The pattern is a good fit for adding one-off behavior to object hierarchies, but it’s pretty much a must if you find yourself in a situation where simple inheritance would mean defining something like n! new classes for each behavior you want. If you find yourself saying “well, I’d need a HorizontalScrollbarDialogWindow and a HorizontalScrollbarNormalWindow, and a VerticalScrollbarDialogWindow, etc”, stop and give serious though to Decorator.

Square Peg, Round Hole – When Not to Use

This pattern may not be necessary for certain scenarios. Consider our working example above, and forget all of the other “hats” employees can wear but the Safety Team. If we knew this was the only other thing to be modeled, it might be worth having a SafetyTeam object that stored a collection of employee objects. This would allow all members of the safety team to be identified. Granted, you wouldn’t get it as part of the employee bio, but perhaps that could be achieved in another way. Point is, Decorator may be overkill if there isn’t much decoration going on.

Decorator also may not fit if you have no combinatorial explosion and significant control over and flexibility with the object hierarchy. It’s not an option that I personally like, and I think it’s a bit clumsy, but we could have achieved some of the functionality above with the Employee base class having properties for IsSafetyTeamMember and IsHighPerformer and IsSoftballPlayer. If we knew that we were limited to these three (and thus not building an outhouse), this rigid design would suffice.

So, the point is that having and dealing with some existing object hierarchy does not automatically mean that the Decorator pattern is a good fit. It introduces some design complexity and potential understanding issues, so it should be introduced to solve a real, current problem, rather than a hypothetical future one.

So What? Why is this Better?

As demonstrated above, Decorator makes code a lot cleaner in situations where responsibilities need to be added in ad-hoc fashion to an existing object hierarchy. This is particularly true when the new responsibilities are somewhat tangential to the main hierarchy. Using this pattern allows you to manipulate protected members of the class in question without sub-classing it directly, and to present an object to clients that looks uniform and hides the trickery that you’ve pulled.

Your inheritance hierarchies when using this pattern will remain both shallower and narrower, which definitely facilitates better understanding of code. But, you won’t have to sacrifice any flexibility to get this more manageable inheritance tree. And, in the end, you’ll save yourself the ugliness of getting into a situation where the number of classes you have are described in terms of factorial.

By

Composite

Quick Information/Overview

Pattern Type Structural
Applicable Language/Framework Agnostic OOP
Pattern Source Gang of Four
Difficulty Easy

Up Front Definitions

  1. Component: This is the abstract object that represents any and all members of the pattern
  2. Composite: Derives from component and provides the definition for the class that contains other components
  3. Leaf: A concrete node that encapsulates data/behavior and is not a container for
    other components.
  4. Tree: For our context here, tree describes the structure of all of the components.

The Problem

Let’s say that you get a call in to write a little console application that allows users to make directories, create empty files, and delete the same. The idea is that you can create the whole structure in memory and then dump it to disk in one fell swoop. Marketing thinks this will be a hot seller because it will allow users to avoid the annoyance of disk I/O overhead when planning out a folder structure (you might want to dust off your resume, by the way).

Simple enough, you say. For the first project spring, you’re not going to worry about sub-directories – you’re just going to create something that will handle files and some parent directory.

So, you create the following class (you probably create it with actual input validation, but I’m trying to stay focused on the design pattern):

public class DirectoryStructure
{
    private const string DefaultDirectory = ".";

    private readonly List<string> _filenames = new List<string>();

    private string _directory = DefaultDirectory;

    public string RootDirectory { get { return _directory; } set { _directory = string.IsNullOrEmpty(value) ? DefaultDirectory : value; } }

    public void AddFile(string filename)
    {
        _filenames.Add(filename);
        _filenames.Sort();
    }

    public void DeleteFile(string filename)
    {
        if (_filenames.Contains(filename))
        {
            _filenames.Remove(filename);
        }
    }

    public void PrintStructure()
    {
        Console.WriteLine("Starting in " + RootDirectory);
        _filenames.ForEach(filename => Console.WriteLine(filename));
    }

    public void CreateOnDisk()
    {
        if (!Directory.Exists(RootDirectory))
        {
            Directory.CreateDirectory(RootDirectory);
        }

        _filenames.ForEach(filename => File.Create(filename));
    }
}

Client code is as follows:

static void Main(string[] args)
{
    var myStructure = new DirectoryStructure();

    myStructure.AddFile("file1.txt");
    myStructure.AddFile("file2.txt");
    myStructure.AddFile("file3.txt");
    myStructure.DeleteFile("file2.txt");

    myStructure.PrintStructure();

    Console.Read();

    myStructure.CreateOnDisk();
}

That’s all well and good, so you ship and start work on sprint number 2, which includes the story that users want to be able to create one level of sub-directories. You do a bit of refactoring, deciding to make root a constructor parameter instead of a settable property, and then get to work on this new story.

You wind up with the following:

public class DirectoryStructure
{
    private const string DefaultDirectory = ".";

    private readonly List<string> _filenames = new List<string>();
    private readonly List<string> _directories = new List<string>();
    private readonly Dictionary<string, List<string>> _subDirectoryFilenames = new Dictionary<string, List<string>>();

    private readonly string _root;

    public DirectoryStructure(string root = null)
    {
        _root = string.IsNullOrEmpty(root) ? DefaultDirectory : root;
    }


    public void AddFile(string filename)
    {
        _filenames.Add(filename);
        _filenames.Sort();
    }

    public void AddFile(string subDirectory, string filename)
    {
        if (!_directories.Contains(subDirectory))
        {
            AddDirectory(subDirectory);
        }
        _subDirectoryFilenames[subDirectory].Add(filename);
    }

    public void AddDirectory(string directoryName)
    {
        _directories.Add(directoryName);
        _subDirectoryFilenames[directoryName] = new List<string>();
    }

    public void DeleteDirectory(string directoryName)
    {
        if (_directories.Contains(directoryName))
        {
            _directories.Remove(directoryName);
            _subDirectoryFilenames[directoryName] = null;
        }
    }

    public void DeleteFile(string filename)
    {
        if (_filenames.Contains(filename))
        {
            _filenames.Remove(filename);
        }
    }

    public void DeleteFile(string directoryName, string filename)
    {
        if (_directories.Contains(directoryName) && _subDirectoryFilenames[directoryName].Contains(filename))
        {
            _subDirectoryFilenames[directoryName].Remove(filename);
        }
    }

    public void PrintStructure()
    {
        Console.WriteLine("Starting in " + _root);
        foreach (var myDir in _directories)
        {
            Console.WriteLine(myDir);
            _subDirectoryFilenames[myDir].ForEach(filename => Console.WriteLine("\t" + filename));
        }
        _filenames.ForEach(filename => Console.WriteLine(filename));
    }

    public void CreateOnDisk()
    {
        if (!Directory.Exists(_root))
        {
            Directory.CreateDirectory(_root);
        }

        foreach (var myDir in _directories)
        {
            Directory.CreateDirectory(Path.Combine(_root, myDir));
            _subDirectoryFilenames[myDir].ForEach(filename => File.Create(Path.Combine(myDir, filename)));
        }
        _filenames.ForEach(filename => File.Create(filename));
    }
}

and client code:

static void Main(string[] args)
{
    var myStructure = new DirectoryStructure();

    myStructure.AddFile("file1.txt");
    myStructure.AddDirectory("firstdir");
    myStructure.AddFile("firstdir", "hoowa");
    myStructure.AddDirectory("seconddir");
    myStructure.AddFile("seconddir", "hoowa");
    myStructure.DeleteDirectory("seconddir");
    myStructure.AddFile("file2.txt");
    myStructure.AddFile("file3.txt");
    myStructure.DeleteFile("file2.txt");

    myStructure.PrintStructure();

    Console.Read();

    myStructure.CreateOnDisk();
}

Yikes. That’s starting to smell. You’ve had to add overloads for adding file and deleting file, add methods for add/delete directory, and append logic to print and create. Basically, you’ve had to either touch or overload every method in the class. Generally, that’s a surefire sign that you’re doin’ it wrong. But, no time for that now because here comes the third sprint. This time, the business wants two levels of nesting. So, you get started and you see just how ugly things are going to get. I won’t provide all of your code here so that the blog can keep a PG rating, but here’s the first awful thing that you had to do:

private readonly List<string> _filenames = new List<string>();
private readonly List<string> _directories = new List<string>();
private readonly Dictionary<string, List<string>> _subDirectoryFilenames = new Dictionary<string, List<string>>();
private readonly Dictionary<string, List<string>> _subDirectoryNames;
private readonly Dictionary<string, Dictionary<string, List<string>>> _subSubDirectoryFilenames = new Dictionary<string, Dictionary<string, List<string>>>();

You also had to modify or overload every method yet again, bringing the method total to 12 and the complexity of each method to a larger figure. You’re pretty sure you can’t keep this up for an arbitrary number of sprints, so you send out your now-dusted off resume and foist this stinker on the hapless person replacing you.

So, What to Do?

What went wrong here is relatively easy to trace. Let’s backtrack to the start of the second sprint when we needed to support sub-directories. As we’ve seen in some previous posts in this series, the first foray at implementing the second sprint gives off the code smell, primitive obsession. This is a code smell wherein bunches of primitive types (string, int, etc) are used in ad-hoc fashion to operate as some kind of ad-hoc class.

In this case, the smell is coming from the series of lists and dictionaries centering around strings to represent file and directory names. As the sprints go on, it’s time to recognize that there is a need for at least one class here, so let’s create it and call it “SpeculativeDirectory” (so as not to confuse it with the C# Directory class).

public class SpeculativeDirectory
{
    private const string DefaultDirectory = ".";

    private readonly HashSet<SpeculativeDirectory> _subDirectories = new HashSet<SpeculativeDirectory>();

    private readonly HashSet<string> _files = new HashSet<string>();

    private readonly string _name = string.Empty;
    public string Name { get { return _name; } }

    public SpeculativeDirectory(string name)
    {
        _name = string.IsNullOrEmpty(name) ? DefaultDirectory : name;
    }

    public SpeculativeDirectory GetDirectory(string directoryName)
    {
        return _subDirectories.FirstOrDefault(dir => dir.Name == directoryName);
    }

    public string GetFile(string filename)
    {
        return _files.FirstOrDefault(file => file == filename);
    }

    public void Add(string file)
    {
        if(!string.IsNullOrEmpty(file))
            _files.Add(file);
    }

    public void Add(SpeculativeDirectory directory)
    {
        if (directory != null && !string.IsNullOrEmpty(directory.Name))
        {
            _subDirectories.Add(directory);
        }
    }

    public void Delete(string file)
    {
        _files.Remove(file);
    }

    public void Delete(SpeculativeDirectory directory)
    {
        _subDirectories.Remove(directory);
    }

    public void PrintStructure(int depth)
    {
        string myTabs = new string(Enumerable.Repeat<char>('\t', depth).ToArray());
        Console.WriteLine(myTabs + Name);

        foreach (var myDir in _subDirectories)
        {
            myDir.PrintStructure(depth + 1);
        }
        foreach (var myFile in _files)
        {
            Console.WriteLine(myTabs + "\t" + myFile);
        }
    }

    public void CreateOnDisk(string path)
    {
        string myPath = Path.Combine(path, Name);

        if (!Directory.Exists(myPath))
        {
            Directory.CreateDirectory(myPath);
        }

        _files.ToList().ForEach(file => File.Create(Path.Combine(myPath, file)));
        _subDirectories.ToList().ForEach(dir => dir.CreateOnDisk(myPath));
    }

}

And, the DirectoryStructure class is now:

public class DirectoryStructure
{
    private readonly SpeculativeDirectory _root;

    public DirectoryStructure(string root = null)
    {
        _root = new SpeculativeDirectory(root);
    }


    public void AddFile(string filename)
    {
        _root.Add(filename);
    }

    public void AddFile(string directoryName, string filename)
    {
        var myDirectory = _root.GetDirectory(directoryName);
        if (myDirectory != null)
        {
            myDirectory.Add(filename);
        }
    }

    public void AddDirectory(string directoryName)
    {
        _root.Add(new SpeculativeDirectory(directoryName));
    }

    public void DeleteFile(string filename)
    {
        _root.Delete(filename);
    }

    public void DeleteFile(string directoryName, string filename)
    {
        var myDirectory = _root.GetDirectory(directoryName);
        if (myDirectory != null)
        {
            myDirectory.Delete(filename);
        }
    }

    public void DeleteDirectory(string directoryName)
    {
        _root.Delete(directoryName);
    }

    public void PrintStructure()
    {
        _root.PrintStructure(0);
    }

    public void CreateOnDisk()
    {
        _root.CreateOnDisk(string.Empty);
    }
}

The main program that invokes this class is unchanged. So, now, notice the Structure of SpeculativeDirectory. It contains a collection of strings, representing files, and a collection of SpeculativeDirectory, representing sub-directories. For things like PrintStructure() and CreateOnDisk(), notice that we’re now taking advantage of recursion.

This is extremely important because what we’ve done here is future proofed for sprint 3 much better than before. It’s still going to be ugly and involve more and more overloads, but at least it won’t require defining increasingly nested (and insane) dictionaries in the DirectoryStructure class.

Speaking of DirectoryStructure, does this class serve a purpose anymore? Notice that the answer is “no, not really”. It basically defines a root directory and wraps its operations. So, let’s get rid of that before we do anything else.

To do that, we can just change the client code to the following and delete DirectoryStructure:

static void Main(string[] args)
{
    var myDirectory = new SpeculativeDirectory(".");
    myDirectory.Add("file1.txt");
    myDirectory.Add(new SpeculativeDirectory("firstdir"));
    myDirectory.GetDirectory("firstdir").Add("hoowa");
    var mySecondDir = new SpeculativeDirectory("seconddir");
    myDirectory.Add(mySecondDir);
    myDirectory.GetDirectory("seconddir").Add("hoowa");
    myDirectory.Delete(mySecondDir);
    myDirectory.Add("file2.txt");
    myDirectory.Add("file3.txt");
    myDirectory.Delete("file2.txt");

    myDirectory.PrintStructure(0);

    Console.Read();

    myDirectory.CreateOnDisk(".");

}

Now, we’re directly using the directory object and we’ve removed a class in addition to cleaning things up. The API still isn’t perfect, but we’re gaining some ground. So, let’s turn our attention now to cleaning up SpeculativeDirectory. Notice that we have a bunch of method pairs: GetDirectory/GetFile, Add(Directory)/Add(string), Delete(Directory)/Delete(string). This kind of duplication is a code smell — we’re begging for polymorphism here.

Notice that we are performing operations routinely on SpeculativeDirectory and performing the same operations on the string representing a file. It is worth noting that if we had a structure where file and directory inherited from a common base or implemented a common interface, we could perform operations on them just once. And, as it turns out, this is the crux of the command pattern.

Let’s see how that looks. First, we’ll define a SpeculativeFile object:

public class SpeculativeFile
{
    private readonly string _name;
    public string Name { get; }

    public SpeculativeFile(string name)
    {
        _name = name ?? string.Empty;
    }

    public void Print(int depth)
    {
        string myTabs = new string(Enumerable.Repeat<char>('\t', depth).ToArray());
        Console.WriteLine(myTabs + Name);
    }

    public void CreateOnDisk(string path)
    {
        File.Create(Path.Combine(path, _name));
    }
}

This is pretty simple and straightforward. The file class knows how to print itself and how to create itself on disk, and it knows that it has a name. Now our task is to have a common inheritance model for file and directory. We’ll go with an abstract base class since they are going to have common implementations and file won’t have an implementation, per se, for add and delete. Here is the common base:

public abstract class SpeculativeComponent
{
    private readonly string _name;
    public string Name { get { return _name; } }

    private readonly HashSet<SpeculativeComponent> _children = new HashSet<SpeculativeComponent>();
    protected HashSet<SpeculativeComponent> Children { get { return _children; } }

    public SpeculativeComponent(string name)
    {
        _name = name ?? string.Empty;
    }

    public virtual SpeculativeComponent GetChild(string name) { return null; }

    public virtual void Add(SpeculativeComponent component) { }

    public virtual void DeleteByName(string name) { }

    public void Print()
    {
        Print(0);
    }

    public void CreateOnDisk()
    {
        CreateOnDisk(Name);
    }

    protected virtual void Print(int depth)
    {
        string myTabs = new string(Enumerable.Repeat<char>('\t', depth).ToArray());
        Console.WriteLine(myTabs + Name);

        foreach (SpeculativeComponent myChild in _children)
        {
            myChild.Print(depth + 1);
        }
    }

    protected virtual void CreateOnDisk(string path)
    {
        foreach (var myChild in _children)
        {
            myChild.CreateOnDisk(Path.Combine(path, Name));
        }
    }
        
}

A few things to note here. Fist of all, our recursive Print() and CerateOnDisk() methods are divided into two methods each, one public, one private. This is continue to allow for recursive calls but without awkwardly forcing the user to pass in zero or empty or whatever for path/depth. Notice also that common concerns for the two different types of nodes (file and directory) are now here, some stubbed as do-nothing virtuals and others implemented. The reason for this is conformance to the pattern — while files and directories share some overlap, some operations are clearly not meaningful for both (particularly adding/deleting and anything else regarding children). So, you do tend to wind up with the leaves (SpeculativeFile) ignoring inherited functionality, this is generally a small price to pay for avoiding duplication and the ability to recurse to n levels.

With this base class, we have pulled a good bit of functionality out of the file class, which is now this:

public class SpeculativeFile : SpeculativeComponent
{
    public SpeculativeFile(string name) : base(name) {}

    protected override void CreateOnDisk(string path)
    {
        File.Create(Path.Combine(path, Name));
        base.CreateOnDisk(path);
    }
}

Pretty simple. With this new base class, here is new SpeculativeDirectory class:

public class SpeculativeDirectory : SpeculativeComponent
{
    public SpeculativeDirectory(string name) : base(name) { }

    public override SpeculativeComponent GetChild(string name)
    {
        return Children.FirstOrDefault(child => child.Name == name);
    }

    public override void Add(SpeculativeComponent child)
    {
        if(child != null)
            Children.Add(child);
    }

    public override void DeleteByName(string name)
    {
        var myMatchingChild = Children.FirstOrDefault(child => child.Name == name);
        if (myMatchingChild != null)
        {
            Children.Remove(myMatchingChild);
        }
    }

    protected override void CreateOnDisk(string path)
    {
        string myPath = Path.Combine(path, Name);
        if (!Directory.Exists(myPath))
        {
            Directory.CreateDirectory(myPath);
        }

        base.CreateOnDisk(path);
    }
}

Wow. A lot more focused and easy to reason about, huh? And, finally, here is the new API:

static void Main(string[] args)
{
    var myDirectory = new SpeculativeDirectory(".");
    myDirectory.Add(new SpeculativeFile("file1.txt"));
    myDirectory.Add(new SpeculativeDirectory("firstdir"));
    myDirectory.GetChild("firstdir").Add(new SpeculativeFile("hoowa"));
    myDirectory.Add(new SpeculativeDirectory("seconddir"));
    myDirectory.GetChild("seconddir").Add(new SpeculativeFile("hoowa"));
    myDirectory.DeleteByName("seconddir");
    myDirectory.Add(new SpeculativeFile("file2.txt"));
    myDirectory.Add(new SpeculativeFile("file3.txt"));
    myDirectory.DeleteByName("file2.txt");

    myDirectory.Print();

    Console.Read();

    myDirectory.CreateOnDisk();

}

Even the API has improved since our start. We’re no longer creating this unnatural “structure” object. Now, we just create root directory and add things to it with simple API calls in kind of a fluent interface.

Now, bear in mind that this is not as robust as it could be, but that’s what you’ll do in sprint 3, since your sprint 2 implemented sub-directories for N depths of recursion and not just one. :)

A More Official Explanation

According to dofactory, the Composite Pattern’s purpose is to:

Compose objects into tree structures to represent part-whole hierarchies. Composite lets clients treat individual objects and compositions of objects uniformly.

What we’ve accomplished in rescuing the speculative directory creation app is to allow the main program to perform operations on nodes in a directory tree without caring whether they are files or directories (with the exception of actually creating them). This is most evident in the printing and writing to disk. Whether we created a single file or an entire directory hierarchy, we would treat it the same for creating on disk and for printing.

The elegant concept here is that we can build arbitrarily large structures with arbitrary conceptual tree structures and do things to them uniformly. This is important because it allows the encapsulation of tree node behaviors within the objects themselves. There is no master object like the original DirectoryStructure that has to walk the tree, deciding how to treat each element. Any given node in the tree knows how to treat itself and its sub-elements.

Other Quick Examples

Other places where one might use the composite pattern include:

  1. GUI composition where GUI widgets can be actual widgets or widget containers (Swing java, WPF XAML, etc).
  2. Complex Chain of Responsibility structures where some nodes handle events and others simply figure out who to hand them over to
  3. A menu structure where nodes can either be actions or sub-menus.

A Good Fit – When to Use

The pattern is useful when (1) you want to represent an object hierarchy and (2) there is some context in which you want to be able to ignore differences between the objects and treat them uniformly as a client. This is true in our example here in the context of printing the structure and writing it to disk. The client doesn’t care whether something is a file or a directory – he just wants to be able to iterate over the whole tree performing some operation.

Generally speaking, this is good to use anytime you find yourself looking at a conceptual tree-like structure and iterating over the whole thing in the context of a control flow statement (if or case). In our example, this was achieved indirectly by different method overloads, but the result in the end would have been the same if we had been looking at a single method with a bit of logic saying “if node is a file, do x, otherwise, do y”.

Square Peg, Round Hole – When Not to Use

There are some subtle considerations here. You don’t want to use this if all of your nodes can be the same type of object, such as the case of some simple tree structure. If you were, for example, creating a sorted tree for fast lookup, where each node had some children and a payload, this would not be an appropriate use of composite.

Another time you wouldn’t want to use this is if a tree structure is not appropriate for representing what you want to do. If our example had not had any concept of recursion and were only for representing a single directory, this would not have been appropriate.

So What? Why is this Better?

The code cleanup here speaks for itself. We were able to eliminate a bunch of method overloads (or conditional branching if we had gone that way), making the code more maintainable. In addition, it allows elimination of a structure that rots as it grows — right out of the box, the composite pattern with its tree structure allows handling of arbitrarily deep and wide tree structures. And, finally, it allows clients to walk the tree structure without concerning themselves with what kind of nodes its processing and how to navigate to the next nodes.

By

Command

Quick Information/Overview

Pattern Type Behavioral
Applicable Language/Framework Agnostic OOP
Pattern Source Gang of Four
Difficulty Easy – Moderate

Up Front Definitions

  1. Invoker: This object services clients by exposing a method that takes a command as a parameter and invoking the command’s execute
  2. Receiver: This is the object upon which commands are performed – its state is mutated by them

The Problem

Let’s say you get a request from management to write an internal tool. A lot of people throughout the organization deal with XML documents and nobody really likes dealing with them, so you’re tasked with writing an XML document builder. The user will be able to type in node names and pick where they go and whatnot. Let’s also assume (since this post is not about the mechanics of XML) that all XML documents consist of a root node called “Root” and only child nodes of root.

The first request that you get in is the aforementioned adding. So, knowing that you’ll be getting more requests, your first design decision is to create a DocumentBuilder class and have the adding implemented there.

/// <summary>This class is responsible for doing document build operations</summary>
public class DocumentBuilder
{
    /// <summary>This is the document that we're doing to be modifying</summary>
    private readonly XDocument _document;

    /// <summary>Initializes a new instance of the DocumentBuilder class.</summary>
    /// <param name="document"></param>
    public DocumentBuilder(XDocument document = null)
    {
        _document = document ?? new XDocument(new XElement("Root"));
    }

    /// <summary>Add a node to the document</summary>
    /// <param name="elementName"></param>
    public void AddNode(string elementName)
    {
        _document.Root.Add(new XElement(elementName));
    }
}

//Client code:
var myInvoker = new DocumentBuilder();
myInvoker.AddNode("Hoowa!");

So far, so good. Now, a request comes in that you need to be able to do undo and redo on your add operation. Well, that takes a little doing, but after 10 minutes or so, you’ve cranked out the following:

public class DocumentBuilder
{
    /// <summary>This is the document that we're doing to be modifying</summary>
    private readonly XDocument _document;

    /// <summary>Store things here for undo</summary>
    private readonly Stack<string> _undoItems = new Stack<string>();

    /// <summary>Store things here for redo</summary>
    private readonly Stack<string> _redoItems = new Stack<string>();

    /// <summary>Initializes a new instance of the DocumentBuilder class.</summary>
    /// <param name="document"></param>
    public DocumentBuilder(XDocument document = null)
    {
        _document = document ?? new XDocument(new XElement("Root"));
    }

    /// <summary>Add a node to the document</summary>
    /// <param name="elementName"></param>
    public void AddNode(string elementName)
    {
        _document.Root.Add(new XElement(elementName));
        _undoItems.Push(elementName);
        _redoItems.Clear();
    }

    /// <summary>Undo the previous steps operations</summary>
    public void Undo(int steps)
    {
        for (int index = 0; index < steps; index++)
        {
            var myName = _undoItems.Pop();
            _document.Root.Elements(myName).Remove();
            _redoItems.Push(myName);
        }
    }

    /// <summary>Redo the number of operations given by steps</summary>
    public void Redo(int steps)
    {
        for (int index = 0; index < steps; index++)
        {
            var myName = _redoItems.Pop();
            _document.Root.Add(new XElement(myName));
            _undoItems.Push(myName);
        }
    }
}

Not too shabby – things get popped from each stack and added to the other as you undo/redo, and the redo stack gets cleared when you start a new “branch”. So, you’re pretty proud of this implementation and you’re all geared up for the next set of requests. And, here it comes. Now, the builder must be able to print the current document to the console. Hmm… that gets weird, since printing to the console is not really representable by a string in the stacks. The first thing you think of doing is making string.empty represent a print operation, but that doesn’t seem very robust, so you tinker and modify until you have the following:

public class DocumentBuilder
{
    /// <summary>This is the document that we're doing to be modifying</summary>
    private readonly XDocument _document;

    /// <summary>This defines what type of operation that we're doing</summary>
    private enum OperationType
    {
        Add,
        Print
    }

    /// <summary>Store things here for undo</summary>
    private readonly Stack<Tuple<OperationType, string>> _undoItems = new Stack<Tuple<OperationType, string>>();

    /// <summary>Store things here for redo</summary>
    private readonly Stack<Tuple<OperationType, string>> _redoItems = new Stack<Tuple<OperationType, string>>();

    /// <summary>Initializes a new instance of the DocumentBuilder class.</summary>
    /// <param name="document"></param>
    public DocumentBuilder(XDocument document = null)
    {
        _document = document ?? new XDocument(new XElement("Root"));
    }

    /// <summary>Add a node to the document</summary>
    /// <param name="elementName"></param>
    public void AddNode(string elementName)
    {
        _document.Root.Add(new XElement(elementName));
        _undoItems.Push(new Tuple<OperationType, string>(OperationType.Add, elementName));
        _redoItems.Clear();
    }

    /// <summary>Print out the document</summary>
    public void PrintDocument()
    {
        Print();

        _redoItems.Clear();
        _undoItems.Push(new Tuple<OperationType, string>(OperationType.Print, string.Empty));
    }

    /// <summary>Undo the previous steps operations</summary>
    public void Undo(int steps)
    {
        for (int index = 0; index < steps; index++)
        {
            var myOperation = _undoItems.Pop();
            switch (myOperation.Item1)
            {
                case OperationType.Add:
                    _document.Root.Elements(myOperation.Item2).Remove();
                    _redoItems.Push(myOperation);
                    break;
                case OperationType.Print:
                    Console.Out.WriteLine("Sorry, but I really can't undo a print to screen.");
                    _redoItems.Push(myOperation);
                    break;
            }
        }
    }

    /// <summary>Redo the number of operations given by steps</summary>
    public void Redo(int steps)
    {
        for (int index = 0; index < steps; index++)
        {
            var myOperation = _redoItems.Pop();
            switch (myOperation.Item1)
            {
                case OperationType.Add:
                    _document.Root.Elements(myOperation.Item2).Remove();
                    _undoItems.Push(myOperation);
                    break;
                case OperationType.Print:
                    Print();
                    _undoItems.Push(myOperation);
                    break;
            }
        }
    }

    private void Print()
    {
        var myBuilder = new StringBuilder();
        Console.Out.WriteLine("\nDocument contents:\n");
        using (var myWriter = XmlWriter.Create(myBuilder, new XmlWriterSettings() { Indent = true, IndentChars = "\t" }))
        {
            _document.WriteTo(myWriter);
        }
        Console.WriteLine(myBuilder.ToString());
    }
}

Yikes, that’s starting to smell a little. But, hey, you extracted a method for the print, and you’re keeping things clean. Besides, you’re fairly proud of your little tuple scheme for recording what kind of operation it was in addition to the node name. And, there’s really no time for 20/20 hindsight because management loves it. You need to implement something that lets you update a node’s name ASAP.

Oh, and by the way, they also want to be able to print the output to a file instead of the console. Oh, and by the by the way, you know what would be just terrific? If you could put something in to switch the position of two nodes in the file. They know it’s a lot to ask right now, but you’re a rock star and they know you can handle it.

So, you buy some Mountain Dew and pull an all nighter. You watch as the undo and redo case statements grow vertically and as your tuple grows horizontally. The tuple now has an op code and an element name like before, but it has a third argument that means the new name for update, and when the op-code is swap, the second and third arguments are the two nodes to swap. It’s ugly (so ugly I’m not even going to code it for the example), but it works.

And, it’s a success! Now, the feature requests really start piling up, and not only are stakeholders using your app, but other programmers have started using your API. There’s really no time to reflect on the design now – you have a ton of new functionality to implement. And, as you do it, the number of methods in your builder will grow as each new feature is added, the size of the case statements in undo and redo will grow with each new feature is added, and the logic for parsing your swiss-army knife tuple is going to get more and more convoluted.

By the time this thing is feature complete, it’s going to take a 45 page developer document to figure out what on Earth is going on. Time to start putting out resumes and jump off this sinking ship.

So, What to Do?

Before discussing what to do, let’s first consider what went wrong. There are two main issues here that have contributed to the code rot. The first and most obvious is the decision to “wing it” with the Tuple solution that is, in effect, a poor man’s type. Instead of a poor man’s type, why not an actual type? The second issue is a bit more subtle, but equally important — violation of the open/closed principle.

To elaborate, consider the original builder that simply added nodes to the XDocument and the subsequent change to implement undo and redo of this operation. By itself, this was fine and cohesive. But, when the requirements started to come in about more operations, this was the time to go in a different design direction. This may not be immediately obvious, but a good question to ask during development is “what happens if I get more requests like this?” When the class had “AddNode”, “Undo” and “Redo”, and the request for “PrintDocument” came in, it was worth noting that you were cobbling onto an existing class. It also would have been reasonable to ask, “what if I’m asked to add more operations?”

Asking this question would have resulted in the up-front realization that each new operation would require another method to be added to the class, and another case statement to be added to two existing methods. This is not a good design — especially if you know more such requests are coming. Having an implementation where new the procedure for accommodating new functionality is “tack another method onto class X” and/or “open method X and add more code” is a recipe for code rot.

So, let’s consider what we could have done when the request for document print functionality. Instead of this tuple thing, let’s create another implementation. What we’re going to do is forget about creating Tuples and forget about the stacks of string, and think in terms of a command object. Now, at the moment, we only have one command object, but we know that we’ve got a requirement that’s going to call for a second one, so let’s make it polymorphic. I’m going to introduce the following interface:

public interface IDocumentCommand
{
    /// <summary>Document (receiver) upon which to operate</summary>
    XDocument Document { get; set; }

    /// <summary>Execute the command</summary>
    void Execute();
        
    /// <summary>Revert the execution of the command</summary>
    void UndoExecute();

}

This is what will become the command in the command pattern. Notice that the interface defines two conceptual methods – execution and negation of the execution (which should look a lot like “do” and “undo”), and it’s also going to be given the document upon which to do its dirty work.

Now, let’s take a look at the add implementer:

public class AddNodeCommand : IDocumentCommand
{
    private readonly string _nodeName;

    private XDocument _document = new XDocument();
    public XDocument Document { get { return _document; } set { _document = value ?? _document; } }

    /// <summary>Initializes a new instance of the AddNodeCommand class.</summary>
    /// <remarks>Note the extra parameter here -- this is important.  This class essentially conceptually
    /// an action, so you're more used to seeing things in method form like this.  We pass in the "method" parameters
    /// to the constructor because we're encapsulating an action as an object with state</remarks>
    public AddNodeCommand(string nodeName)
    {
        _nodeName = nodeName ?? string.Empty;
    }
    public void Execute()
    {
        Document.Root.Add(new XElement(_nodeName));
    }

    public void UndoExecute()
    {
        Document.Root.Elements(_nodeName).Remove();
    }
}

Pretty straightforward (in fact a little too straightforward – in a real implementation, there should be some error checking about the state of the document). When created, this object is seeded with the name of the node that it’s supposed to create. The document is a setter dependency, and the two operations mutate the XDocument, which is our “receiver” in the command pattern, according to the pattern’s specification.

Let’s have a look at what our new Builder implementation now looks like before adding print document:

public class DocumentBuilder
{
    /// <summary>This is the document that we're doing to be modifying</summary>
    private readonly XDocument _document;

    /// <summary>Store things here for undo</summary>
    private readonly Stack<IDocumentCommand> _undoItems = new Stack<IDocumentCommand>();

    /// <summary>Store things here for redo</summary>
    private readonly Stack<IDocumentCommand> _redoItems = new Stack<IDocumentCommand>();

    /// <summary>Initializes a new instance of the DocumentBuilder class.</summary>
    /// <param name="document"></param>
    public DocumentBuilder(XDocument document = null)
    {
        _document = document ?? new XDocument(new XElement("Root"));
    }

    /// <summary>Add a node to the document</summary>
    /// <param name="elementName"></param>
    public void AddNode(string elementName)
    {
        var myCommand = new AddNodeCommand(elementName)  { Document = _document };
        myCommand.Execute();
        _undoItems.Push(myCommand);
        _redoItems.Clear();
    }

    /// <summary>Undo the previous steps operations</summary>
    public void Undo(int steps)
    {
        for (int index = 0; index < steps; index++)
        {
            var myCommand = _undoItems.Pop();
            myCommand.UndoExecute();
            _redoItems.Push(myCommand);
        }
    }

    /// <summary>Redo the number of operations given by steps</summary>
    public void Redo(int steps)
    {
        for (int index = 0; index < steps; index++)
        {
            var myCommand = _redoItems.Pop();
            myCommand.Execute();
            _undoItems.Push(myCommand);
        }
    }
}

Notice that the changes to this class are subtle but interesting. We now have stacks of commands rather than strings (or, later, tuples). Notice that undo and redo now delegate the business of executing the command to the command object, rather than figuring out what kind of operation it is and doing it themselves. This is critical to conforming to the open/closed principle, as we’ll see shortly.

Now that we’ve performed our refactoring, let’s add the print document functionality. This is now going to be accomplished by a new implementation of IDocumentCommand:

public class PrintCommand : IDocumentCommand
{
    private XDocument _document = new XDocument();
    public XDocument Document { get { return _document; } set { _document = value ?? _document; } }

    /// <summary>Execute the print command</summary>
    public void Execute()
    {
        var myBuilder = new StringBuilder();
        Console.Out.WriteLine("\nDocument contents:\n");
        using (var myWriter = XmlWriter.Create(myBuilder, new XmlWriterSettings() { Indent = true, IndentChars = "\t" }))
        {
            Document.WriteTo(myWriter);
        }
        Console.WriteLine(myBuilder.ToString());
    }

    /// <summary>Undo the print command (which, you can't)</summary>
    public void UndoExecute()
    {
        Console.WriteLine("\nDude, you can't un-ring that bell.\n");
    }
}

Also pretty simple. Let’s now take a look at how we implement this in our “invoker”, the DocumentBuilder:

public class DocumentBuilder
{
    /// <summary>This is the document that we're doing to be modifying</summary>
    private readonly XDocument _document;

    /// <summary>Store things here for undo</summary>
    private readonly Stack<IDocumentCommand> _undoItems = new Stack<IDocumentCommand>();

    /// <summary>Store things here for redo</summary>
    private readonly Stack<IDocumentCommand> _redoItems = new Stack<IDocumentCommand>();

    /// <summary>Initializes a new instance of the DocumentBuilder class.</summary>
    /// <param name="document"></param>
    public DocumentBuilder(XDocument document = null)
    {
        _document = document ?? new XDocument(new XElement("Root"));
    }

    /// <summary>Add a node to the document</summary>
    /// <param name="elementName"></param>
    public void AddNode(string elementName)
    {
        var myCommand = new AddNodeCommand(elementName) { Document = _document };
        myCommand.Execute();
        _undoItems.Push(myCommand);
        _redoItems.Clear();
    }

    /// <summary>Print the document</summary>
    public void PrintDocument()
    {
        var myCommand = new PrintCommand() { Document = _document};
        myCommand.Execute();
        _undoItems.Push(myCommand);
        _redoItems.Clear();
    }

    /// <summary>Undo the previous steps operations</summary>
    public void Undo(int steps)
    {
        for (int index = 0; index < steps; index++)
        {
            var myCommand = _undoItems.Pop();
            myCommand.UndoExecute();
            _redoItems.Push(myCommand);
        }
    }

    /// <summary>Redo the number of operations given by steps</summary>
    public void Redo(int steps)
    {
        for (int index = 0; index < steps; index++)
        {
            var myCommand = _redoItems.Pop();
            myCommand.Execute();
            _undoItems.Push(myCommand);
        }
    }
}

Lookin’ good! Observe that undo and redo do not change at all. Our invoker now creates a command for each operation, and delegate its work to the receiver on behalf of the client code. As we continue to add more commands, we do not ever have to modify undo and redo.

But, we still don’t have it quite right. The fact that we need to add a new class and a new method each time a new command is added is still a violation of the open/closed principle, even though we’re better off than before. The whole point of what we’re doing here is separating the logic of command execution (and undo/redo and, perhaps later, indicating whether a command can currently be executed or not) from the particulars of the commands themselves. We’re mostly there, but not quite – the invoker, DocumentBuilder is still responsible for enumerating the different commands as methods and creating the actual command objects. The invoker is still too tightly coupled to the mechanics of the commands.

This is not hard to fix – pass the buck! Let’s look at an implementation where the invoker, instead of creating commands in named methods, just demands the commands:

public class DocumentBuilder
{
    /// <summary>This is the document that the user will be dealing with</summary>
    private readonly XDocument _document;

    /// <summary>This houses commands for undo</summary>
    private readonly Stack<IDocumentCommand> _undoCommands = new Stack<IDocumentCommand>();

    /// <summary>This houses commands for redo</summary>
    private readonly Stack<IDocumentCommand> _redoCommands = new Stack<IDocumentCommand>();

    /// <summary>User can give us an xdocument or we can create our own</summary>
    public DocumentBuilder(XDocument document = null)
    {
        _document = document ?? new XDocument(new XElement("Root"));
    }

    /// <summary>Executes the given command</summary>
    /// <param name="command"></param>
    public void Execute(IDocumentCommand command)
    {
        if (command == null) throw new ArgumentNullException("command", "nope");
        command.Document = _document;
        command.Execute();
        _redoCommands.Clear();
        _undoCommands.Push(command);
    }

    /// <summary>Perform the number of undos given by iterations</summary>
    public void Undo(int iterations)
    {
        for (int index = 0; index < iterations; index++)
        {
            if (_undoCommands.Count > 0)
            {
                var myCommand = _undoCommands.Pop();
                myCommand.UndoExecute();
                _redoCommands.Push(myCommand);
            }
        }
    }

    /// <summary>Perform the number of redos given by iterations</summary>
    public void Redo(int iterations)
    {
        for (int index = 0; index < iterations; index++)
        {
            if (_redoCommands.Count > 0)
            {
                var myCommand = _redoCommands.Pop();
                myCommand.UndoExecute();
                _undoCommands.Push(myCommand);
            }
        }
    }
}

And, there we go. Observe that now, when new commands are to be added, all a maintenance programmer has to do is author a new class. That’s a much better paradigm. Any bugs related to the mechanics of do/undo/redo are completely separate from the commands themselves.

Some might argue that the new invoker/DocumentBuilder lacks expressiveness in its API (having Execute(IDocumentCommand) instead of AddNode(string) and PrintDocument()), but I disagree:

var myInvoker = new DocumentBuilder();
myInvoker.Execute(new AddNodeCommand("Hoowa"));
myInvoker.Execute(new PrintCommand());
myInvoker.Undo(2);
myInvoker.Execute(new PrintCommand());

Execute(AddCommand(nodeName)) seems just as expressive to me as AddNode(nodeName), if slightly more verbose. But even if it’s not, the tradeoff is worth it, in my book. You now have the ability to plug new commands in anytime by implementing the interface, and DocumentBuilder conforms to the open/closed principle — it’s only going to change if there is a bug in the way the do/undo/redo logic is found and not when you add new functionality (incidentally, having only one reason to change also makes it conform to the single responsibility principle).

A More Official Explanation

dofactory defines the command pattern this way:

Encapsulate a request as an object, thereby letting you parameterize clients with different requests, queue or log requests, and support undoable operations.

The central, defining point of this pattern is the idea that a request or action should be an object. This is an important and not necessarily intuitive realization. The natural tendency would be to implement the kind of ad-hoc logic from the initial implementation, since we tend to think of objects as things like “Car” and “House” rather than concepts like “Add a node to a document”.

But, this different thinking leads to the other part of the description – the ability to parameterize clients with different requests. What this means is that since the commands are stored as objects with state, they can encapsulate their own undo and redo, rather than forcing the invoker to do it. The parameterizing is the idea that the invoker operates on passed in command objects rather than doing specific things in response to named methods.

What is gained here is then the ability to put commands into a stack, queue, list, etc, and operate on them without specifically knowing what it is they do. That is a powerful ability since separating and decoupling responsibilities is often hard to accomplish when designing software.

Other Quick Examples

Here are some other places that the command pattern is used:

  1. The ICommand interface in C#/WPF for button click and other GUI events.
  2. Undo/redo operations in GUI applications (i.e. Ctrl-Z, Ctrl-Y).
  3. Implementing transactional logic for persistence (thus providing atomicity for rolling back)

A Good Fit – When to Use

Look to use the command pattern when there is a common set of “meta-operations” surrounding commands. That is, if you find yourself with requirements along the lines of “revert the last action, whatever that action may have been.” This is an indicator that there are going to be operations on the commands themselves beyond simple execution. In scenarios like this, it makes sense to have polymorphic command objects that have some notion of state.

Square Peg, Round Hole – When Not to Use

As always, YAGNI applies. For example, if our document builder were only ever going to be responsible for adding nodes, this pattern would have been overkill. Don’t go implementing the command pattern on any and all actions that your program may take — the pattern incurs complexity overhead in the form of multiple objects and a group of polymorphs.

So What? Why is this Better?

As we’ve seen above, this makes code a lot cleaner in situations where it’s relevant and it makes it conform to best practices (SOLID principles). I believe that you’ll also find that, if you get comfortable with this pattern, you’ll be more inclined to offer richer functionality to clients on actions that they may take.

That is, implementing undo/redo or atomicity may be something you’d resist or avoid as it would entail a great deal of complexity, but once you see that this need not be the case, you might be more willing or even proactive about it.

In, using this pattern where appropriate is better because it provides for cleaner code, fewer maintenance headaches, and more clarity.

By

Chain of Responsibility

Quick Information/Overview

Pattern Type Behavioral
Applicable Language/Framework Agnostic OOP
Pattern Source Gang of Four
Difficulty Easy

Up Front Definitions

N/A

The Problem

Let’s say that you’re doing something reasonably standard. You have some desktop application that deals with a persistence structure (file, web service, remote database, whatever) and displays things for the user. Since it’s not 1996 anymore, you don’t want to treat the user to an endless series of dialog boxes for feedback, so you decide to create some kind of status message scheme, whereby there is a piece of screen real estate that is updated with messages as processing occurs, to give the user feedback. Think of an install wizard:

You get some requirements that you’re to have three types of status messages: informational, warning, and error, to be displayed in black, yellow and red text, respectively. From your extensive experience as a developer, you know that business analysts and users love nothing more than to tinker with the GUI, so you decide that you need a better scheme than simply displaying text and changing its color — you need to encapsulate the message generation logic so that when it is decided that the error messages should really be more of a brick red, you don’t have to do a giant find and replace in your presentation layer. So, you create the following object to which the GUI will bind:

    public class Message
    {
        public virtual string Text { get; set; }
        public Color Color { get; set; }
        public FontWeight Font { get; set; }
    }

Further, you create some classes that understand how to populate these bindable objects:

    public abstract class MessageGenerator
    {
        public const int LowPriority = 0;
        public const int Normal = 1;
        public static int Warning = 2;
        public static int Error = 3;
        public static int Critical = 4;

        public abstract Message GenerateMessage(string messageText);
    }

    public class InformationalMessageGenerator : MessageGenerator
    {
        public override Message GenerateMessage(string messageText)
        {
            return new Message() { Color = Colors.Black, Font = FontWeights.Normal, Text = messageText };
        }
    }

    public class WarningMessageGenerator : MessageGenerator
    {
        public override Message GenerateMessage(string messageText)
        {
            return new Message() { Color = Colors.Yellow, Font = FontWeights.SemiBold, Text = messageText };
        }
    }

    public class ErrorMessageGenerator : MessageGenerator
    {
        public override Message GenerateMessage(string messageText)
        {
            return new Message() { Color = Colors.Red, Font = FontWeights.Bold, Text = messageText };
        }
    }

Now, when the error message needs to be a little lighter than brick red, but a little darker than normal red, and maybe with a hint of purple, you can go to one place, the ErrorMessageGenerator, and you’re done. This is good, except that generating these things will be a little tedious. You’re going to have to instantiate the specific generator that you want and use it to generate your message. So, all over the code, you’re going to have things like this:

    public class CustomerViewModel : INotifyPropertyChanged
    {
        private CustomerService _customerService;

        private Message _statusMessage;
        public Message StatusMessage { get { return _statusMessage; } set { _statusMessage = value; RaisePropertyChanged("StatusMessage"); } }

        public void DoSomething()
        {
            var myCustomer = _customerService.GetCustomerById(12);
            if (myCustomer == null) //Oops, let's tell the GUI about this
            {
                var myGenerator = new ErrorMessageGenerator();
                StatusMessage = myGenerator.GenerateMessage("Customer not found!");
            }
            else
            {
                var myGenerator = new InformationalMessageGenerator();
                StatusMessage = myGenerator.GenerateMessage("Located customer 12.");
            }
        }
....

Generating those objects is sort of annoying, and it also defeats the purpose of having an abstract base class. You could always factor the generation into some view model base, but you don’t get around the problem of having to tell the new method what kind of error generation you want, but that only works for view models that inherit from a base view model. Another option would be to create a factory method or instance that generated the appropriate generator… but, generating generators seems like overkill here. It would also be sort of redundant and wrong feeling to do that, as the information about how to generate messages is all stored inside of the MessageGenerator hierarchy, but you’d be introducing some external class to figure out how these things are wired. So, you decide to leave well enough alone and plow ahead with this not quite elegant, but good enough implementation.

Now, let’s say some time goes by, and your message coloring scheme is such a hit that the users/BAs want every color in the rainbow and even some ultra-violet and infra-red messages. I mean, there are messages that are critical, and then messages that are CRITICAL. The latter should be in red, but with hints of white, to evoke images of a hospital. And, there are really several different kinds of warnings – those that you can ignore, and those that are almost errors, which should be an angry orange. There should also be messages that are green to say “Good job, user!”

You’re glad that your code is such a hit, but dismayed to see your “DoSomething()” method and all those like it ballooning in size like there’s no tomorrow:

        public void DoSomething()
        {
            var myCustomer = _customerService.GetCustomerById(12);
            if (myCustomer == null) //Oops, let's tell the GUI about this
            {
                var myGenerator = new ErrorMessageGenerator();
                StatusMessage = myGenerator.GenerateMessage("Customer not found!");
            }
            else if (myCustomer.IsValid == false)
            {
                var myGenerator = new WarningMessageGenerator();
                StatusMessage = myGenerator.GenerateMessage("Customer not in valid state!");
            }
            else if (PositiveFeedback)
            {
                var myGenerator = new FeelGoodMessageGenerator();
                StatusMessage = myGenerator.GenerateMessage("Way to go!");
            }
            //...
            else
            {
                var myGenerator = new InformationalMessageGenerator();
                StatusMessage = myGenerator.GenerateMessage("Located customer 12.");
            }
        }

Now, since this is GUI code, some of this ballooning is unavoidable – if there are 20 different things that can be displayed for customer retrieval, you’re going to need at least 20 lines for 20 strings. You might rethink the factory method at this point, for generating the generators or even the messages, thus saving yourself some lines of code, but it won’t be a huge gain in terms of the complexity of these methods. So, you forget the factory method and resign yourself to this complexity.

But, let’s say that a new wrinkle comes along. Some of your users think that the BAs got a little carried away with all of the colors, and they just want the old red/yellow/black scheme back. Others love the colors. So, you’re tasked with coming up with a way to please both sets of users. There is a “rich colors” setting in a config file that you’ll read in and, if that’s enabled, you’ll display all of the additional colors, but if not, then the first three.

Now, things get away from the realm of “unavoidable complexity for displaying lots of information to the user” and into “downright hideous” territory:

        public void DoSomething()
        {
            var myCustomer = _customerService.GetCustomerById(12);
            if (myCustomer == null) //Oops, let's tell the GUI about this
            {
                var myGenerator = new ErrorMessageGenerator();
                StatusMessage = myGenerator.GenerateMessage("Customer not found!");
            }
            else if (myCustomer.IsValid == false)
            {
                var myGenerator = new WarningMessageGenerator();
                StatusMessage = myGenerator.GenerateMessage("Customer not in valid state!");
            }
            else if (myCustomer.IsSemiValid)
            {
                if (RichColors)
                {
                    var myGenerator = new WishyWashyMessageGenerator();
                    StatusMessage = myGenerator.GenerateMessage("Well, you're almost there!");
                }
                else
                {
                    var myGenerator = new InformationalMessageGenerator();
                    StatusMessage = myGenerator.GenerateMessage("Well, you're almost there!");
                }
            }
            else if (PositiveFeedback)
            {
                if (RichColors)
                {
                    var myGenerator = new FeelGoodMessageGenerator();
                    StatusMessage = myGenerator.GenerateMessage("Way to go!");
                }
                else
                {
                    var myGenerator = new InformationalMessageGenerator();
                    StatusMessage = myGenerator.GenerateMessage("Way to go!");
                }
            }
            //...
            else
            {
                var myGenerator = new InformationalMessageGenerator();
                StatusMessage = myGenerator.GenerateMessage("Located customer 12.");
            }
        }

Now, you’re duplicating code in a big way. Using a factory method here could stop the bleeding somewhat, but not completely. You’ll see why when you learn what the BAs have in store for you next. When you were able to shoehorn in the selective color scheme from the last release, they got the taste of your blood in their mouths and they liked it.

You see, customers in Miami like teal messages because it’s one of the Dolphins’ colors, while males over 50 seem to be partial to muted shades of gray, and we also need a universal beige when the application is in safe mode. So, the application now needs to be able to read in all of those settings and selectively enable disable those message generators. Now, even your factory method solution is convoluted and nasty. It needs to be in a class with a bunch of booleans or take those booleans as parameters. It may buy you a little reprieve in lines of code, but it won’t buy you any help with your ominously growing complexity. Abandon all hope, ye who enter the presentation tier.

… well, okay, before you start dusting off the resume or pitching version 2.0 to management, there is another way, if you’re up for a bit of refactoring.

So, What to Do?

This is where the Chain of Responsibility pattern enters the picture. If you pull back for a moment and think of what really needs to happen here, it isn’t simply a matter of picking a message generator implementation to use. It’s a matter of prioritizing the message creators. What you’ve really got is a set of rules like “If X and Y, use creator A, otherwise, if Z, use creator B, etc”. You’ve been successful at not duplicating the actual construction of the message by using the generator polymorphs, but you are duplicating the prioritization logic.

So, first things first. Let’s introduce a concept of message priority to the creation method, since it’s already sort of defined in the base class anyway:

    public abstract class MessageGenerator
    {
        public const int LowPriority = 0;
        public const int Normal = 1;
        public static int Warning = 2;
        public static int Error = 3;
        public static int Critical = 4;

        public abstract Message GenerateMessage(string messageText, int severity);
    }

Now, each implementer has additional information that it can use to decide whether or not to bother processing a message:


    public class InformationalMessageGenerator : MessageGenerator
    {
        public override Message GenerateMessage(string messageText, int severity)
        {
            if (severity == Normal)
            {
                return new Message() { Color = Colors.Black, Font = FontWeights.Normal, Text = messageText };
            }
            return null;
        }
    }

Now, the scheme is a bit different. Each generator may or may not return a message. This doesn’t exactly help you, but it’s interesting. You’ve introduced the notion that a generator can examine a passed in parameter and then choose or decline to generate a message. To fully implement Chain of Responsibility, and solve the problem, it is now necessary to teach your generators how to pass the buck.

The idea is to give your generators a sense of “I’ll handle this message if it’s appropriate, and if it’s not, the next guy will handle it.” This, combined with some heuristics for which generators handle which priorities will move a lot of those unsightly if conditions out of your code. So, let’s start with the base class:

    public abstract class MessageGenerator
    {
        public const int LowPriority = 0;
        public const int Normal = 1;
        public static int Warning = 2;
        public static int Error = 3;
        public static int Critical = 4;

        public MessageGenerator Next { get; set; }

        public virtual Message GenerateMessage(string messageText, int severity)
        {
            return Next != null ? Next.GenerateMessage(messageText, severity) : null;
        }
    }

Here, you’ve defined a concept of next generator that can be set by clients. The formerly abstract method is now virtual to encapsulate the buck passing so that clients don’t have to do it. By default, you’ll get buck passing, and you now have to opt in to handling the message yourself. The clients will now look as follows:


    public class InformationalMessageGenerator : MessageGenerator
    {
        public override Message GenerateMessage(string messageText, int severity)
        {
            if (severity == Normal)
            {
                return new Message() { Color = Colors.Black, Font = FontWeights.Normal, Text = messageText };
            }
            return base.GenerateMessage(messageText, severity);
        }
    }

Now your code is looking promising for saving you a lot of bloat. The new message generator examines a message, handles the generation if the severity parameter is appropriate and passes if not. The real slick part of this is that the burden of message generation is still removed from the client, but so too can the burden of prioritizing message generation handling. Here’s what the new client code looks like:


    public class CustomerViewModel : INotifyPropertyChanged
    {
        private CustomerService _customerService;

        private MessageGenerator _messageGenerator;

        public CustomerViewModel(CustomerService customerService, MessageGenerator messageGenerator)
        {
            _customerService = customerService;
            _messageGenerator = messageGenerator;
        }

        private Message _statusMessage = null;
        public Message StatusMessage { get { return _statusMessage; } set { _statusMessage = value; RaisePropertyChanged("StatusMessage"); } }

        public void DoSomething()
        {
            var myCustomer = _customerService.GetCustomerById(12);
            if (myCustomer == null) //Oops, let's tell the GUI about this
            {
                StatusMessage = _messageGenerator.GenerateMessage("Customer not found!", MessageGenerator.Error);
            }
            else if (myCustomer.IsValid == false)
            {
                StatusMessage = _messageGenerator.GenerateMessage("Customer is not in valid state!", MessageGenerator.Warning);
            }
            else if (myCustomer.IsSemiValid)
            {
                StatusMessage = _messageGenerator.GenerateMessage("Well, you're almost there!", MessageGenerator.WishyWashy);
            }
            else if (PositiveFeedback)
            {
                StatusMessage = _messageGenerator.GenerateMessage("Way to go!", MessageGenerator.FeelGood);
            }
            //...
            else
            {
                StatusMessage = _messageGenerator.GenerateMessage("Located customer 12.", MessageGenerator.Normal);
            }
        }
    ...

Wow, that looks much better. One condition, one message — the cyclomatic complexity is now order linear with the actual complexity of the conditions that need to be reported, instead of condition complexity and business analyst imagination complexity multiplied. And, as a nice bonus, you’re not instantiating generators anymore – you’ve got only one that you use, and it’s injected as a dependency. Furthermore, this is accomplished without any factory method. Going back to the original example (error/warning/info), here’s the wireup for it:


    public class Wireup
    {
        public MessageGenerator BuildMessageGeneratorChain()
        {
            return new ErrorMessageGenerator() 
            { 
                Next = new WarningMessageGenerator()
                { 
                    Next = new InformationalMessageGenerator() 
                    {
                        Next = new DefaultMessageGenerator() 
                    } 
                }
            };
        }
    }

(Sorry about the nested conditional initializers — it’s late, and for some reason that amused me a lot more than it should have. It’s like some kind of code ugly-chic.) So, in this simple wireup, you have the chain of responsibility setup with some DefualtMessageGenerator defined to handle all messages not handled elsewhere. I won’t bother picturing it, but this would simply return a message every time, should the responsibility be passed to it. This would ensure that the message was always at least generated, if not with colors and fonts and whatnot.

Now, you’ve really separated responsibilities. The ViewModel and other clients don’t need to worry about message generation – it’s now a black box to them. They have a generator and the generator gives them messages from their passed in string/severity pairs. They have a “Bob’s your uncle” attitude toward the generator’s chain of delegation. And now, when the business analysts get crazy with the colors, you have exactly one place to make changes in existing code — the wireup class (you may need to add new generators as well). This is powerful because one of the more desirable situations for a code base is one in which requirements changes mean adding new code instead of modifying existing code. You can’t introduce regressions to brand new code, after all.

The only exception to not modifying existing code may be a need to periodically revisit the priorities. For instance, if every color in the rainbow has been added to the code base, you may have your default black/yellow/red handle priorities 0-10, 11-20, and 21-30 respectively, but giving the custom colors a bite at the apple first. That allows a teal message of priority 4 to be handled with TealGenerator for Miami customers, but the basic generator for all others simply by omitting the teal generator for the responsibility chain for non-Miami customers. But, if you have this scenario and the 31st color is introduced, you may need to expand the scope of the defaults and shuffle the priorities a bit.

Of course, other schemes are possible too. The generate method could take on another parameter, or you could use a different numbering scheme. The important part is that you’re creating multiple objects that can handle a request using different criteria, with easily customizable ordering scheme.

A More Official Explanation

The original Gang of Four definition of the pattern was:

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.

The algorithm in question calls for a recursive handling of requests. A scheme is setup whereby a client invokes some service to satisfy a request, and the service does so by walking a pre-determined graph of potential handlers until one agrees to service the request. The aforementioned decoupling occurs because the client is oblivious to which potential servicer will actually handle it.

Polymorphism is a convenient mechanism for this paradigm but certainly not the only one. The only requirement is a customizable chain of handlers be given the chance to do so, and given that chance in response to a single request from the client.

Other Quick Examples

Here are some other scenarios that seem as though they’d lend itself well to Chain of Responsibility:

  1. Event handling in the a GUI context (WPF works this way, for instance, with routed events). A control can raise an event that will bubble up the logical tree until some other control handles it.
  2. Modeling a situation with approvers or handlers. For instance, consider a software scheme for managing vacation/PTO requests at a business. Approvers might include managers, VPs, etc. Requests may be handled by person X unless person X is out of office, and then they are handled by person Y, etc.
  3. In a sense, exception handling works this way — code generates an exception, and each layer of the call stack (either explicitly or implicitly) opts to handle the exception or let it bubble up.

A Good Fit – When to Use

This pattern is good to use any time the scheme for handling a request is somewhat involved and should be configurable on the fly. In the example in this post, the pattern wasn’t really important until the scheme for message handling started to get pretty customized and involved. Generally, when this is happening, Chain of Responsibility should enter the discussion.

Likewise, if there is a situation where multiple parties should have input to a request/event, the pattern may be a good idea. With a bit of modification, the example above could be used to generate composite messages (for instance, one message generator could take the message returned by another and make it bold).

Square Peg, Round Hole – When Not to Use

As always, there is the YAGNI princple. Jeff Atwood says

Don’t use fancy OOP features just because you can. Use fancy OOP features because they have specific, demonstrable benefit to the problem you’re trying to solve. You laugh, but like Rico, I see this all the time. Most programmers never met an object they didn’t like. I think it should be the other way around: these techniques are guilty until proven innocent in the court of KISS.

You could substitute “Design Patterns” for “fancy OOP features” here and the message would remain valid. In the example here, if all messages were black and with normal font, it wouldn’t make any sense to use Chain of Responsibility just in case the BAs wanted other colors. Wait until they add one or two before jumping to that conclusion and implementing this pattern. (I have a rule of thumb, which is to wait for at least two and usually three similar requests before deeming the request a pattern and adjusting accordingly. But, as soon as you hit three, do a 180 and bank on more such requests).

In addition, this pattern may not make sense if a rigid ordering is acceptable. For example, if you’re modeling a department structure, and all requests are always approved by a manager and then the VP, it may not be necessary to line up the handlers just yet. If that is unlikely ever to change, there’s no need for a complex design pattern where a simple && will suffice.

Finally, don’t confuse this with assembly. If you’re modeling the construction of a house, you don’t want a “Chain of Responsibility” where one handler builds the basement, and passes it on, the next adds a ground floor and passes it on, etc. That’s an inappropriate metaphor and it will be confusing in the long run. The house construction has a rigid ordering and isn’t in response to anything. This is a creational situation, and Chain of Responsibility is a behavioral pattern. I realize that we were, in the example, ‘constructing’ a message, but the purpose of that construction is to figure out who would build the message — not to partition the message’s construction into different spheres of responsibility (there’s another pattern for that).

So What? Why is this Better?

Chain of Responsibility is an improvement where appropriate because it introduces flexibility. It separates the handling of an event or servicing of request from the place where the event/request is generated. The requester doesn’t need to take care of this itself — it can delegate that. In the example above, the View Model class is responsible for displaying information to the user. But, before implementing the pattern, the View Model was developing a greater and greater responsibility for figuring out how to construct a message. By delegating that responsibility elsewhere, the class was simplified. By using Chain of Responsibility to do it, the whole application was made more flexible by virtue of the fact that the scheme for message construction was made easily swappable on the fly.

This pattern is not a hard sell in terms of utility, given that it’s already widely in use within frameworks, such as in the aforementioned cases of GUI events in WPF and exceptions in general.

By

Builder

Quick Information/Overview

Pattern Type Creational
Applicable Language/Framework Agnostic OOP
Pattern Source Gang of Four
Difficulty Relatively easy.

Up Front Definitions

Here are terms that I’ll be using in this explanation and what they mean:

  1. Composite: This is another design pattern, but I’m using it here to mean an object that is composed of other objects.

The Problem

For this design pattern, I’ll use the example of modeling computers. A computer is a classic example of a composite object. That is, a computer object isn’t just a collection of simple literals, but is actually composed of other objects in your domain (most likely anyway, and it will be in the example).

So, let’s say that you get an assignment to model computer composition and pricing, perhaps for a website for a store that builds custom rigs. For a proof of concept, let’s say that you very much oversimplify things and decide to create an implementation where a computer has memory, a CPU, and a motherboard.

Now, since we’re modeling price rather than actual operation, it’s important to keep in mind that the abstraction for actual computer construction and sales is limited to “what will work with what” rather than modeling the actual interaction. So, if CPU X doesn’t work with motherboard Y, you don’t want to sell that combination. But, worrying about the details of how CPU x works with motherboard Y is beyond the scope of this application. Another thing to consider here is that all components have a price, and the assembled machine will have a price that equals the sum of its components, perhaps with a cost of assembly added as well.

Now, let’s also assume that there is a dependency relationship in ordering how machines are built. That is, you have an external requirement of some sort that the motherboard must be chosen first, followed by the CPU, and then by the memory. So, you create objects for your components and a computer object, and it looks something like the following (remember, this is an example and an example of a POC at that – let’s not get too immersed in the details)

public abstract class Cpu
{
    public int Cores { get; set; }
    public int ProcessorSpeed { get; set; }

    public abstract double Price { get; }

    public virtual bool IsCompatibleWith(Memory memory)
    {
        return true;
    }
}

public class Intel : Cpu 
{
    public override double Price { get { return 300.00; } }
}
public class Athalon : Cpu 
{
    public override double Price { get { return 140.00; } }
}
public abstract class MotherBoard
{
    public int PciSlots { get; set; }
    public int IdeSlots { get; set; }

    public abstract double Price { get; }

    public virtual bool IsCompatibleWith(Cpu cpu)
    {
        return true;
    }

    public virtual bool IsCompatibleWith(Memory memory)
    {
        return true;
    }
}

public class Acer : MotherBoard
{ 
    public override double Price { get { return 200.00; } } 
}
public class IntelMobo : MotherBoard 
{ 
    public override double Price { get { return 500.00; } } 
}
public abstract class Memory
{
    public int Slots { get; set; }
    public int CapacityPerSlot { get; set; }

    public abstract double Price { get; }
}

public class Crucial : Memory 
{ 
    public override double Price { get { return 100.00; } 
    } 
}
public class Kingston : Memory 
{ 
    public override double Price { get { return 200.00; } } 
}

And, finally, the computer:

public class Computer
{
    private MotherBoard _motherboard;
    private Cpu _cpu;
    private Memory _memory;

    public double GetPrice()
    {
        return _memory.Price + _cpu.Price + _motherboard.Price; //Fails if anyone is null
    }
        
    public bool AddMotherboard(MotherBoard motherboard)
    {
        _motherboard = motherboard;
        return true;
    }

    public bool AddCpu(Cpu cpu)
    {
        if (_motherboard == null || !_motherboard.IsCompatibleWith(cpu))
        {
            return false;
        }
        _cpu = cpu;
        return true;
    }

    public bool AddMemory(Memory memory)
    {
        if (_motherboard == null || !_motherboard.IsCompatibleWith(memory) ||
            _cpu == null || !_cpu.IsCompatibleWith(memory))
        {
            return false;
        }
        _memory = memory;
        return true;
    }
}

And, life is good. You have a computer class that can have components added to it in the proper order, with each add returning false if you’ve made an oops. The compatibility standards are a little permissive at the moment, but, remember, POC.

So, the next thing that you’d do is actually set about building these computers, presumably based on user input. The user would first choose a MOBO, and you’d add it to an empty computer object. Then, the user would choose a CPU, and you’d flag an error message if trying to add that didn’t work, or add it if it did, and life would still be good.

But, let’s say that you want to add some functionality to let the user select some pre-assembled machines and then, perhaps customize them. So, you get the first spec in and, no problem, you add it, perhaps to the presentation layer class for backing the view of the computer building screen (remember, POC :) ):

public Computer BuildBudgetComputer()
{
    var myComputer = new Computer();
    myComputer.AddMotherboard(new Acer());
    myComputer.AddCpu(new Athalon());
    myComputer.AddMemory(new Crucial());

    return myComputer;
}

There you go – you’ve got a method in the class that builds a budget computer, pre-assembled for selection, allowing users to build their own or take your canned construction. Then, a requirement for another pre-configured one comes in, and you dutifully add it:

public Computer BuildBudgetComputer()
{
    var myComputer = new Computer();
    myComputer.AddMotherboard(new Acer());
    myComputer.AddCpu(new Athalon());
    myComputer.AddMemory(new Crucial());

    return myComputer;
}

public Computer BuildExpensiveComputer()
{
    var myComputer = new Computer();
    myComputer.AddMotherboard(new IntelMobo());
    myComputer.AddCpu(new Intel());
    myComputer.AddMemory(new Crucial());

    return myComputer;
}

The two methods look pretty similar, but you’re doing a POC, so you choose not to sweat the small stuff, like “Don’t Repeat Yourself”. Now, each time you want to add new preconfigured computer, you have a design pattern. All you have to do is copy one of those methods and put different objects in the Add() calls.

Now, let’s fast forward a few months. After explaining that this was just a POC to management, management decides to ship the POC since it’s working so well. In the interim, you’ve gotten requirements to add hard drives, USB hubs, monitors, keyboards, mice, etc. You also now have to offer hundreds of pre-built computers to the users, along with the coolness of building their own.

Now, along comes an interesting new requirement. Instead of picking the MOBO first, the users now have to pick the CPU first. So, you switch the method preconditions for the AddCpu() and AddMotherboard() methods in Computer, run your unit tests/application, and discover that nothing works. D’oh! You’re still building them in the same order. You just need to switch the order of the client calls to AddMotherboard() and AddCpu(), and…. oh. You need to go through hundreds of methods doing this. Ouch…

So, What to Do?

At this point, “what to do” requires an examination of “what went wrong?” Everything here was a little slapdash, but relatively reasonably constructed. There was no obvious step where things got out of hand, and yet you suddenly have a mess. As it turns out, you have a mess that was completely avoidable.

Think back to the step where we copy/pasted some code and how that didn’t feel right. Well, turns out it wasn’t right (hint: it’s pretty much never right — Don’t. Repeat. Yourself. ). That little concession early in the game led to big problems later. We duplicated the logic of ordering the construction of the computer over and over again.

What could we have done instead? Well, builder pattern to the rescue. Let’s rewind to when we just had our computer and components, and our first method for a canned computer. Taking another look at that method, we see:

public Computer BuildBudgetComputer()
{
    var myComputer = new Computer();
    myComputer.AddMotherboard(new Acer());
    myComputer.AddCpu(new Athalon());
    myComputer.AddMemory(new Crucial());

    return myComputer;
}

Looking at this a bit more abstractly, we have a method that accepts no parameters and returns a computer object. Hard-coded in there are various derived polymorphs that are specific to this particular construction. Also hard-coded in there is obeying the temporal coupling between the different add operations. So here, we’re doing two things — defining which components will be added, and defining the order in which they are added. Now, when we define our next implementation via copy/paste, we’re duplicating the ordering logic but giving different specific objects. What if, instead of coupling these two things, we introduced an abstraction:

public Computer BuildBudgetComputer(Motherboard motherboard, Cpu cpu, Memory memory)
{
    var myComputer = new Computer();
    myComputer.AddMotherboard(motherboard);
    myComputer.AddCpu(cpu);
    myComputer.AddMemory(memory);

    return myComputer;
}

Now, BuildComputer() just encapsulates the logic for navigating the temporal coupling. It’s up to somebody else which components it should be given. This is already a vast improvement and a solution to the problem that we created. Now, client code is making calls like:

public Dictionary<string, Computer> BuildPreassembledComputers()
{
    var myComputers = new Dictionary<string, Computer>();
    myComputers["Budget"] = BuildComputer(new Acer(), new Athalon(), new Crucial());
    myComputers["Expensive"] = BuildComputer(new IntelMobo(), new Intel(), new Crucial());

    return myComputers;
}

public Computer BuildComputer(MotherBoard motherboard, Cpu cpu, Memory memory)
{
    var myComputer = new Computer();
    myComputer.AddMotherboard(motherboard);
    myComputer.AddCpu(cpu);
    myComputer.AddMemory(memory);

    return myComputer;
}

Now, we’ve solved our main initial problem where the logic for the ordering of computer construction being strewn all over the place. With this code, we have one method to change: BuildComputer(), rather than hundreds.

But, we still have a subtle problem. Recall that we’d talked about now having additional components like monitors and hard drives, and we have hundreds of pre-canned combinations. Think about what BuildPreassembledComputers() is going to look like. It’s going to contain hundreds of permutations of parts, named only by the key in that dictionary. Every time you want to add a new pre-assembled computer, you’re going to have to open that class and add a line to that gargantuan method. If some of the computers become obsolete, you’re going to have to remove them from that method. That is, a the composition of a “budget” computer is going to change over the course of time as new parts come out and old ones become obsolete. Why should your presenter/controller/ViewModel have to change when that happens? At some point, you’re going to have to tie the particular computer to some hard-coded name, but it needn’t be there.

So, let’s extrapolate to something a little closer to the builder pattern.

public abstract class AlmostBuilder
{
    public abstract Computer BuildComputer();

    protected Computer AssembleComputer(MotherBoard motherboard, Cpu cpu, Memory memory)
    {
        var myComputer = new Computer();
        myComputer.AddMotherboard(motherboard);
        myComputer.AddCpu(cpu);
        myComputer.AddMemory(memory);

        return myComputer;
    }
}

public class BudgetBuilder : AlmostBuilder
{
    public override Computer BuildComputer()
    {
        return AssembleComputer(new Acer(), new Athalon(), new Crucial());
    }
}

public class ExpensiveBuilder : AlmostBuilder
{
    public override Computer BuildComputer()
    {
        return AssembleComputer(new IntelMobo(), new Intel(), new Crucial());
    }
}


public class Client
{
    public Dictionary<string, Computer> BuildPreassembledComputers()
    {
        var myComputers = new Dictionary<string, Computer>();
        myComputers["Budget"] = new BudgetBuilder().BuildComputer();
        myComputers["Expensive"] = new ExpensiveBuilder().BuildComputer());

        return myComputers;
    }
}

Now, we’re onto something. The builder base class encapsulates a method where the temporal coupling is defined exactly once. The derived builders have the responsibility for defining exactly which components are part of the computer that they’ll return. And, the presentation layer class has the responsibility only for presenting things to the user. It knows what kind of computer it wants, and it delegates the construction totally – both the temporal coupling of the construction and the components used in assembly.

The derived classes have only the responsibility of determining which parts will be added to the composite, and the base class’s Assemble() method has the sole responsibility for navigating the assembly particulars. This solves the issue of modifying a method in a presentation class over and over again and an implied violation of the Open/Closed principle. Now, if we want to define a different building paradigm we can define a new class that derives from AlmostBuilder base class. Of course, somewhere or another we will need to add a line of creation code for that, but it won’t be here in the presentation layer, and we probably already have a creational pattern for that somewhere (like a factory).

Now, to get to the bonafide pattern, we define a “Director” class and different Builders expose methods like “BuildMemory()”, “BuildCpu()” and “BuildMotherBoard()”. The Director takes a builder polymorph as an argument and use its different members to assemble the composite.

public class Director
{
    public Computer BuildComputer(Builder builder)
    {
        var myComputer = new Computer();
        myComputer.AddMotherboard(builder.BuildMotherboard());
        myComputer.AddCpu(builder.BuildCpu());
        myComputer.AddMemory(builder.BuildMemory());

        return myComputer;
    }
}

public abstract class Builder
{
    public abstract Memory BuildMemory();

    public abstract Cpu BuildCpu();

    public abstract MotherBoard BuildMotherboard();
}

public class BudgetBuilder : Builder
{
    public override Cpu BuildCpu()
    {
 	    return new Athalon();
    }

    public override Memory BuildMemory()
    {
        return new Crucial();
    }

    public override MotherBoard BuildMotherboard()
    {
        return new Acer();
    }
}

public class ExpensiveBuilder : Builder
{
    public override Cpu BuildCpu()
    {
        return new Intel();
    }

    public override Memory BuildMemory()
    {
        return new Crucial();
    }

    public override MotherBoard BuildMotherboard()
    {
        return new IntelMobo();
    }
}


public class Client
{
    public Dictionary<string, Computer> BuildPreassembledComputers()
    {
        var myComputers = new Dictionary<string, Computer>();
        var myDirector = new Director();
        myComputers["Budget"] = myDirector.BuildComputer(new BudgetBuilder());
        myComputers["Expensive"] = myDirector.BuildComputer(new ExpensiveBuilder());

        return myComputers;
    }
}

I didn’t show this until just now because I wanted to go through the series of mental leaps and abstractions that would lead us to this point. It may not be necessary at first to launch into an all out implementation. There are steps along the way, and each introduces a new degree of abstraction that’s great and helpful as long as it’s not overkill.

This full blown builder pattern has all of the previous advantages, and the addition of the Director both adds complexity and customizability. You can now inject the director and/or the builders into your presentation class for maximum flexibility.

I’d also like to note that you can use this pattern to do some cool stuff with fluent interfaces. Imagine if the builders, instead of returning their components, all returned new Computer objects (assuming Computer had some kind of copy constructor or clone method). You would have an interface like

var myExpensiveComputer = myBuilder.AddMotherboard(new IntelMobo()).AddCpu(new Intel()).AddMemory(new Crucial());

A More Official Explanation

So pulling back for a moment, let’s consider what we’ve really done here. What got us into trouble was having the methodology of the construction of our composite object, computer, mixed together with the definition of the composite components themselves. To speak plainly, we mixed the how with the what.

According to wikipedia, the main purpose of the Builder Pattern is “to abstract steps of construction of objects so that different implementations of these steps can construct different representations of objects”. Again, this describes separating the how (“construction of objects”) from the what (“different representations of the objects”).

Other Quick Examples

Other examples of using the builder pattern might include:

* You have some object that provides all of the services for your application and you want to supply different services for different runtime configurations, and you want to separate selection of the services from building and instantiating them.
* You’re modeling a pizza delivery service and you want to offer customizable pizzas but also some pre-defined ones that change perhaps by season or specials of the week or something.
* You’re assembling a multi-level composite.

A Good Fit – When to Use

More generally, a good heuristic for when to use the builder pattern is when construction of an object is complicated. In my experience, builder is generally appropriate if and only if you’re building a composite object, though YMMV. So, you might want to consider a builder pattern usage if your composite has temporal coupling as to how it needs to be built. You might also want to do it if your composite can have different configurations.

But, the most important and subtle point here is that you want to do this when there’s some notion of wanting to define discrete assembly characteristics – some assemblies work together but not others according to your business rules. In this sense, you’re separating business rules for valid configuration from the actual nuts and bolts construction of the object.

Square Peg, Round Hole – When Not to Use

Conversely to the idea of discrete assemblies, it’s not a good idea to use this if you have relatively infinite possibilities. For instance, let’s say you defined a “DateRange” struct that consisted of two DateTime objects. You don’t want a builder for this. All other things being equal, the only real restriction on creation of this object is that start date should probably not come after end date. You don’t need a builder to navigate the particulars of construction here — just a simple check in the struct’s constructor. You’d get more into builder territory as the rules for date creation tightened (say, you had a specific application where you could only choose from one of four start dates and one of four end dates or something).

Another bad reason to use this is if you don’t actually need it. We sort of pushed it with the example above — the abstraction of the BuildComputer() method might have sufficed for the requirements as stated up to that point. The pattern is powerful, but it introduces complexity, and it’s important to make sure the complexity isn’t of the needless variety.

And finally, I’d like to emphasize that there is a specific construction mode for where there is a far better design pattern — building polymorphs. Builder is for composites. Don’t use it for a situation where you have a “Food” base class and you read in strings like “IceCream” and “Steak” and create inheritors IceCream and Steak depending on what you read in. That calls for one variation or another of the factory pattern — a pattern specifically for figuring out how to create inheritors of a common base or implementers of a common interface.

So What? Why is this Better?

Object construction is one of those things that tends to creep up on you in terms of complexity. In the book “The Pragmatic Programmer: From Journeyman to Master”, Dave Thomas and Andy Hunt describe the boiling frog phenomenon. The idea is (and the authors swear never to have tried it) that if you put a frog in a boiling pot of water, it will, predictably, leap out. But, if you put it in cold water and increase the temperature gradually over time, the frog will remain there even when the temperature is eventually raised to boiling and cooks the frog.

That is how object creation tends to work in code bases. There is nothing simpler than a “var myClass = new MyClass()” declaration, so why spend a lot of time thinking about where to put it? Eventually, myClass’s constructor gets more complicated, and it picks up some initialization logic and other things, and then you need to create lists and dictionaries of it, and at some point it gets inheritors that you also need to create. Before you know it, your ad-hoc creation of these things is a nightmare.

As shown above, the Builder Pattern alleviates this problem. It separates the logic for providing components for a complicated object from the logic that governs the order of assembly of those components, and it separates both of those things from the logic that actually uses the components. When used in this fashion, changes to any one of those concerns do not affect the other two. And, decoupling and dependency management is the key to avoiding maintenance and feature-addition headaches.

By

Bridge

Quick Information/Overview

Pattern Type Structural
Applicable Language/Framework Agnostic OOP
Pattern Source Gang of Four
Difficulty Somewhat complex to grasp, moderate to implement.

Up Front Definitions

There are no special definitions that I’ll use here not defined inline.

The Problem

The iconic example of a situation in which the Bridge pattern is applicable is modeling a wall switch and the thing that it controls. Let’s say that you start out with a set of requirements that says users want to be able to turn an overhead light on and off. Skipping right to implementation, you do something like this:

public class OverheadLamp
{
    public bool IsOn { get; private set; }
    public bool IsUp { get; private set; }

    public void FlipSwitch()
    {
        IsUp = !IsUp;
        IsOn = !IsOn;
    }
}

This is fine, and you deliver it to production, and everyone is happy. But in the next iteration, a new requirement comes in that users want to be able to use a rocker switch or a push-button switch. And just as you’re getting ready to implement that, you’re also told that you need to implement a rotary switch (like a door deadbolt, you turn this to two different positions). Well, that’s fine, because you have just the trick up your sleeve in a polymorphic language: the interface!

public interface IOverheadLamp
{
    bool IsOn { get; }

    void OperateSwitch();
}

public class RockerOperatedLamp : IOverheadLamp
{
    public bool IsOn { get; private set; }
    public bool IsUp { get; private set; }

    public void OperateSwitch()
    {
        IsUp = !IsUp;
        IsOn = !IsOn;
    }
}

public class PushButtonOperatedLamp : IOverheadLamp
{
    public bool IsOn { get; private set; }
        
    public void OperateSwitch()
    {
        IsOn = !IsOn;
    }
}

public class RotarySwitchOperatedLamp : IOverheadLamp
{
    public bool IsOn { get; private set; }
    public bool IsToTheLeft { get; private set; }

    public void OperateSwitch()
    {
        IsOn = !IsOn;
        IsToTheLeft = !IsToTheLeft;
    }

}

Notice the change in “FlipSwitch” to the more abstract “OperateSwitch()”. This allows for implementations where the switch is not “flipped,” such as push-button. (I’m not really a stickler for English semantics, but I suppose it’s debatable whether or not a rotary switch’s operation would be a “flip.”)

Now you’re all set. Not only does your overhead lamp operate with several different kinds of switches, but you’re following the Open/Closed Principle. Marketing can come in and demand a toggle switch, a fancy touchpad, or even a contraption that you smack with a hammer, and you handle it by writing and unit-testing a new class. Everything looks good.

Except in the next iteration, those crafty marketing people realize that a switch could operate other kinds of electronics, like fans, appliances, and space heaters. So they tell you that they want the switch now to be able to turn on and off computers as well as overhead lamps. That’s a challenge, but you’re up to it. You have your interface, so you’ll just add some more polymorphs and refine the abstraction a bit:

public interface ISwitchableAppliance
{
    bool IsOn { get; }

    void OperateSwitch();
}

public class RockerOperatedLamp : ISwitchableAppliance
{
    public bool IsOn { get; private set; }
    public bool IsUp { get; private set; }

    public void OperateSwitch()
    {
        IsUp = !IsUp;
        IsOn = !IsOn;
    }
}

public class PushButtonOperatedLamp : ISwitchableAppliance
{
    public bool IsOn { get; private set; }
        
    public void OperateSwitch()
    {
        IsOn = !IsOn;
    }
}

public class RotarySwitchOperatedLamp : ISwitchableAppliance
{
    public bool IsOn { get; private set; }
    public bool IsToTheLeft { get; private set; }

    public void OperateSwitch()
    {
        IsOn = !IsOn;
        IsToTheLeft = !IsToTheLeft;
    }

}

public class RockerOperatedComputer : ISwitchableAppliance
{
    public bool IsOn { get; private set; }
    public bool IsUp { get; private set; }

    public void OperateSwitch()
    {
        IsUp = !IsUp;
        IsOn = !IsOn;
    }
}

public class PushButtonOperatedComputer : ISwitchableAppliance
{
    public bool IsOn { get; private set; }

    public void OperateSwitch()
    {
        IsOn = !IsOn;
    }
}

public class RotarySwitchOperatedComputer : ISwitchableAppliance
{
    public bool IsOn { get; private set; }
    public bool IsToTheLeft { get; private set; }

    public void OperateSwitch()
    {
        IsOn = !IsOn;
        IsToTheLeft = !IsToTheLeft;
    }

}

Alright, that code is going to work, but you’re a little leery of the fact that, after renaming IOverheadLamp to ISwitchableAppliance, the new classes you created were simply a result of copying and pasting the lamp classes and changing “lamp” to “computer.” You should be leery. That’s a design/code smell (duplication–don’t repeat yourself!) But whatever–you’re behind schedule and people are giving you a hard time. You can refactor it later.

Now the next iteration starts, and marketing is wildly pleased with your computer/light switch. They want to be able to control any sort of appliance that you can imagine–the aforementioned space heaters, ceiling fans, refrigerators, plug-in light sabers, whatever. Oh, and by the way, computers don’t necessarily turn on when you flip the switch for the outlet that they’re plugged into, so can you have the computer not turn on when you turn the switch on, but turn off when you turn the switch off? Oh, and remember that hammer-operated switch? They want that too.

Well, you’re hosed. You realize that you’re going to have to copy and paste your three (four, with the hammer thing) classes dozens or hundreds of times, and you’re going to have to change the behavior of some of them. All of the computer ones, for instance, don’t automatically turn on when you activate the switch. But clients of your code don’t know that, so they’re now going to have to try to cast the ISwitchableAppliance to one of the classes ending in Computer to account for its special behavior. This just got ugly, and fast.

So, What to Do?

In terms of realizing what you should have done or what can be done, the first important thing to realize is that you’re dealing with two distinct concepts rather than just one. Consider the following two diagrams:

Before
Our current object model

After
Another way of looking at things

The first diagram is what we were doing. Conceptually, every appliance consists not only of the appliance itself, but also of the switch that turns it on or off (or does something to it, more generally). In the second diagram, we’ve separated those concerns, realizing that the appliance itself and the switching mechanism are two separate entities capable of varying independently.

At this point, I’ll introduce the Bridge pattern in earnest, in a UML diagram, compliments of Wikipedia:

Wiki bridge

In looking at this version of it, we see some new concepts introduced: abstraction and implementor. I’ll explain the theory behind this in the next section, but suffice it to say for now that our abstraction is the switch and our implementor is the appliance. As the diagram depicts, our clients are going to deal with the abstraction, and they’re going to do so by handing it a reference to the implementor that they want. More concretely, our clients are going to instantiate some switch and tell it what device they want it to control.

By way of code, let’s consider what we had before marketing buried us with the latest barrage of requirements–three switch types and two appliances. The only new requirement that we’ll consider up front is the one suggesting that computers need to behave differently than other appliances when the switch controlling them is toggled. First, we’ll define the API for the switch (abstraction) and the appliance (implementation):

public interface ISwitch
{
    bool IsOn { get; }

    IAppliance Appliance { get; set; }
        
    void OperateSwitch();
}

public interface IAppliance
{
    bool HasPower { get; }
    bool IsOn { get; }
    void TogglePower();
    void ToggleOn();
}

Notice that because our implementation up until this point has been pretty simple, the interfaces look almost identical (minus the HasPower, TogglePower() in IAppliance, which we’ve added with our new requirement in mind). Both the appliance and the switch have the concept of on and off, more or less. This similarity was what allowed us, up until now, to operate under the (faulty) assumption that these two concepts could easily be combined. But we ran into difficulty when we saw that the abstraction and the implementation needed to vary separately (more on this later).

Where we got into trouble was with the concept of toggle power and distinguishing between having power and being on. That makes sense for an appliance (is it turned off or unplugged?) but not for a switch, which only knows that it has two positions and that it’s in one of them. So, with the introduction of this new requirement, we can no longer operate under even the pretense that mashing these two concepts together is a reasonable thing to do.

The key thing to notice here is that ISwitch has a reference to an IAppliance. This means that clients instantiating a switch can hand it an appliance on which to operate. But we’ll look at client code later.

Now let’s consider the implementors of IAppliance:

public class OverheadLamp : IAppliance
{
    public bool HasPower { get; private set; }
    public bool IsOn { get; private set; }

    // Supplying power to lamps automatically turns them on, and removing it turns them off
    // (well, probably only if their onboard switch is in that position, but that's tangential to the example)
    public void TogglePower()
    {
        HasPower = !HasPower;
        ToggleOn();
    }

    public void ToggleOn()
    {
        IsOn = !IsOn;
    }
}

public class Computer : IAppliance
{
    public bool HasPower { get; private set; }
    public bool IsOn { get; private set; }

    // Toggling power for computer just turns it off if it was on
    public void TogglePower()
    {
        HasPower = !HasPower;
        if (!HasPower)
        {
            IsOn = false;
        }
    }

    public void ToggleOn()
    {
        IsOn = !IsOn;
    }
}

Here, notice the distinction in the behavior of TogglePower(). For lamps, supplying or removing power supplies and removes power but also turns the lamp on and off, respectively. For computers, removing power turns the computer off, but supplying power does not turn it on. (Some other client of the API will have to do that manually, ala real life.) Now that we’ve decoupled the actual implementation of the concept of appliances being on and off from the abstraction of initiating that implementation, our appliances can change how they behave when power is supplied or removed. We could introduce a new appliance, “BatteryPoweredAlarmClock,” that didn’t turn off when power was cut (or, more accurately, kicked off some long running timer that would turn it off at some point later).

Here are the implementations of the ISwitch interface:

public class Rocker : ISwitch
{
    public bool IsOn { get; private set; }
    public IAppliance Appliance { get; set; }
    public bool IsUp { get; private set; }

    public void OperateSwitch()
    {
        IsUp = !IsUp;
        IsOn = !IsOn;
        if (Appliance != null)
        {
            Appliance.TogglePower();
        }
    }
}

public class PushButton : ISwitch
{
    public bool IsOn { get; private set; }
    public IAppliance Appliance { get; set; }

    public void OperateSwitch()
    {
        IsOn = !IsOn;
        if (Appliance != null)
        {
            Appliance.TogglePower();
        }
    }
}

public class Rotary : ISwitch
{
    public bool IsOn { get; private set; }
    public IAppliance Appliance { get; set; }
    public bool IsToTheLeft { get; private set; }

    public void OperateSwitch()
    {
        IsOn = !IsOn;
        IsToTheLeft = !IsToTheLeft;
        if (Appliance != null)
        {
            Appliance.TogglePower();
        }
    }
}

Notice that the individual implementors still retain their own unique properties. Rocker still has up or not up, and Rotary still has its position. But the things that all share are implementations of the OperateSwitch() method, the IsOn property (it might be more accurate to rename this “IsInOnPosition” to avoid confusion with the appliance On/Off state, but I already typed up the code examples), and the IAppliance property. In addition, all of them operate on the appliance’s TogglePower() method.

This last distinction is important. Switches, in concept, can only supply power to an appliance or take it away–they don’t actually switch it on and off. It is up to the appliance to determine how it behaves when power is supplied or removed. As this implementation is continued, it is important to remember this distinction. I could have omitted ToggleOn() from the appliances’ interface if this code were in a vacuum because the switch has no use for it. However, assuming that we’re modeling something a little broader (like, say, my home automation pet project), we clearly want people in houses to be able to turn on their computers and televisions. The switch is unlikely to be the only consumer of IAppliance.

Finally, let’s consider how we would use this thing:

public class Client
{
    public IAppliance WireUpAComputerAndFlipTheSwitch(ISwitch switchToUse)
    {
        var mySwitch = switchToUse ?? new Rocker(); //If the switch passed in is null, use a rocker by default
        mySwitch.Appliance = new Computer(); //Wire the switch up to a new computer
        mySwitch.OperateSwitch(); //Operate the switch

        return mySwitch.Appliance; //Return the appliance in whatever state the switch operation put it
    }
}

Here’s an example application, cutting out any considerations like factory classes or methods. We have some method that takes a switch as input and returns a computer in the state the method put it in. Conceptually, this is pretty simple–we’ve done all the hard work. You just take your switch, set it to operate some appliance, and then operate away.

A More Official Explanation

Earlier, I mentioned the notion of decoupling an abstraction from its implementation. This is the backbone of this pattern, but it might be a little confusing in terms of what it’s actually trying to communicate. I’d imagine some reading will think, “Isn’t decoupling an abstraction from its implementation what an interface contract does? Why the separate pattern?”

To answer that first question, I’ll say, “yes.” Defining an interface says, “Any implementors of this interface will define a method that takes these parameters and returns this type of value, and the details are up to the implementor to sort out. The client doesn’t care how–just get it done.” So, in a manner of speaking, the method signature is the abstraction and the implementation is, well, the implementation.

The problem is that this is a code abstraction rather than a modeled abstraction. That is, a method signature is a contract between one developer and another and not between two different objects. A switch isn’t an interface to a device in C#–it’s an interface to a device in the real world. A switch has its own properties, operations, and state that needs to be modeled. It can’t be reduced in code to a method signature.

So what are we getting at when we say that we want to decouple an abstraction from an implementation? Generally speaking, we’re saying that we want to decouple a thing of some sort from operation performed on that thing. In our example, the thing is an appliance, and the operations performed on it are supplying or removing power. The switch (abstraction) is a separate object with its own properties that needs to be modeled. And what’s more, we can have different kinds of switches, so long as all of the switches perform the needed operation on appliance.

In general, the Bridge pattern represents a scenario like a simple sentence with subject, verb, object: Erik eats apple. We could code up Erik and code up an apple. But then maybe Erik eats orange. So we define a fruit base class or interface and model the world with “Erik eats fruit.” But then maybe Joe also eats fruit, so we need to define a person class and further generalize to “Person eats fruit.” In this case, our abstraction is person, and our implementation is fruit. Person has a fruit property and performs “Eat” on it. The one thing that never changed as we continued generalizing was “eat”–it was always “A eats B.” Going back to our switch/appliance paradigm, we notice the same thing: “A toggles power to B.”

The decoupling allows us to have different subjects and for different objects to behave differently during the course of the verb operation. So if I use the Bridge pattern to model “Person eats Fruit,” it isn’t hard to specify that some fruits leave a pit or a core and some don’t following the eat operation. It isn’t hard to have some people get indigestion as a result of eating fruit. And neither one of those new requirements merits a change to the other one. Fruit doesn’t change if it gives people indigestion, and a person isn’t changed when a piece of fruit they eat has a pit.

Other Quick Examples

The Bridge pattern has as many uses as you can conceive of “A verb B” pairs that might have some variance in the A and B, so I’ll list a handful that lend themselves well to the pattern.

  1. You have images stored in different formats on disk (bmp, jpg, png, etc) and you also have different ways of rendering images (grayscale, inverted, etc)
  2. You’re performing a file operation on a file that may be a Windows, Mac, or Linux file
  3. You have different types of customers that can place different types of orders
  4. You have a GUI that displays buttons, text boxes, and labels differently depending on different user themes

A Good Fit–When to Use

The Bridge Pattern makes sense to use when you have two objects participating in an action and the mechanics of that action will have different ramifications for different types of the participating objects. But, beyond that simple distinction, it makes sense when you are likely to need to add participants. In our example, different appliances behaved differently when power was supplied or removed, and different switches had different behaviors and properties surrounding their operation. Additionally, it seemed pretty likely after the first round or two of marketing requests that we’d probably be adding more “subjects” and “objects” in perpetuity.

This is where the Bridge pattern really shines. It creates a situation where those types of requirements changes mean adding a class, rather than changing existing ones. And, it obviates duplicating code with copy and paste.

I’d summarize here by saying that the Bridge pattern is a good fit when you are modeling “A action B,” when A and B vary in how the action affects each one, and when you find that coupling A and B together will result in duplication. Conversely, it might be a good pattern to look at when you’re faced with the prospect of a combinatorial explosion of implementations as requirements change. That is, you can tell that A and B should be decoupled if you find yourself with classes like A1B1, A1B2, A2B1, A2B2.

Square Peg, Round Hole–When Not to Use

Don’t use this pattern if A and B are really appropriately coupled. If, in your object model, switches were actually wired to appliances, our effort would be unnecessary. Conceptually, it wouldn’t be possible to use one appliance’s switch on another–each appliance would come with one. So you define the different types of switches, give each appliance a concrete switch, and define “TurnOn” and “TurnOff” as methods on the appliance. The Bridge pattern is meant to be used when real variance occurs between the actors involved, not to be used any time one thing performs an operation on another.

There’s always YAGNI to consider as well. If the requirements had stayed as they were early in our example–we were only interested in lights–the pattern would be overkill. If you’re writing a utility specifically to model the overhead lights in a house, why define IAppliance and other appliances only to let them languish as dead code? Apply the bridge when you start getting actual variance in both objects, not when you just think it might happen at some point. In the simplest application, having to supply Switch with your only appliance, “OverheadLamp,” is wasteful and confusing.

Finally, Bridge has a curious relationship with Adapater, which I covered earlier. Adapater and Bridge have conceptual similarities in that they both link two objects and allow them to vary independently. However, Adapter is a retrofit hack used when your hands are tied, and Bridge is something that you plan when you control everything. So, don’t use (or try to use) Bridge when you don’t control one of the participant hierarchies. If, say, “RockerSwitch” et. al. were in some library that you didn’t control, there’s no point bothering to try a bridge. You’d need to adapt, rather than bridge, the switches to work in your implementation.

So What? Why is this Better?

So, why do all this? We’ve satisfied the requirement about computers behaving differently when the switch is flipped, but was it worth it? It sure was. Consider how the new requirements will now be implemented. Marketing wants 100 new appliances and a new switch. Sure, it’s a lot of work–we have to code up 101 new classes (100 for the appliances and 1 for the switch). But in the old, mash-up way, we’d have to code up those 100 new appliance classes, copy and paste them 3 times each, code up a new switch class, and copy and paste it 102 times, for a total of 403 new classes. And what if we made a mistake in a few of the appliance classes? Well, we’d have to correct each one 4 times because of all the copy/pasted code. So, even if the idea that not duplicating your work doesn’t sell you, the additional development and maintenance should.

By

MVVM and Dialogs

For those familiar with the MVVM (Model, View, View-Model) pattern in .NET development, one conundrum that you’ve probably pondered, or at least read about, is what to do about showing a dialog. For a bit of background, MVVM is centered around the concept of binding from the View (XAML markup) to the “ViewModel”, which essentially acts as a staging platform for UI binding.

The ViewModel exposes the “Model” in such a way that the XAML can passively bind to it. It does this by exposing bindable properties (using INotifyPropertyChanged) and bindable commands (by using ICommand). Properties represent data, and commands represent actions.

The Problem

So, let’s say that you want a clean MVVM implementation which generally aspires to have no code-behind. Some people are more purist about this than others, but the concept has merit. Code-behind represents an active way of binding. That is, you have code that knows about the declarative markup and manipulates it. The problem here is that you have a dependency bugaboo. In a layered application, the layers should know about the one (or ones) underneath them and care nothing about the ones above them. This allows a different presentation layer to be plopped on a service tier or a different view to be skinned on a presentation tier. In the case of code-behind, what you have is a presentation tier that knows about its view and a view that knows about its presentation tier. You cannot simply skin another view on top because the presentation tier (read: code-behind) expects named elements in the declarative markup.

So, in a quest to eliminate all things code behind, you adopt MVVM and do fine when it comes to data binding and basic commands. But inevitably you want to open a window, and the WPF framework is extremely clunky and win-forms-like when it comes to this. Your choices, out of the box, are to have a named element in the XAML and manipulate it to show a dialog or else to have an event handler in the code behind.

What Others Have Suggested

The following are suggestions I’ve seen to address this problem and the reasons that I didn’t particularly care for them, in regards to my own situation. I did a fair amount of research before rolling my own.

  1. Just use the code behind (second response to post (3), though I’ve seen the sentiment elsewhere). I don’t really like this because I think that, when it comes to design guidelines, slippery slopes are a problem. If you’re creating a design where you’d like to be able to arbitrarily swap out groups of XAML files above a presentation layer, making this exception is the gateway to your skinnable plans going out the window. Why make exceptions to your guidelines if it isn’t necessary?
  2. Mediator Pattern. Well, this particular implementation lost me at “singleton,” but I’m not really a fan of this pattern in general for opening windows. The idea behind all of these is to create a situation where the View and ViewModel communicate through a mediator so as to have no direct dependencies. That is, ViewModel doesn’t depend on View–it depends on Mediator, as does the View. Generally speaking, this sort of mediation is effective at allowing tests and promoting some degree of flexibility, but you still have the same dependency in concept, and then you have the mediator code to maintain and manage.
  3. Behaviors. This is a solution I haven’t looked at too much and might come around to liking. However, at first blush, I didn’t like the looks of that extra XAML and the overriding of the Behavior class. I’m generally leery of .NET events and try to avoid them as much as possible. (I may create a post on that in and of itself, but suffice it to say I think the syntax and the forced, weakly typed parameters leave a lot to be desired.)
  4. Some kind of toolkit Blech. Nothing against the people that make these, and this one looks pretty good and somewhat in line with my eventual situation, but it seems like complete overkill to download, install, and maintain some third party application to open a window.
  5. IOC Container. I’ve seen some of these advertised, but the same principle applies here as the last one. It’s overkill for what I want to do.

I’ve seen plenty of other solutions and discussion as well, but none of them really appealed to me.

What I Did

I’ll just put the code and example usage in XAML here and talk about it:

public class OpenWindowCommand<T> : SimpleCommand where T : Window, new()
{
    #region Fields

    /// <summary>Stores the function that evaluates whether or not the command can be executed</summary>
    private readonly Func<bool> _canExecute;

    /// <summary>View model that will serve as data context of the command in question</summary>
    private readonly IViewModel _viewModel;

    /// <summary>Used to verify method preconditions and object invariants</summary>
    private readonly ArgumentValidator _validator = new ArgumentValidator();
                                                                               

    #endregion

    #region Constructor

    /// <summary>For window open command, </summary>
    /// <param name="viewModel"></param>
    public OpenWindowCommand(IViewModel viewModel, Func<bool> canExecute = null) : base(canExecute, null)
    {
        _validator.VerifyNonNull(viewModel);

        _viewModel = viewModel;
    }

    #endregion

    #region ICommand stuff

    /// <summary>Ignores the command parameter, creates the window, sets its datacontext, and shows</summary>
    public override void Execute(object parameter)
    {
        var myWindow = new T();
        myWindow.DataContext = _viewModel;
        myWindow.ShowDialog();
    }

    #endregion
}
<MenuItem Header="_Edit">
    <MenuItem Header="Metadata" Command="{Binding Commands[OpenWindowMetadataEditor]}"/>
</MenuItem>

That’s it. The things that are referenced here that you won’t have are worth mentioning but not vital to the implementation. SimpleCommand, from which “OpenWindowCommand” inherits, is a class that allows easier command declaration and use. It implements ICommand. It takes a delegate or a boolean for CanExecute() and a delegate for execution (that we override in OpenWindowCommand since we have a concrete implementation). Simple command is not generic–the generic is in OpenWindowCommand to allow strongly typed window opening (the presumption here being that you want to use this for windows that you’ve created and want to show modally).

The binding in the XAML to commands is to an object that represents a collection of commands. I actually have a CommandCollection object that I’ve created and exposed as a property on the ViewModel for that XAML, but you could use a Dictionary to achieve the same thing. Basically, “Commands[]” is just an indexed hash of commands for brevity in the view model. You could bind to a OpenWindowCommand property on your ViewModel.

So, basically, when the view model from which you want to open a window is being setup, you create an instance of OpenWindowCommand(YourViewModelInstance). When you do this, you passively expose a window open for binding. You’re saying to the view “execute this command to open window of type X with view model Y for backing.” Your view users are then free to bind to this command or not.

Why I Like This

First of all, this implementation creates no code-behind. No named windows/dialogs certainly, but also no event handlers. I also like that this doesn’t have the attendant complexity of most of the other solutions that I’ve seen. There’s no IMediator/Mediator, there’s no ServiceLocator, no CommandManager.Instance–none of it. Just one small class that implements one framework interface.

Naturally, I like this because this keeps the ViewModel/presentation layer View agnostic. This isn’t true out of the box here, but it is true in my implementation. I don’t declare commands anywhere in my ViewModels (they’re all wired in configurably by my home-rolled IOC implementation at startup). So the ViewModel layer only knows about the generic Window, not what windows I have in my view.

Room for Improvement

I think it would be better if the presentation tier, in theory, didn’t actually know about Window at all. I’m keeping my eyes peeled for a way to remove the generic parameter from the class and stick it on the Execute() method to be invoked from XAML. XAML appears to be very finicky when it comes to generics, but I have some hope that this may be doable in the latest release. I’ll re-post when I find that, because I’d love to have a situation in which the XAML itself could specify what kind of window to open as a command parameter. (I’m not in love with command parameters, but I’d make an exception for this flexibility.)

I’m also aware that this doesn’t address non-modal windows, and that there is currently no mechanism for obtaining the result from ShowDialog. The former I will address as I grow the application that I’m working on. I already have a solution for the latter in my code, and perhaps I’ll detail that more in a subsequent post.

Acknowledgements | Contact | About | Social Media