I've been asked repeatedly - what are fluent APIs and how does it relate to the builder pattern. 
These are good questions and instead of just sending a link or two, here's a blog about it.

First, what is Fluent API or interface?

"Fluent interface (as first coined by Eric Evans and Martin Fowler) is an implementation of an object oriented 
API that aims to provide for more readable code. A fluent interface is normally implemented by using method 
cascading (concretely method chaining) to relay the instruction context of a subsequent call."

This highlights two important characteristics of a fluent API - readability and method chaining. Here's an
example from Gang of Four "Design Patterns: Elements of Reusable OO Software" -
Fluent API is
Maze maze = 
    new Maze.MazeBuilder().
        buildRoom(1).
        buildRoom(2).
        buildDoor(1,2).
        buildMaze();
Non-fluent API would look like
Maze maze = new Maze();
maze.buildMaze();
maze.buildRoom(1);
maze.buildRoom(2);
maze.buildDoor(1,2)

The examples above are chaining methods to build or construct an object. This actually ties two concepts
together. When fluent API is used for building an object, it is implementing the builder pattern.

What is the builder pattern?

"The builder pattern is a design pattern that allows for the step-by-step creation of complex objects using 
the correct sequence of actions. The construction is controlled by a director object that only needs to know 
the type of object it is to create." -- GoF

"Builder pattern separates the construction of a complex object from its representation. This has the 
immediate effect of making a complex target class simpler. It lets a builder class focus on the proper 
construction of an object, leaving the target class to focus on the operation of a valid instance. This is 
especially useful when you want to ensure the validity of an object before instantiating it and don’t want 
the associated logic to appear in the target class’s constructors. A builder also accommodates step-by-step 
construction, which often occurs when you create an object by parsing text." -- Design Patterns in Java

Hence, fluent testing with builder pattern is particularly useful when we have to construct a complex object.
This also allows you to write better code as you will be addressing the following when designing the 
construction of the object (see Petri K's blog for more details) -

  1. Identifying the properties that cannot be updated after the object is created by making them final.
  2. Identifying the properties that can be updated after creation and the best way to update them. 

When you're done, you should see these characteristics of a builder pattern 
  • Constructor of the object is private
  • Creation of the object is via its builder static class
  • The builder has mandatory parameters in its constructor
  • The builder has setters for any optional parameters
  • The builder has the responsibility to check for invalid data
  • Object immutability is easily supported with final attributes and only public getters for these attributes
  • You have created a readable DSL for building your complex object


Finally, here's an example from Effective Java, which demonstrates all the characteristics 
of the builder pattern listed above -

Builder pattern is
 public class NutritionFacts {
  private final int servingSize;
  private final int servings;
  private final int calories;
  private final int fat;
  private final int sodium;
  private final int carbohydrate;
  public static class Builder {
    // Required parameters
    private final int servingSize;
    private final int servings;
    // Initialize optional parameters
    private int calories      = 0;
    private int fat           = 0;
    private int carbohydrate  = 0;
    private int sodium        = 0;
    public Builder(int servingSize,
                   int servings) {
       this.servingSize = servingSize;
       this.servings    = servings;
    }
    public Builder calories(int val) { 
       calories = val; 
       return this; 
    }
    public Builder fat(int val) { 
      fat = val; 
      return this;
    }
    public Builder carbohydrate(int val) {
      carbohydrate = val; 
      return this; 
    }
    public Builder sodium(int val) { 
      sodium = val; 
      return this; 
    }
    public NutritionFacts build() {
        return new NutritionFacts(this);
    }
  }
  private NutritionFacts(Builder builder) {
    servingSize  = builder.servingSize;
    servings     = builder.servings;
    calories     = builder.calories;
    fat          = builder.fat;
    sodium       = builder.sodium;
    carbohydrate = builder.carbohydrate;
  }
}

NutritionFacts cocaCola = new
  NutritionFacts.Builder(240, 8).
    calories(100).sodium(35).
    carbohydrate(27).
    build();
Non-builder pattern would look like
public class NutritionFacts {
  private int servingSize  = -1;
  private int servings     = -1;
  private int calories     = 0;
  private int fat          = 0;
  private int sodium       = 0;
  private int carbohydrate = 0;
  public NutritionFacts(
     int servingSize, int servings) {}
  public NutritionFacts( 
     int servingSize, int servings, 
     int calories) {...}
  public NutritionFacts(
     int servingSize, int servings, 
     int calories, int fat) {...}
  public NutritionFacts(
     int servingSize, int servings, 
     int calories, int fat, 
     int sodium) {...}
  public NutritionFacts(
       int servingSize, int servings, 
       int calories, int fat,
       int sodium, int carbohydrate) {
     this.servingSize  = servingSize;
     this.servings     = servings;
     this.calories     = calories;
     this.fat          = fat;
     this.sodium       = sodium;
     this.carbohydrate = carbohydrate;
  }
  public void setServingSize(int val)
  {...}
  public void setServings(int val) {}
  public void setCalories(int val) {}
  public void setFat(int val) {}
  public void setSodium(int val) {}
  public void setCarbohydrate(int val) {}
}

NutritionFacts cocaCola =
    new NutritionFacts(
        240, 8, 100, 0, 35, 27);
// Another way to create NutritionFacts
NutritionFacts cocaCola = new NutritionFacts();
cocaCola.setServingSize(240);
cocaCola.setServings(8);
cocaCola.setCalories(100);
cocaCola.setSodium(35);
cocaCola.setCarbohydrate(27);