Software Design Blog - Software Design

Late binding principle: defer resource binding to improve flow

Fri, 29 Jan 2016 10:39:00 +1300

Donald G. Reinertsen, author of �The Principles of Product Development Flow�, asked the question should we assign a resource to a task at the start of a project?

Let�s explore this questions in our software examples below. Will delaying assignment produce light classes, with less memory consumption, and reduced computing waste?

The problem is how can you delay resource demands during object construction? For example, using dependency injection (DI), how do you inject dependencies into a class and delay the construction of these dependencies at the same time?

The solution is to use automatic factories to delay resource demands until it is used.

Download Source Code

Setting the scene

This post will use an illustration of a cloud storage service that relies on an expensive online connection resource. Let�s assume that we cannot modify the constructor behaviour of the resource class. The interfaces and resource implementation are shown below.

public interface IStorageService
{
void Save(string path, Stream stream);
bool HasSufficientSpace(int requiredSizeMb);
}
public interface IStorageResource
{
void UploadStream(string path, Stream stream);
}
public class CloudStorage : IStorageResource
{
public CloudStorage()
{
Console.WriteLine("Establishing cloud connection...");
// Simulate expensive initialisation
System.Threading.Thread.Sleep(5000);
}
public void UploadStream(string path, Stream stream)
{
// your code here
}
}
public class CloudStorageService : IStorageService
{
private readonly IStorageResource _resource;
public CloudStorageService(IStorageResource resource)
{
if (resource == null) throw new ArgumentNullException("resource");
_resource = resource;
}
public void Save(string path, Stream stream)
{
Console.WriteLine("Called Save");
_resource.UploadStream(path, stream);
}
public bool HasSufficientSpace(int requiredSizeMb)
{
Console.WriteLine("Called HasSufficientSpace");
return true; // No need to check, the cloud service has unlimited space
}
}

Evaluating the results

Let�s run the code and observe the output.

var container = new UnityContainer();
container.RegisterType<IStorageService, CloudStorageService>();
container.RegisterType<IStorageResource, CloudStorage>();
var storageService = container.Resolve<IStorageService>();
if (storageService.HasSufficientSpace(100))
{
using (var fileStream = System.IO.File.OpenRead(@"C:\Temp\File.txt"))
{
storageService.Save(@"Files\File01.txt", fileStream);
}
}

Establishing cloud connection...
Called HasSufficientSpace
Called Save

Oops! The resource was initialised before it was used.

The CloudStorageService class is poorly implemented because:

The resource dependency is demanded in the constructor causing a significant start-up delay. By default, Windows will refuse to start the service if it takes longer than 30 sec to initialise.
System memory and computing cycles are wasted since the resource may never be used.

Late binding with an Auto Factory

We are only going to change the CloudStorageService class. Everything else will remain the same, which minimises the risk of potential regression.

The auto factory version is shown below.

public class CloudStorageServiceAutoFactory : IStorageService
{
private readonly Lazy<IStorageResource> _resource;
public CloudStorageServiceAutoFactory(Func<IStorageResource> resource)
{
if (resource == null) throw new ArgumentNullException("resource");
_resource = new Lazy<IStorageResource>(resource);
}
private IStorageResource Resource
{
get { return _resource.Value; }
}
public void Save(string path, Stream stream)
{
Console.WriteLine("Called Save");
Resource.UploadStream(path, stream);
}
public bool HasSufficientSpace(int requiredSizeMb)
{
Console.WriteLine("Called HasSufficientSpace");
return true; // Cloud service has unlimited space
}
}

Note: Unity will automatically pass in a func<IStorageResource> lamba factory function so your bootstrap code doesn�t have to change.

Let�s call the improved CloudStorageServiceAutoFactory class instead.

Called HasSufficientSpace
Called Save
Establishing cloud connection...

Success! The resource demands were deferred until the resource was needed.

Why is this a great solution?

Here is an alternative version as covered in a DevTrends post:

public class CloudStorageServiceBad : IStorageService
{
private readonly Func<IStorageResource> _factory;
private IStorageResource _resource;
public CloudStorageServiceBad(Func<IStorageResource> factory)
{
if (factory == null) throw new ArgumentNullException("factory");
_factory = factory;
}
private IStorageResource Resource
{
get { return _resource ?? (_resource = _factory()); }
}
// The methods goes here
}

Warning! Bad code, do not copy.

The code above is bad because:

A reference is required to the factory and resource, yet the factory is only used once
Performing lazy loading in the Resource property is not thread safe

The solution as shown in the CloudStorageServiceAutoFactory class will pass the factory to Lazy<IStorageResource>, which requires less code and is thread safe. See this post about thread safety.

Let�s compare the output of the two solutions by executing the method in multiple threads:

Parallel.Invoke(() => storageService.Save(@"Files\File01.txt", null),
() => storageService.Save(@"Files\File01.txt", null));

CloudStorageServiceBad output:

Called Save
Called Save
Establishing cloud connection...
Establishing cloud connection...

CloudStorageServiceAutoFactory output:

Called Save
Called Save
Establishing cloud connection...

Success! The CloudStorageServiceAutoFactory class is thread safe.

Manual Construction

For those out there who haven�t transitioned to DI yet, but I highly recommend that you do, here is how you would wire it up manually:

var service = new CloudStorageServiceAutoFactory(() => new CloudStorage());

Summary

This post illustrated how to improve memory utilisation and to reduce computing waste using automatic factories to delay expensive resource demands.

Delaying the demand of resources until the code paths are actually executed can significantly improve application performance.

How to structure DI registration code cleanly

Thu, 21 Jan 2016 06:43:00 +1300

The previous post introduced dependency injection (DI). This post will provide a practical approach to wire up DI cleanly.

The problem is where do we keep our dependency injection registration bootstrap/wiring code?

We don�t want a giant central registration assembly or a monolithic global.asax class
We don�t want to bleed DI into our implementation assemblies that requires DI references
We don�t want to be locked into a specific DI framework

The solution is to componentise registrations and keep DI frameworks out of our implementation and interface libraries.

Download Source Code

What is Unity?

Unity is a DI container which facilitates building loosely coupled apps. It provides features such as object lifecycle management, registration by convention and instance/type interception.

What is MEF?

The Managed Extensibility Framework (MEF) provides DI container capabilities to build loosely coupled apps. It allows an app to discover dependencies implicitly with no configuration required by declaratively specifying the dependencies (known as imports) and what capabilities (known as exports) that are available.

MEF vs Unity

MEF and Unity provide similar capabilities but they both have strengths and weaknesses.

Unity has greater DI capabilities � such as interception
Unity is less invasive since MEF requires developers to sprinkle [Import] and [Export] attributes all throughout the code
MEF has great discoverability features that are not available in Unity

The Winner: MEF for discovery + Unity for DI

Setup

The solution layout of the previous DI introduction post is shown below.

All of the bootstrapping code currently lives in the OrderApplication console assembly. The registration can quickly get out of hand with a large app with many components. The registration is also not discoverable which means we can�t just drop in new dlls to automatically replace existing functionality or add new functionality.

Clean Wiring

Let�s get started with clean wiring in 3 steps.

1. Move each components� DI registration to its own assembly

// Orders.Bootstrap.dll
public class Component
{
private readonly IUnityContainer _container;
public Component(IUnityContainer container)
{
if (container == null) throw new ArgumentNullException("container");
_container = container;;
}
public void Register()
{
_container.RegisterType<IOrderRepository, OrderRepository>();
_container.RegisterType<IEmailService, EmailService>();
_container.RegisterType<IRenderingService, RazaorRenderingService>();
_container.RegisterType<IMailClient, SmtpMailClient>();
_container.RegisterType<IOrderService, OrderService>();
var baseTemplatePath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory,
"EmailTemplates");
_container.RegisterType<ITemplateLocator, TemplateLocator>(
new InjectionConstructor(baseTemplatePath));
}
}

Solved! The Orders.Implementation and Orders.Interfaces assemblies are no longer coupled to a specific DI framework since it doesn�t know about DI.

2. Discover and bootstrap your registration

MEF is great at discovering assemblies so let�s create an interface that can be discovered by exporting the bootstrap interface.

// Bootstrap.Interfaces.dll
public interface IBootstrap
{
void Register();
}

Add the MEF export attribute to the bootstrap component created in step 1.

[Export(typeof(IBootstrap))]
public class Component : IBootstrap
{
private readonly IUnityContainer _container;
[ImportingConstructor]
public Component(IUnityContainer container)
{
if (container == null) throw new ArgumentNullException("container");
_container = container;;
}
public void Register()
{
// Registration code from step 1
}
}

The ResolvingFactory below will perform the discovery and Unity registration.

// Bootstrap.Implementation.dll
public class ResolvingFactory
{
[ImportMany(typeof(IBootstrap))]
private IEnumerable<IBootstrap> Bootstraps { get; set; }
private readonly IUnityContainer _container;
public ResolvingFactory()
{
_container = new UnityContainer();
Initialise();
}
private void Initialise()
{
var catalog = new AggregateCatalog();
catalog.Catalogs.Add(new DirectoryCatalog(GetBinPath()));
using (var mefContainer = new CompositionContainer(catalog))
{
mefContainer.ComposeExportedValue(_container);
mefContainer.SatisfyImportsOnce(this);
}
foreach (var bootstrap in Bootstraps)
{
bootstrap.Register();
}
}
public string GetBinPath()
{
var domainSetup = AppDomain.CurrentDomain.SetupInformation;
return !string.IsNullOrEmpty(domainSetup.PrivateBinPath) ?
domainSetup.PrivateBinPath : domainSetup.ApplicationBase;
}
public T Resolve<T>()
{
return _container.Resolve<T>();
}
}

The new project assembly layout is shown below.

3. Run the solution

Let�s run the new Unity + MEF solution.

// OrderApplication.dll
static void Main(string[] args)
{
var orderModel = new OrderModel()
{
Description = "Design Book",
Customer = new CustomerModel()
{
Email = "[email protected]",
Name = "Jay"
}
};
var factory = new ResolvingFactory();
var orderService = factory.Resolve<IOrderService>();
orderService.Create(orderModel);
}

Solved! Simply drop a new bootstrap dll in the app directory and it will be registered automatically.

Summary

DI code often becomes messy with large amounts of registrations.

This post shows how DI registration can be componentised to keep code clean, simple and discoverable.

Problem solving beyond the basics

Fri, 08 Jan 2016 15:17:00 +1300

Part of my role is to review code and to coach developers.

Reviewing code provides insight into a range of techniques to solve problems. Like many developers, we often steal each other�s ideas. To become a good thief, you really need to be able to identify what is valuable so that you don�t steal someone else�s rubbish code.

Whilst coaching developers, I often take the code submitted for a code review and ask the person I�m coaching to review it. This technique helps to assess the fidelity of a developer to identify good and bad code. It also exposes new potential skills that can be coached or helps with confirming that a developer has mastered a skill.

The aim of this post is to show a working solution and discuss potential problems. A follow up post will provide an alternative that will solve these problems.

Setup

The problem we are trying to solve is to validate a credit card number based on the credit card type. The credit card context model / data transfer object (DTO) is shown below.

public class CreditCard
{
public string Type { get; set; }
public string Name { get; set; }
public string Number { get; set; }
public string Expiry { get; set; }
}
public interface ICreditCardValidator
{
void Validate(CreditCard creditCard);
}

Code Review

The solution that was submitted for a code review is shown below.

public class CreditCardValidator : ICreditCardValidator
{
public void Validate(CreditCard creditCard)
{
if (creditCard.Type.ToLower() == "visa")
{
var visaRegEx = new Regex("^4[0-9]{6,}$");
if (!visaRegEx.IsMatch(creditCard.Number))
throw new Exception("Invalid card");
}
else if (creditCard.Type.ToLower() == "mastercard")
{
var masterCardRegEx = new Regex("^5[1-5][0-9]{5,}$");
if (!masterCardRegEx.IsMatch(creditCard.Number))
throw new Exception("Invalid card");
}
else
{
throw new Exception(string.Format("Card type {0} is unsupported.",
creditCard.Type));
}
}
}

Stop! How many issues can you spot before you continue to read on?

Code Smells

Let's run through a standard set of heuristics to identify code smells.

Duplicate code � both If statements uses a fairly similar pattern but it doesn�t appear to justify refactoring
Long method � the method length appears to be acceptable
Large class � the class fits on one screen and it doesn�t appear to be too large
Too many parameters � it only has one parameter so that's fine
Overuse of inheritance � no inheritance at all
Not testable � the class implements an interface which suggests that clients rely on a contract instead of a concrete implementation which promotes mocking and the class appears to be easily testable

Success! The solution passed the code smell heuristics.

Code Problems

Even though the code doesn't appear to have code smells, the code is not great. Here is a list of problems with the code:

Guard Exception � an ArgumentNullException should be thrown before line 5 when the client calls the validator with a null credit card instance
NullReferenceException � the client will receive an �object reference not set to an instance of an object� exception on line 5 when the card type is null
Throwing Exceptions � throwing custom exceptions such as InvalidCreditCardNumberException is better than throwing a generic Exception which is harder to catch and bubble up
Immutable String Comparison � at least the code is case insensitive using .ToLower() although strings are immutable so the .ToLower() comparison will create a new copy of the string for each if statement. We could just use the string comparison function such as creditCard.Type.Equals("visa", StringComparison.OrdinalIgnoreCase)
Constants � we should avoid using magic strings and numbers in code and use constants instead for names such as credit card names. A CreditCardType Enum could be an alternative if the credit card types are fixed.
Readability � as the number of supported credit cards grows, readability can be improved with a switch statement
Globalisation � error messages can be placed in resource files to provide multilingual support
Performance � the regular expression is created for every credit card number that is validated which can be changed to a singleton. We can use the RegEx compile parameter to improve the execution time.

An alternative solution using a switch statement is shown below.

public class CreditCardValidator : ICreditCardValidator
{
private static readonly Regex VisaRegEx =
new Regex("^4[0-9]{6,}$", RegexOptions.Compiled);
private static readonly Regex MasterCardRegEx =
new Regex("^5[1-5][0-9]{5,}$", RegexOptions.Compiled);
public void Validate(CreditCard creditCard)
{
if (creditCard == null) throw new ArgumentNullException("creditCard");
if (string.IsNullOrWhiteSpace(creditCard.Type))
throw new ArgumentException("The card type must be specified.");
switch (creditCard.Type.ToLower())
{
case "visa":
if (!VisaRegEx.IsMatch(creditCard.Number))
throw new InvalidCardException("Invalid card");
break;
case "mastercard":
if (!MasterCardRegEx.IsMatch(creditCard.Number))
throw new InvalidCardException("Invalid card");
break;
default:
throw new InvalidCardException(
string.Format("Card type {0} is unsupported.", creditCard.Type));
}
}
}

Warning! Don't steal this code. It works but the design is poor.

Even though the code was improved, the design is still poor and breaks SOLID principals.

Open/Closed Principal - The class might be small but is hard to extend by supporting additional credit cards without modifying the code
Single Responsibility Principle - The class knows too much about various credit card types and how to validate them

Summary

The post identified issues with a working solution and discussed fundamental coding practices.

If you can spot more issues, please let me know. If you know how to solve the problem then I�d love you hear from you too.

The next post will discuss how the design can be improved by applying a design pattern.