However, if you’re doing this as your full-time job and you’re neck deep in a complex business domain, then you are seriously selling yourself short. When working in a team environment you’ve got to use every means possible to communicate what you were thinking and what hard-earned knowledge you gained along the way. Some poor sucker is going to open your project at some point and your code should be screaming important concepts right from the class list.

I don’t expect you to understand how the app works, but you should at least get a feel right away for the things that are important. Knowing it’s a console app, you could find the entry point and quickly navigate to the meat and potatoes of the application.

public class SyncListingJob : MarshalByRefObject, IJob
{
    private IServiceProvider locator;
    private YextListing listing;

    public SyncListingJob(IServiceProvider locator)
    {
        this.locator = locator;
    }

    public void Init(YextListing listing)
    {
        this.listing = listing;
    }

    [UnitOfWork]
    public void Execute()
    {
        GuardAgainstNotInitialized();
        SyncListing();
    }

    private void SyncListing()
    {
        new LocatorChain<Yextlisting>(locator)
            .AddNew<RevertDiscontinuedListing>()
            .AddNew<RefreshLinkedBusiness>()
            .AddNew<CreateLinkToExistingBusiness>()
            .AddNew<CreateNewBusinessAndLink>()
            .Process(listing);
    }

    private void GuardAgainstNotInitialized()
    {
        if (listing == null) throw new Exception("Job not initialized!");
    }
}

* The LocatorChain<T> is an implementation of the chain of responsibility pattern.

I do everything I can to push out all the noise and bring the behavior to the surface.  Sometimes the right way to name a class is after a feature or behavior. I want my code to read like a DSL and making everything a noun just doesn’t cut it. The drivers for me are context and readability.

Recently, the stake holders came up with a twist that went something like this: If the order contains a gift card, add the contact to a specific folder in the CRM application. No big deal, we had a nicely abstracted OrderGateway interface and I was already envisioning a quick addition to the existing decorator chain.

class OrderWithGiftCardGateway extends OrderGatewayDecorator
{
    ...

    public function createOrder(CreateOrderRequest $order)
    {
        if ($this->containsGiftCard($order))
        {
            $this->addContactToFolder($order);
        }

        return parent::createOrder($order);
    }
}

I had a few minutiae questions like what happens with duplicates, etc. It took me nearly an hour to track down the right person and get real answers. During the conversation, a subtle comment was made that I almost missed.

Stake holder: We should check with the product supplier to make sure the gift card sku I made up isn’t for a real product.

Me: Say what?

Stake holder: The gift card is not fulfilled by the product supplier, it’s fulfilled by the affiliate.

Me: %$@!&, I’m glad we had this conversation.

We talked about what it meant for the the affiliate to fulfill the product and basically the folder stuff was okay, but I recommended we remove the fake sku from the order before sending it through.

public function createOrder(CreateOrderRequest $order)
{
    if ($this->containsGiftCard($order))
    {
        $this->addContactToFolder($order);
        $this->removeGiftCardFromOrder($order);
    }

    return parent::createOrder($order);
}

I didn’t have a buddy to pair with so I just grabbed Keith for a minute at the end of the day to walk through things. I recapped the stake holder discussion and we looked through the code. He pointed out I was missing the concept of fulfillment and that was hard earned knowledge that would be lost!

public function createOrder(CreateOrderRequest $order)
{
    if ($this->containsGiftCard($order))
    {
        $this->sendToAffiliateForFulfillment($order);
        $this->removeGiftCardFromOrder($order);
    }

    return parent::createOrder($order);
}

That was huge. – Paris Hilton

Why was that huge? Because it changed the conversation. Right away we thought of important requirements like this should be in a transaction with the order and the template email the affiliate gets should include the customer’s address, etc.

It tells an important story for the next guy looking at the code and it changes the role of the programmer from code monkey to business partner. Maybe you think I’m crazy, but this stuff matters to me.

Our phone system routes live phone calls to doctor’s offices and the project was to bill the doctor if the call met the following criteria:

1) Caller is a new patient (pressed “1” instead of “2” in response to a voice prompt)

2) A live call was connected for more than 20 seconds or message longer than 10 seconds was recorded.

3) The doctor has not already been billed for this caller.

4) The call is not from a known list of test numbers.

The application subscribes to an event stream of new call records and runs them through this composite specification to determine if the call is billable.

public bool IsBillable(CallRecord call)
{
    ISpecification<CallRecord> billableCallSpecification = new NewPatient()
        .And(new MinLengthLiveCall(liveCallSeconds).Or(new MinLengthMessage(messageSeconds))
        .And(new RepeatCall(referralFinder).Not())
        .And(new TestCall(testNumbers).Not()));

    return billableCallSpecification.IsSatisfiedBy(call);
}

I have to admit that I was already an hour into Query Analyzer blasting through another monster stored procedure when I caught myself. Not just the criteria logic either, I mean bypassing all the event stream hooha and basically just writing the whole enchilada as one gnarly stored procedure that would run as a job. That was a close one!

Before I get into the guts, I would like to provide a little context. My application has 20+ databases scattered across 4 machines.

IRepository<Customer> customerRepository; // customer database on server 1
IRepository<Package>  packageRepository; // customer database on server 1
IRepository<Contact>  contactRepository; // contact database on server 2

The “magic” if you will, happens in the global.asax. I was nosing around in Rhino.Commons for inspiration and adapted a technique I saw there. This is how it looks:

public class GlobalApplication : HttpApplication
{
    private static IUnityContainer container;

    public GlobalApplication()
    {
        BeginRequest += new EventHandler(GlobalApplication_BeginRequest);
        EndRequest += new EventHandler(GlobalApplication_EndRequest);
    }

    protected void Application_Start(object sender, EventArgs e)
    {
        RegisterRoutes(RouteTable.Routes);

        container = new UnityContainer();
        container.AddNewExtension<PolicyInjectorContainerExtension>();
        container.AddNewExtension<HttpRequestLifetimeCoreContainerExtension>();
        container.AddNewExtension<WebMvcContainerExtension>();

        ControllerBuilder.Current.SetControllerFactory(new UnityControllerFactory(container));
    }

    void GlobalApplication_BeginRequest(object sender, EventArgs e)
    {
        var unitOfWork = container.Resolve<IUnitOfWork>();
        unitOfWork.Start();
    }

    void GlobalApplication_EndRequest(object sender, EventArgs e)
    {
        var unitOfWork = container.Resolve<IUnitOfWork>();
        unitOfWork.Commit();
    }
}

I register the UoW with an HttpRequestLifetimeManager so I get a new instance for each request.

Container.RegisterType<IUnitOfWork<ISession>,
	NHibernateUnitOfWork>(new HttpRequestLifetimeManager());

public class NHibernateRepository<T> : IRepository<T>
{
    protected ISession session;

    public NHibernateRepository(IUnitOfWork<ISession> unitOfWork)
    {
        session = unitOfWork.GetContextFor<T>();
    }

    ...

    public virtual void Save(T obj)
    {
        session.Save(obj);
    }
}

Now, this is all the context of an ASP.NET MVC Controller, but I have a similar issue for other (non-web) services. In that context I am using AOP and decorating a particular method with [UnitOfWork], which looks like:

public class UnitOfWorkCallHander : ICallHandler
{
    private IUnitOfWork<ISession> unitOfWork;

    public UnitOfWorkCallHander(IUnitOfWork<ISession> unitOfWork)
    {
        this.unitOfWork = unitOfWork;
    }

    public int Order { get; set; }

    public IMethodReturn Invoke(IMethodInvocation input, GetNextHandlerDelegate getNext)
    {
        unitOfWork.Start();

        try
        {
            return getNext()(input, getNext);
        }
        finally
        {
            unitOfWork.Commit();
        }
    }
}

In that context I use a PerThreadLifetimeManager for the NHibernateUnitOfWork, and code ends up looking like:

[UnitOfWork]
public void Process(Job job)
{
    ...
}

You know, there is really no reason why you couldn’t do the same thing in the MVC context. You could basically ditch the global.asax event hooha and just annotate the Controller task:

[UnitOfWork]
public ActionResult ControllerTaskThatRequiresUoW()
{
    ...
}

It’s more explicit than using the global.asax technique and it would allow you to specify different UoW behavior on each controller task:

[UnitOfWork(IsolationLevel.ReadCommitted]
public ActionResult SomeTaskThatShouldNotReadUncommitedData()
{
}

[UnitOfWork(IsolationLevel.ReadUncommitted)]
public ActionResult AnotherTaskWithDifferentRequirements()
{
}

I’d like to try this out next time I get back into ASP.NET MVC, the global.asax event technique felt a little too magical and I don’t think Uncle Bob would approve.

So, here it is in action. Below is a controller from an ASP.NET MVC application. The method accepts an order in the form of xml for provisioning products in our system.

public ActionResult EnqueueOrders(string orderXml)
{
    var context = new OrderContext(orderXml);

    var pipeline = new FilterPipeline<OrderContext>()
        .Add(new RewriteLegacyUsernameFeature(productFinder))
        .Add(new ValidateOrderXml())
        .Add(new ValidateReferenceCode(customerFinder))
        .Add(new IgnoreOnException(new ValidateRemoteAccountUsernames(packageRepository)))
        .Add(new IgnoreOnException(new ValidateRemoteAccountUniqueEmail(packageRepository)))
        .Add(new EnqueueOrders(customerFacade)).When(new OrderHasNoErrors())
        .Execute(context);

    var xml = BuildResponseFromOrderContext(context);

    return new XmlResult(xml);
}

Most of it is just validation logic, but there are a few meatier pieces. Take a look a the first filter – RewriteLegacyUsernameFeature. If you’ve ever published an API that accepts xml, then you’ve probably wanted to change your schema 5 minutes later. The pipeline is great way to deal with transforming legacy xml on the way in.

Next is the implementation of the FilterPipeline which is essentially a chain of responsibility with a few convenience features.

public class FilterPipeline<T> : IFilter<T>
{
    private IFilterLink<T> head;

    public void Execute(T input)
    {
        head.Execute(input);
    }

    public IFilterConfiguration<T> Add(IFilterLink<T> link)
    {
        var specificationLink = new SpecificationFilterLink<T>(link);

        AppendToChain(specificationLink);

        return specificationLink;
    }

    public IFilterConfiguration<T> Add(IFilter<T> filter)
    {
        return Add(new FilterLinkAdapter<T>(filter));
    }

    public void AppendToChain(IFilterLink<T> link)
    {
        if (head == null)
        {
            head = link;
            return;
        }

        var successor = head;

        while (successor.Successor != null)
        {
            successor = successor.Successor;
        }

        successor.Successor = link;
    }
}

You might be scratching your head and wondering what this business is with both IFilter<T> and IFilterLink<T>. IFilter<T> is just a simpler version of IFilterLink<T> that doesn’t require the implementer to deal with calling the next link in the chain. The subject will always pass through, no short-circuiting, hence the pipeline.

My favorite part  is the SpecificationFilterLink<T> which is a decorator that uses a Specification to decide if the filter should be invoked. So you can do little readable snippets like:

pipeline.Add(new EnqueueOrders(customerFacade)).When(new OrderHasNoErrors());

Maybe this post will get it out of my system and I can move on to other solutions. It’s just so handy…