Expression Builder

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.