Java 8 Pocket Guide

Appendix A. Fluent APIs

Fluent APIs, a.k.a. fluent interfaces, are object-oriented APIs designed to make the API code more readable and therefore easier to use. Wiring objects together via method chaining helps accomplish these readability and usability goals. In this design, chained methods generally maintain the same type.

// StringBuilder API
StringBuilder sb = new StringBuilder("palindrome!");
// Method chaining
sb.delete(10, 11).append("s").reverse();
System.out.println("Value: " + sb);

$ Value: semordnilap

To name a few popular fluent APIs written in Java, there is the Java Object Oriented Querying (jOOQ) API, the jMock testing API, the Calculon Android testing API, the Apache Camel integration patterns API, Java 8’s Date Time API (JSR 310), and Java 9’s Money and Currency API (JSR 354). Each of these is considered to contain a Java domain specific language (DSL).

An external DSL can be easily mapped into a new Java internal DSL by using the fluent API approach.

Common method prefixes used in fluent APIs, and acting on objects, include at, format, from, get, to, and with.

The LocalDateTime class of the Date Time API is represented here, first without and then with method chaining:

// Standalone static method
LocalDateTime ldt1 = LocalDateTime.now();
System.out.println(ldt1);

$ 2014-02-26T09:33:25.676

// Static method with method chaining
LocalDateTime ldt2 = LocalDateTime.now()
  .withDayOfMonth(1).withYear(1878)
  .plusWeeks(2).minus(3, ChronoUnit.HOURS);
System.out.println(ldt2); ...