Expression Builder
8 August 2013
One of the problems with a FluentInterface is that it results in some odd looking methods. Consider this example:
customer.newOrder() .with(6, “TAL”) .with(5, “HPK”).skippable() .with(3, “LGV”) .priorityRush();
Methods like with
, skippable
, and
priorityRush
don't sit well on the Order class. The
naming works well in the context of the little
DomainSpecificLanguage that the fluent interface
provides, but we usually expect APIs in the form of what I call a
Command-Query API. In a command-query API each method makes
sense individually in any context. It may also honor such principles
as CommandQuerySeparation which in Java means that
methods that change the ObservableState of an object
shouldn't have a return value. Mixing fluent-style methods with
command-query methods may lead to confusion because fluent methods
can violate the expectations of what most APIs should look like.
An Expression Builder is a solution to this problem. An expression builder is a separate object on which we define the fluent interface that then translates the fluent calls to the underlying regular API calls. So an expression builder for the order case would look something like this.
public class OrderBuilder { private Order subject = new Order(); private OrderLine currentLine; public OrderBuilder with(int quantity, String productCode) { currentLine = new OrderLine(quantity, Product.find(productCode)); subject.addLine(currentLine); return this; } public OrderBuilder skippable() { currentLine.setSkippable(true); return this; } public OrderBuilder priorityRush() { subject.setRush(true); return this; } public Order getSubject() { return subject; } }
In this case I have a single expression builder class, but you
can also have a small structure of builders, something like a customer
builder, order builder, and line builder. Using a single object means
you need a variable to keep track of what line you are working on for
the skippable
method. Using a structure can avoid this,
but is a bit more complicated and you need to ensure lower level
builders can handle methods that are intended for higher order
builders. In this case an OrderLineBuilder
would need to
have delegating methods for all the methods of the
OrderBuilder
.
Further Reading
I talk in more detail about Expression Builders in my book on Domain-Specific Languages
A good, open example of the use of an expression builder is in the JMock library. I found the OOPSLA paper describing the evolution of JMock's DSL handling very helpful.
Revision History
First published 4 January 2007. Revised 8 August 2013.