Disclaimer: Authorship is not equal to Authority.  I don’t claim to be an expert in this domain.  I’m merely learning by doing so take what I write with a pinch of salt!

Fluent Interfaces & Fluent APIs

A fluent interface to me is a the way you interact with a class in a fluent fashion.  A fluent API is how you interact with a framework of classes in a fluent fashion.  In all reality the terms are interchangeable with one another.

Over the last month I have been thinking a lot about fluent interface design in C# to create a DSL for an “Fluent” API I will be working on.  I am starting to see more and more “Fluent” APIs emerging in the .NET space.

I am currently researching quite heavily in this area and I will be blogging about the different approaches that can be taken to develop an effective Fluent API.  I want to know first hand how to create structured and compiler controlled sentences, the positives and negatives of doing so by experiencing the process of developing and developing with my own Fluent API.

Definitions

“In software engineering, a fluent interface (as first coined by Eric Evans and Martin Fowler) is a way of implementing an object oriented API in a way that aims to provide for more readable code.  A fluent interface is normally implemented by using method chaining to relay the instruction context of a subsequent call (but a fluent interface entails more than just method chaining).” Wikipedia: Fluent Interface

“Typically, method chaining simply consists of many methods on a class, each of which return the current object itself. This enables invoking another method on the same object immediately, leading to code that may look something like:” Wikipedia: Method Chaining

Simple Fluent Interface

This is a simple example, my goal is to elaborate into more complex scenarios in later posts.

Here is an example of a fluent interface for creating a Coffee, it could be said we are creating a ‘internal’ DSL  for creating coffee.

The first thing to note is that all public methods return ‘this’ in turn allowing us to chain methods together.

public class CoffeeItem : ICoffeeItem
{
    public bool HasMilk { get; set; }
 
    public bool HasCream { get; set; }
 
    public CoffeeSize Size { get; set; }
 
    public ICoffeeBlend Blend { get; set; }
 
    public ICoffeeItem SetSizeTo(CoffeeSize size)
    {
        Size = size;
        return this;
    }
 
    public ICoffeeItem WithCream()
    {
        HasCream = true;
        return this;
    }
 
    public ICoffeeItem WithMilk()
    {
        HasMilk = true;
        return this;
    }
 
    public ICoffeeItem SetBlendTo(ICoffeeBlend blend)
    {
        Blend = blend;
        return this;
    }
}

Lets create an order and test that it works with a unit test.

[Test]
public void CoffeeItem_OrderAJavaSumutraWithCreamOfSizeEpic_ShouldContainSaidAttributes()
{
    var coffee = new CoffeeItem();
 
    //Set Order
    coffee.SetBlendTo(new JavaSumutra()).WithCream().SetSizeTo(CoffeeSize.Epic);
 
    //Assert that order was issued correctly
    Assert.That(coffee.HasCream, Is.True);
    Assert.That(coffee.Blend, Is.TypeOf(typeof(JavaSumutra)));
    Assert.That(coffee.Size, Is.EqualTo(CoffeeSize.Epic));
}

I find this a nice way to write software, and it lends well to test driven development.  Now lets create a Coffee Order which will contain many coffees.

public class CoffeeOrder
{
    public CoffeeOrder()
    {
        CoffeeItems = new List();
    }
 
    public List CoffeeItems { get; set; }
 
    public ICoffeeItem AddCoffee(ICoffeeItem coffee)
    {
        CoffeeItems.Add(coffee);
        return coffee;
    }
}

So now we can create a coffee order which contains the a coffee with its attributes being set in a a sentence.  We can run this inside a unit test like so:

[Test]
public void AddCoffee_WhenPassedACoffee_ShouldContainCoffee()
{
    var order = new CoffeeOrder();
    var coffee = new CoffeeItem();
 
    order.AddCoffee(coffee)
        .SetBlendTo(new JavaSumutra())
        .WithCream()
        .SetSizeTo(CoffeeSize.Small);
 
    Assert.That(order.CoffeeItems, Has.Member(coffee));
}

So that concludes the simple Coffee example.  It is quite contrived but hopefully gives a quick and dirty glimpse at what a Fluent Interface is.

Topics I wish to cover next in the near future:

• Returning Interfaces to Control sentence structure within Fluent Interfaces.
• Using Extensions Methods (C# 3.0) within Fluent Interfaces.
• An overview of Quality Open Source Fluent APIs in .NET and what you can learn.
• Passing in predicates and utilizing lambda expressions in Fluent  Interfaces.
• Internal versus External DSLs.