ExpressionBuilder

4 January 2007

domain specific language

tags:

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 methods to make sense in their own right. The methods violate the CommandQuerySeparation which in Java means that methods that change the ObservableState of an object shouldn't have a return value. If we supply methods that make more individual sense, like addLine, we also go against the notion of a MinimalInterface.

At the heart of all this is a mismatch between what a fluent interface needs and our usual guidelines for API design. What works well for a regular API doesn't work for a fluent one and vice versa.

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.

For an interesting open example of expression builder, take a look at the JMock library. They use an interesting variant of this approach to handle their little DSL for expectations. There is a single expression builder object (InvocationMockerBuilder). As usual with a single builder object, every call to a builder method ends with a return this to continue the method chaining. The interesting twist is that the return type varies, depending on which part of the expression we are in. The returning interface provides only the methods that make sense for that part of the expression. This supports better error checking, and also means that the method completion you find on IDEs works better by only suggesting methods that are legal at that point of the expression.

You can find out more about the design of the DSL handling in JMock, and how it has evolved from a regular API, by reading Steve and Nat's OOPSLA paper.