Trying to understand how to create fluent interfaces, and when to use them

Question

How would one create a fluent interface instead of a more tradition approach? Here is a traditional approach:

Interface:

interface IXmlDocumentFactory<T>
{
    XmlDocument CreateXml()                    //serializes just the data
    XmlDocument CreateXml(XmlSchema schema)    //serializes data and includes schema
}

interface IXmlSchemaFactory<T>
{
    XmlSchema CreateXmlSchema()                //generates schema dynamically from type
}

Usage:

var xmlDocFactory = new XmlDocumentFactory<Foo>(foo);
var xmlDocument = xmlDocFactory.CreateXml();

//or...

var xmlDocFactory = new XmlDocumentFactory<Foo>(foo);
var xmlSchemaFactory = new XmlSchemaFactory<Foo>();
var xmlDocument = xmlDocFactory.CreateXml(xmlSchemaFactory.CreateXmlSchema());

I'd like to be able to say:

var xmlDocument = new XmlDocumentFactory<Foo>(foo).CreateXml().IncludeSchema();
//or...
var xmlDocument = new XmlDocumentFacotry<Foo>(foo).CreateXml();

Lastly, is this situation a good fit for fluent interfaces? Or would a more traditional approach make more sense?

score 8 · Accepted Answer · answered May 26 '11 at 13:10

8

The key to making an interface fluent is to ensure the methods all return instances of the interface itself, or some other object that also implements the interface that can continue the processing.

So in your case each of your IXmlDocumentFactory methods has to return an IXmlDocumentFactory so you can continue to call. The final method, if there is one, returns the type you really want?

It makes for very readable code but one thing that still gives me a bit of the willies is return-checking. You have to make very sure that null's can't be returned or else the next 'fluent call' will fail.

answered May 26 '11 at 13:10

n8wrl

19,439
4
63
103

1

_"The final method, if there is one, returns the type you really want?"_ So It probably would be better to say: `var xmlDocmuent = new XmlDocumentFactory(foo).BuildXmlData().IncludeSchema().CreateXml();` or something like that. That was the piece I was missing, as all the examples I looked at I did notice methods returning self. – Matt May 26 '11 at 13:19
@Matt - one of the things i've seen a few times is a final '.Build() method, where each fluent-method does its thing on a 'plan to build' and the .Build() returns the datatype you want. Just an idea. – n8wrl May 26 '11 at 13:27
I like that. Additionally, what about controlling flow? What if this works `.SerializeType().AttachSchema().Build()`, but this doesn't `.AttachSchema().SerializeType().Build()`? What I mean is what if the `AttachSchema` method requires the type to first be serialized (i.e. it's inserting schema to a serialized type). Also what happens if they call Build before `AttachSchema` and/or `SerializeType`. – Matt May 26 '11 at 13:38
@Matt. I guess it depends on how complex you want to get. You could define seperate interfaces that implement the methods such that calling AttachSchema isn't availalbe until you call SerializeType which returns the interface where AttachSchema lives. But if the order is that complex maybe fluent is the way to go - maybe you need a builder-object that has properties or methods that don't care about order, and then Build puts it all together. – n8wrl May 26 '11 at 14:25
Your first sentence and you last reply was key for me. Thanks +1! – Matt May 26 '11 at 16:17

BrokenGlass · Answer 2 · 2011-05-26T14:47:03.867

Three things are important in my mind:

1.) There is an initial method that returns the fluent interface you are going to work with

2.) Each method in the class that implements your fluent interface returns itself so you can continue chaining - these are the real fluent methods.

3.) There is a final method that returns the type that you really want to build.

In your example since you only have two methods, its borderline useful - usually you would have more methods in a fluent interface. Alternatively (which I personally prefer) you can offer both options in your API: A fluent API and a more traditional API (i.e. with optional parameters).

In your case would do something like this:

Edited to respond to comment.

public interface IXmlDocumentFactory<T>
{
    XmlDocument Create();                    //serializes just the data
    IXmlDocumentFactory<T> WithSchema(XmlSchema schema);    //serializes data and includes schema
}

public class DocumentFactory<T> : IXmlDocumentFactory<T>
{
    private XmlSchema _schema;
    private T _data;

    public DocumentFactory(T data)
    {
        _data = data;
    }
    public IXmlDocumentFactory<T> WithSchema(XmlSchema schema)
    {
        _schema = schema;
        return this;
    }
    public XmlDocument Create()
    {
        if (_schema != null)
        {
            //..use schema/data
            return new XmlDocument();
        }
        else //use data
            return new XmlDocument();
    }

    public static IXmlDocumentFactory<T> From(T data)
    {
        return new DocumentFactory<T>(data);
    }
}

Then you can use it like this:

var xmlDoc = DocumentFactory<int>.From(42)
                                 .WithSchema(new XmlSchema())
                                 .Create();

var xmlDoc = DocumentFactory<int>.From(42)
                                 .Create();

Using this idea I have: `return XmlFactory.Build().From(foo).InferSchema().Create();`. However, what if `Build().InferSchema().Create()` is also acceptable, as is `Build().From(foo).Create()`, but `Build().InferSchema().From(foo).Create()` is not? I mean the code would actually work with the latter case, but I don't want it as it seems to change the meaning. In other words, if they call `InferSchema()` before they call `From()`, I'd like for `From()` to not to be an option. — Matt, May 26 '11 at 14:29
@Matt: I have a similar setup - just make the `From()` method your builder - I will add to my example. — BrokenGlass, May 26 '11 at 14:39

score 3 · Answer 3 · answered May 26 '11 at 13:12

IMO, fluent APIs do have their value. Fluently configuring a component feels more like an English sentence, easily read from start to finish. The intent of a developer is more easily comprehended.

For examples of implementation, please refer to such projects as Autofac, Moq and Fluent NHibernate

Trying to understand how to create fluent interfaces, and when to use them

3 Answers3