Better software through software architecture and devops

@jamessnape

Category Archives: sample solution

  • I’m currently trying to learn F# because I’m keen to learn new programming styles as well as languages. It turns out that many of the concepts we C# programmers know and love such as Linq (monads), generics and async workflows originated in either F# or other functional languages. Thinking ‘functionally’ is a great skill to have too. How does this apply to surrogate key mapping? Well to borrow a notation from F# we are looking for a function like this:

    string –> int

    That is, a function that takes a string (the business key) and returns an integer (the surrogate key). Surrogate key lookup is a perfect fit for the functional view where “functions have no side effects”. Pass the same string to our lookup function any number of times and it should return the same integer value. The poorly performing version of this function might run off to the database every call and retrieve the value but there is a familiar functional technique called Memoization that can help. C# programmers might call this technique “store the values in a hashtable and only call the database if the value is missing”. A few other optimisations are necessary. Firstly, memoization will only cache the result of a single call so if we have a few hundred thousand dimension members in the database it will still take a lot of calls to populate the cache. Secondly, my lookup function doesn’t really care about the mechanics for the real database call so it would be nice if we could abstract that away. Finally, because I intend this class to be used a part of a multithreaded pipeline it needs to make sure that the internal data structures are protected. Piecing these requirements together we can start to flesh out the code. The main map function as we mentioned takes a string and returns an int:

    public int Map(string businessKey) { }

    Since we want to prime the cache with a set of values and abstract the real lookup functionality the best place to configure this is in the constructor:

    public DimensionMapper(IDictionary<string, int>initialCache, Func<string, int> lookup) { }

    Assuming the constructor just saves these parameters for later we can create a first cut version of the Map function:

    public int Map(string businessKey)
    {
        int surrogateKey;
    
        if (this.map.TryGetValue(businessKey, out surrogateKey))
        {
            return surrogateKey;
        }
    
        surrogateKey = this.lookup(businessKey);
        this.map.Add(businessKey, surrogateKey);
    
        return surrogateKey;
    }

    This works but it isn’t thread safe. For that we need a ReaderWriterLockSlim since only writes need to be synchronised. If you look at the code above there are two parts to it – the first few lines check the cache and return a value if it exists (the majority path); the last three lines are concerned with calling the real lookup function and populating the cache with the result when it doesn’t exist. Splitting on this boundary allows us to wrap the first part in a read lock and the second in a write lock - turning the write part into a separate function is a little cleaner:

    public int Map(string businessKey)
    {
        this.updateLock.EnterUpgradeableReadLock();
    
        try
        {
            int surrogateKey;
    
            if (this.map.TryGetValue(businessKey, out surrogateKey))
            {
                return surrogateKey;
            }
    
            return this.Lookup(businessKey);
        }
        finally
        {
            this.updateLock.ExitUpgradeableReadLock();
        }
    }
    
    private int Lookup(string businessKey)
    {
        this.updateLock.EnterWriteLock();
    
        try
        {
            int surrogateKey = this.lookup(businessKey);
            this.map.Add(businessKey, surrogateKey);
            return surrogateKey;
        }
        finally
        {
            this.updateLock.ExitWriteLock();
        }
    }

    So we have most of the class written now and I haven’t discussed anything to do with databases or how we get a real surrogate key because…well its not relevant here since a function is passed to the constructor. I like this ability to concentrate on just a single algorithm and not worry about the wider solution. From what I’ve learned so far F# is better as this than C#.

    For the full class definition see the full source file in context and associated unit tests.

    This entry was posted in sample-solution  and tagged #f #functional #surrogate-key  on .
    Discuss this on Twitter or LinkedIn
  • I’ve been working on this for a few weeks now, half an hour at a time in the evenings and I can safely say it’s pretty hard to maintain a train of thought in thirty minute intervals. However a bare minimum implementation is complete and ready to discuss.

    We start with an acceptance test:

    https://gist.github.com/jsnape/5887988

    The first part of the feature describes the user story and the second part tells us that when we load three patient referrals then the total count should be 3 with 1 on the 1st January.

    I’m using SpecFlow for acceptance tests since it is very easy to define tables and there are some useful binding utilities as we will see. After entering the test we can immediately compile the application and run the tests without writing anything else. The test will obviously fail since we haven’t written any code. In fact the acceptance test will stay broken for some time as we write code and unit tests. When it passes we know the feature is done.

    So thinking about this functionally we effectively want to write a function that transforms an enumerable of source referral records into an enumerable of referral facts; then pipe this iterator into a SqlBulkCopy instance. Effectively this code needs to work:

    referralrepository.BulkCopy(referrals.Select(x => mapper.Map(x)));

    This is a Linq transform with a mapping function applied to each item in the source list. In the next few posts I’m going to break it into bite size chunks to implement.

    This entry was posted in sample-solution  and tagged #linq #mental-health-project #specflow  on .
    Discuss this on Twitter or LinkedIn
  • Last time we were looking at the mental health project I was discussing the dimensional model. I think its time to have a crack at some code now. But this first session is just about setting up my project.

    There are some key things every agile project should do:

    • Automated build with acceptance and unit tests
    • Automated code analysis
    • Automated deployment with integration tests

    Note everything is automated - it has to be repeatable and not need human intervention or it won’t get done. I’m a big fan of continuous integration and continuous deployment so I’m going to use Team City as a build service since its free for a single agent.

    Team City is a very configurable and powerful tool but I want to make sure that I can build and deploy from my local command line in exactly the same way that the Team City agent will since it makes debugging issues easier and allows developers to check the build works before committing.

    There are lots of build script tools around such as FinalBuilder but I prefer MSBuild since its readily available and a text format. Visual Studio uses MSBuild internally but we are not going to change project files; we are going to create a higher level script to tie everything together. Since this is a simple start it’s all going in one build file.

    https://gist.github.com/jsnape/5730292

    The build script is split into 2 main parts. At the top are property and item definitions – this is the build metadata controlling what and how the build will happen. Below that are Imports and Targets which deal with the mechanics of building. This split makes it easy to add new projects and settings without having to change your overall build script.

    There are four main targets listed which are Clean, SourceAnalysis, Compile and Test. The last three of which make a build. It’s fairly self-explanatory but if you don’t know MSBuild script imagine anything in a $() is a single value or variable, @() is a list of items. Each target has a list of tasks which are executed in order to complete the target.

    So, this script is very simple; it just runs StyleCop over a set of source files, builds a Visual Studio solution and runs Xunit against a set of assemblies. Not much but it gives us a single command line action to build and test the solution as we add features:

    PS> msbuild draco.proj

    This is then setup as a single step in TeamCity. Every check-in causes the build to run and tests to execute.

    The complete set of source for this project is available at https://github.com/jsnape/draco.

    This entry was posted in sample-solution  and tagged #build #build-automation #build-management #ci #continuous-integration #deployment  on .
    Discuss this on Twitter or LinkedIn
  • For this week’s post I want to continue the sample solution. Even though I’m going to be as agile as possible we still need to have a rough idea of a roadmap and the best way to do that is with a dimensional model.

    Each business process we want to model is represented as a fact on columns. They are all to be stored at the transactional grain except possibly admissions. The conformed dimensions are listed on rows with the facts they are related to.

    ReferralAssessmentTreatmentDischargeComplaintIncidentAdmission
    Date
    Diagnosis
    Health Professional
    Patient
    Referrer
    Service (Tier)
    Time
    Treatment Outcome
    Clinic

    It is interesting to note that this is a very patient focused model since that dimension is related to every fact. There are some unanswered questions within the model though:

    • How do we represent treatment outcomes? Is there a standard method? Can this be represented in a single dimension?
    • What grain are admissions? Given the goal of calculating ‘bed days’ we might need to model them as events in progress.

    I think we have enough to make a start and I don’t think we will deliver faster if we stop to resolve these issues first. Initially I’m going to concentrate on referrals, assessments and discharges since the number of patients in the system is one of the most useful metrics to monitor.

    This entry was posted in sample-solution  and tagged #dimensional-model #mental-health #mental-health-project  on .
    Discuss this on Twitter or LinkedIn
  • Architecture shares something with testing in that resources are limited so effort is best directed toward maximising risk reduction.

    The amount of ‘architecture’ in a solution should also reflect the risk associated with a project. For example the sample solution I’m creating carries almost no risk apart from my pride so a light touch is warranted.

    However in a real solution what are the major risks? Where should we concentrate our efforts? Below are some of the common risks associated with business intelligence projects:

    • Unclean data e.g. Key pathologies – see later post.
    • Unreliable sources – how are failed connections, retries and duplicates handled?
    • Data volumes – what are the expected peak volumes? What will happen if these peaks are exceeded?
    • Latency requirements – can data be supplied to users fast enough? What is the business cost of delays?
    • Testability – how testable is the solution? How long can you keep going before technical debt catches up with you?
    • History and archive – in my experience most source systems don’t keep a full fidelity history so it ends up being the data warehouse’s responsibility.
    • Staying agile – unfortunately many problems with business intelligence solutions are due to an inability to change things; once users, reports, spread-sheets, and ETL code depend on data warehouse schemas or cube designs the whole thing becomes very difficult to change.
    • Disaster recovery – what happens when your server dies? Network fails? Data centre fails?
    • Scalability – what are your expected user loads? what happens if they are exceeded? are there any events that could cause your user load to be drastically exceeded?
    • Usability – how will your users interact with the system? how much training will they need? what if they need help? how can you make the solution easier to use?

    “Agile architecture is the art of constraining a solution in order to optimise competing stakeholder concerns whilst maximising the number of options for future design decisions.” – James Snape (just now)

    So to be agile lets just concentrate on the risks and try to not be too prescriptive over the final solution. Everything else can generally be quickly changed if it doesn’t work out.

    This entry was posted in sample-solution  and tagged #architecture #business-intelligence #data-warehouse #risk #stakeholder-concerns  on .
    Discuss this on Twitter or LinkedIn