Fluent interface

Short description: Software engineering object-oriented API

This article is about the API design pattern. For the user interface introduced in Microsoft Office 2007, see Microsoft Office 2007 § User interface. For Microsoft's 2017 visual design language, see Fluent Design System.

In software engineering, a fluent interface is an object-oriented API whose design relies extensively on method chaining. Its goal is to increase code legibility by creating a domain-specific language (DSL). The term was coined in 2005 by Eric Evans and Martin Fowler.[1]

## Contents

* 1 Implementation
* 2 History
* 3 Examples
* 3.1 C#
* 3.2 C++
* 3.3 Java
* 3.4 JavaScript
* 3.5 Scala
* 3.6 Raku
* 3.7 PHP
* 3.8 Python
* 3.9 Swift
* 4 Immutability
* 4.1 JavaScript example
* 5 Problems
* 5.1 Errors cannot be captured at compile time
* 5.2 Debugging and error reporting
* 5.3 Logging
* 5.4 Subclasses
* 6 See also
* 7 References
* 8 External links

## Implementation

A fluent interface is normally implemented by using method chaining to implement method cascading (in languages that do not natively support cascading), concretely by having each method return the object to which it is attached , often referred to as `this` or `self`. Stated more abstractly, a fluent interface relays the instruction context of a subsequent call in method chaining, where generally the context is

* Defined through the return value of a called method
* Self-referential, where the new context is equivalent to the last context
* Terminated through the return of a void context

Note that a "fluent interface" means more than just method cascading via chaining; it entails designing an interface that reads like a DSL, using other techniques like "nested functions and object scoping".[1]

## History

The term "fluent interface" was coined in late 2005, though this overall style of interface dates to the invention of method cascading in Smalltalk in the 1970s, and numerous examples in the 1980s. A common example is the iostream library in C++, which uses the `<<` or `>>` operators for the message passing, sending multiple data to the same object and allowing "manipulators" for other method calls. Other early examples include the Garnet system (from 1988 in Lisp) and the Amulet system (from 1994 in C++) which used this style for object creation and property assignment.

## Examples

### C#

C# uses fluent programming extensively in LINQ to build queries using "standard query operators". The implementation is based on extension methods.

// An English-to-French dictionary of animal names
Dictionary<string, string> translations = new()

{"cat", "chat"},
{"dog", "chien"},
{"fish", "poisson"},
{"bird", "oiseau"}

// Find translations for English words containing the letter "a",
// sorted by length and displayed in uppercase
IEnumerable<string> query = translations
.Where(t => t.Key.Contains("a"))
.OrderBy(t => t.Value.Length)
.Select(t => t.Value.ToUpper());

// The same query constructed progressively:
IEnumerable<string> filtered = translations.Where(t => t.Key.Contains("a"));
IEnumerable<string> sorted = filtered.OrderBy(t => t.Value.Length);
IEnumerable<string> finalQuery = sorted.Select(t => t.Value.ToUpper());

Fluent interface can also be used to chain a set of methods, which operate on/share the same object. Instead of creating a customer class, we can create a data context which can be decorated with fluent interface as follows.

// Defines the data context
class Context

public string FirstName { get; set; }
public string LastName { get; set; }
public string Sex { get; set; }
public string Address { get; set; }

class Customer

private Context _context = new Context(); // Initializes the context

// set the value for properties
public Customer FirstName(string firstName)

_context.FirstName = firstName;
return this;

public Customer LastName(string lastName)

_context.LastName = lastName;
return this;

public Customer Sex(string sex)

_context.Sex = sex;
return this;

public Customer Address(string address)

_context.Address = address;
return this;

// Prints the data to console
public void Print()

Console.WriteLine($"First name: {_context.FirstName} \nLast name: {_context.LastName} \nSex: {_context.Sex} \nAddress: {_context.Address}");

class Program

static void Main(string[] args)

// Object creation
Customer c1 = new Customer();
// Using the method chaining to assign & print data with a single line
c1.FirstName("vinod").LastName("srivastav").Sex("male").Address("bangalore").Print();

The .NET testing framework NUnit uses a mix of C#'s methods and properties in a fluent style to construct its "constraint based" assertions:

Assert.That(() => 2 * 2, Is.AtLeast(3).And.AtMost(5));

### C++

A common use of the fluent interface in C++ is the standard iostream, which chains overloaded operators.

The following is an example of providing a fluent interface wrapper on top of a more traditional interface in C++:

import std;

using std::string;
using std::vector;

// Basic definition
class GlutApp {
private:
int width;
int height;
int x;
int y;
int displayMode;
vector<string> args;
string title;
public:
GlutApp(const vector<string>& args):
args{args} {}

void setDisplayMode(int mode) noexcept {
displayMode = mode;

nodiscard
int getDisplayMode() const noexcept {
return displayMode;

void setWindowSize(int w, int h) noexcept {
width = w;
height = h;

void setWindowPosition(int x, int y) noexcept {
this->x = x;
this->y = y;

void setTitle(const string& title) noexcept {
this->title = title;

void create() {
// ...

// Basic usage
int main(int argc, char* argv[]) {
vector<string> args(argv, argv + argc);
GlutApp app(args);
app.setDisplayMode(GLUT_DOUBLE | GLUT_RGBA | GLUT_ALPHA | GLUT_DEPTH); // Set framebuffer params
app.setWindowSize(500, 500); // Set window params
app.setWindowPosition(200, 200);
app.setTitle("My OpenGL/GLUT App");
app.create();

// Fluent wrapper
class FluentGlutApp : private GlutApp {
public:
FluentGlutApp(const vector<string>& args):
GlutApp(args) {} // Inherit parent constructor

FluentGlutApp& withDoubleBuffer() {
setDisplayMode(getDisplayMode() | GLUT_DOUBLE);
return *this;

FluentGlutApp& withRGBA() {
setDisplayMode(getDisplayMode() | GLUT_RGBA);
return *this;

FluentGlutApp& withAlpha() {
setDisplayMode(getDisplayMode() | GLUT_ALPHA);
return *this;

FluentGlutApp& withDepth() {
setDisplayMode(getDisplayMode() | GLUT_DEPTH);
return *this;

FluentGlutApp& across(int w, int h) {
setWindowSize(w, h);
return *this;

FluentGlutApp& at(int x, int y) {
setWindowPosition(x, y);
return *this;

FluentGlutApp& named(const string& title) {
setTitle(title);
return *this;

// It doesn't make sense to chain after create(), so don't return *this
void create() {
GlutApp::create();

// Fluent usage
int main(int argc, char* argv[]) {
vector<string> args(argv, argv + argc);
FluentGlutApp(args)
.withDoubleBuffer()
.withRGBA()
.withAlpha()
.withDepth()
.at(200, 200)
.across(500, 500)
.named("My OpenGL/GLUT App")
.create();

### Java

An example of a fluent test expectation in the jMock testing framework is:[1]

mock.expects(once()).method("m").with( or(stringContains("hello"),
stringContains("howdy")) );

The jOOQ library models SQL as a fluent API in Java:

Author author = AUTHOR.as("author");
create.selectFrom(author)
.where(exists(selectOne()
.from(BOOK)
.where(BOOK.STATUS.eq(BOOK_STATUS.SOLD_OUT))
.and(BOOK.AUTHOR_ID.eq(author.ID))

The fluflu annotation processor enables the creation of a fluent API using Java annotations.

The JaQue library enables Java 8 Lambdas to be represented as objects in the form of expression trees at runtime, making it possible to create type-safe fluent interfaces, i.e., instead of:

Customer customer = new Customer();
customer.property("name").eq("John")

One can write:

method<Customer>(customer -> customer.getName() == "John")

Also, the mock object testing library EasyMock makes extensive use of this style of interface to provide an expressive programming interface.

Collection mockCollection = EasyMock.createMock(Collection.class);
EasyMock
.expect(mockCollection.remove(null))
.andThrow(new NullPointerException())
.atLeastOnce();

In the Java Swing API, the LayoutManager interface defines how Container objects can have controlled Component placement. One of the more powerful `LayoutManager` implementations is the GridBagLayout class which requires the use of the `GridBagConstraints` class to specify how layout control occurs. A typical example of the use of this class is something like the following.

import javax.swing.JLabel;
import javax.swing.JPanel;
import javax.swing.JTextField;

GridBagLayout gl = new GridBagLayout();
JPanel p = new JPanel();
p.setLayout(gl);

JLabel l = new JLabel("Name:");
JTextField nm = new JTextField(10);

GridBagConstraints gc = new GridBagConstraints();
gc.gridx = 0;
gc.gridy = 0;
gc.fill = GridBagConstraints.NONE;
p.add(l, gc);

gc.gridx = 1;
gc.fill = GridBagConstraints.HORIZONTAL;
gc.weightx = 1;
p.add(nm, gc);

This creates a lot of code and makes it difficult to see what exactly is happening here. The `Packer` class provides a fluent mechanism, so you would instead write:[2]

import javax.swing.JLabel;
import javax.swing.JPanel;
import javax.swing.JTextField;

JPanel p = new JPanel();
Packer pk = new Packer(p);

JLabel l = new JLabel("Name:");
JTextField nm = new JTextField(10);

pk.pack(l).gridx(0).gridy(0);
pk.pack(nm).gridx(1).gridy(0).fillx();

There are many places where fluent APIs can simplify how software is written and help create an API language that helps users be much more productive and comfortable with the API because the return value of a method always provides a context for further actions in that context.

### JavaScript

There are many examples of JavaScript libraries that use some variant of this: jQuery probably being the most well known. Typically, fluent builders are used to implement "database queries", for example in the Dynamite client library:

// getting an item from a table
client.getItem('user-table')
.setHashKey('userId', 'userA')
.setRangeKey('column', '@')
.execute()
.then(function(data) {
// data.result: the resulting object

A simple way to do this in JavaScript is using prototype inheritance and `this`.

// example from https://schier.co/blog/2013/11/14/method-chaining-in-javascript.html

class Kitten {
constructor() {
this.name = 'Garfield';
this.color = 'orange';

setName(name) {
this.name = name;
return this;

setColor(color) {
this.color = color;
return this;

save() {
console.log(
`saving ${this.name}, the ${this.color} kitten`

return this;

// use it
new Kitten()
.setName('Salem')
.setColor('black')
.save();

### Scala

Scala supports a fluent syntax for both method calls and class mixins, using traits and the `with` keyword. For example:

class Color { def rgb(): Tuple3[Decimal] }
object Black extends Color { override def rgb(): Tuple3[Decimal] = ("0", "0", "0"); }

trait GUIWindow {
// Rendering methods that return this for fluent drawing
def set_pen_color(color: Color): this.type
def move_to(pos: Position): this.type
def line_to(pos: Position, end_pos: Position): this.type

def render(): this.type = this // Don't draw anything, just return this, for child implementations to use fluently

def top_left(): Position
def bottom_left(): Position
def top_right(): Position
def bottom_right(): Position

trait WindowBorder extends GUIWindow {
def render(): GUIWindow = {
super.render()
.move_to(top_left())
.set_pen_color(Black)
.line_to(top_right())
.line_to(bottom_right())
.line_to(bottom_left())
.line_to(top_left())

class SwingWindow extends GUIWindow { ... }

val appWin = new SwingWindow() with WindowBorder
appWin.render()

### Raku

In Raku, there are many approaches, but one of the simplest is to declare attributes as read/write and use the `given` keyword. The type annotations are optional, but the native gradual typing makes it much safer to write directly to public attributes.

class Employee {
subset Salary         of Real where * > 0;
subset NonEmptyString of Str  where * ~~ /\S/; # at least one non-space character

has NonEmptyString $.name    is rw;
has NonEmptyString $.surname is rw;
has Salary         $.salary  is rw;

method gist {
return qq:to[END];
Name:    $.name
Surname: $.surname
Salary:  $.salary
END

my $employee = Employee.new();

given $employee {
.name    = 'Sally';
.surname = 'Ride';
.salary  = 200;

say $employee;

# Output:
# Name:    Sally
# Surname: Ride
# Salary:  200

### PHP

In PHP, one can return the current object by using the `$this` special variable which represent the instance. Hence `return $this;` will make the method return the instance. The example below defines a class `Employee` and three methods to set its name, surname and salary. Each return the instance of the `Employee` class allowing to chain methods.

<?php declare(strict_types=1);

final class Employee

private string $name;
private string $surname;
private string $salary;

public function setName(string $name): self

$this->name = $name;

return $this;

public function setSurname(string $surname): self

$this->surname = $surname;

return $this;

public function setSalary(string $salary): self

$this->salary = $salary;

return $this;

public function __toString(): string

return <<<INFO
Name: {$this->name}
Surname: {$this->surname}
Salary: {$this->salary}
INFO;

# Create a new instance of the Employee class, Tom Smith, with a salary of 100:
$employee = (new Employee())
->setName('Tom')
->setSurname('Smith')
->setSalary('100');

# Display the value of the Employee instance:
echo $employee;

# Display:
# Name: Tom
# Surname: Smith
# Salary: 100

### Python

In Python, returning `self` in the instance method is one way to implement the fluent pattern.

It is however discouraged by the language’s creator, Guido van Rossum,[3] and therefore considered unpythonic (not idiomatic) for operations that do not return new values. Van Rossum provides string processing operations as example where he sees the fluent pattern appropriate.

class Poem:
def __init__(self, title: str) -> None:
self.title = title

def indent(self, spaces: int):
"""Indent the poem with the specified number of spaces."""
self.title = " " * spaces + self.title
return self

def suffix(self, author: str):
"""Suffix the poem with the author name."""
self.title = f"{self.title} - {author}"
return self

>>> Poem("Road Not Travelled").indent(4).suffix("Robert Frost").title
'    Road Not Travelled - Robert Frost'

### Swift

In Swift 3.0+ returning `self` in the functions is one way to implement the fluent pattern.

class Person {
var firstname: String = ""
var lastname: String = ""
var favoriteQuote: String = ""

@discardableResult
func set(firstname: String) -> Self {
self.firstname = firstname
return self

@discardableResult
func set(lastname: String) -> Self {
self.lastname = lastname
return self

@discardableResult
func set(favoriteQuote: String) -> Self {
self.favoriteQuote = favoriteQuote
return self

let person = Person()
.set(firstname: "John")
.set(lastname: "Doe")
.set(favoriteQuote: "I like turtles")

## Immutability

It's possible to create immutable fluent interfaces that utilise copy-on-write semantics. In this variation of the pattern, instead of modifying internal properties and returning a reference to the same object, the object is instead cloned, with properties changed on the cloned object, and that object returned.

The benefit of this approach is that the interface can be used to create configurations of objects that can fork off from a particular point; Allowing two or more objects to share a certain amount of state, and be used further without interfering with each other.

### JavaScript example

Using copy-on-write semantics, the JavaScript example from above becomes:

class Kitten {
constructor() {
this.name = 'Garfield';
this.color = 'orange';

setName(name) {
const copy = new Kitten();
copy.color = this.color;
copy.name = name;
return copy;

setColor(color) {
const copy = new Kitten();
copy.name = this.name;
copy.color = color;
return copy;

// ...

// use it
const kitten1 = new Kitten()
.setName('Salem');

const kitten2 = kitten1
.setColor('black');

console.log(kitten1, kitten2);
// -> Kitten({ name: 'Salem', color: 'orange' }), Kitten({ name: 'Salem', color: 'black' })

## Problems

### Errors cannot be captured at compile time

In typed languages, using a constructor requiring all parameters will fail at compilation time while the fluent approach will only be able to generate runtime errors, missing all the type-safety checks of modern compilers. It also contradicts the "fail-fast" approach for error protection.

### Debugging and error reporting

Single-line chained statements may be more difficult to debug as debuggers may not be able to set breakpoints within the chain. Stepping through a single-line statement in a debugger may also be less convenient.

java.nio.ByteBuffer.allocate(10).rewind().limit(100);

Another issue is that it may not be clear which of the method calls caused an exception, in particular if there are multiple calls to the same method. These issues can be overcome by breaking the statement into multiple lines which preserves readability while allowing the user to set breakpoints within the chain and to easily step through the code line by line:

java.nio.ByteBuffer
.allocate(10)
.rewind()
.limit(100);

However, some debuggers always show the first line in the exception backtrace, although the exception has been thrown on any line.

### Logging

Adding logging into the middle of a chain of fluent calls can be an issue. E.g., given:

ByteBuffer buffer = ByteBuffer.allocate(10).rewind().limit(100);

To log the state of `buffer` after the `rewind()` method call, it is necessary to break the fluent calls:

ByteBuffer buffer = ByteBuffer.allocate(10).rewind();
log.debug("First byte after rewind is " + buffer.get(0));
buffer.limit(100);

This can be worked around in languages that support extension methods by defining a new extension to wrap the desired logging functionality, for example in C# (using the same Java ByteBuffer example as above):

static class ByteBufferExtensions

public static ByteBuffer Log(this ByteBuffer buffer, Log log, Action<ByteBuffer> getMessage)

string message = getMessage(buffer);
log.debug(message);
return buffer;

// Usage:
ByteBuffer
.Allocate(10)
.Rewind()
.Log( log, b => "First byte after rewind is " + b.Get(0) )
.Limit(100);

### Subclasses

Subclasses in strongly typed languages (C++, Java, C#, etc.) often have to override all methods from their superclass that participate in a fluent interface in order to change their return type. For example:

class A {
public A doThis() {
// ...

class B extends A {
public B doThis() {
super.doThis();
return this;
} // Must change return type to B.

public B doThat() {
// ...

...
A a = new B().doThat().doThis(); // This would work even without overriding A.doThis().
B b = new B().doThis().doThat(); // This would fail if A.doThis() wasn't overridden.

Languages that are capable of expressing F-bound polymorphism can use it to avoid this difficulty. For example:

abstract class AbstractA<T extends AbstractA<T>> {
@SuppressWarnings("unchecked")
public T doThis() {
// ...
return (T)this;

class A extends AbstractA<A> {}

class B extends AbstractA<B> {
public B doThat() {
// ...
return this;

...
B b = new B().doThis().doThat(); // Works!
A a = new A().doThis();          // Also works.

Note that in order to be able to create instances of the parent class, we had to split it into two classes — `AbstractA` and `A`, the latter with no content (it would only contain constructors if those were needed). The approach can easily be extended if we want to have sub-subclasses (etc.) too:

abstract class AbstractB<T extends AbstractB<T>> extends AbstractA<T> {
@SuppressWarnings("unchecked")
public T doThat() {
// ...
return (T)this;

class B extends AbstractB<B> {}

abstract class AbstractC<T extends AbstractC<T>> extends AbstractB<T> {
@SuppressWarnings("unchecked")
public T foo() {
// ...
return (T)this;

class C extends AbstractC<C> {}
...
C c = new C().doThis().doThat().foo(); // Works!
B b = new B().doThis().doThat();       // Still works.

In a dependently typed language, e.g. Scala, methods can also be explicitly defined as always returning `this` and thus can be defined only once for subclasses to take advantage of the fluent interface:

class A {
def doThis(): this.type = { ... } // returns this, and always this.

class B extends A{
// No override needed!
def doThat(): this.type = { ... }

...
val a: A = new B().doThat().doThis(); // Chaining works in both directions.
val b: B = new B().doThis().doThat(); // And, both method chains result in a B!

## See also

* Command-query separation
* Method chaining
* Named parameter
* Pipeline (Unix)

## References

1. ↑ 1.0 1.1 1.2 Martin Fowler, "FluentInterface", 20 December 2005
2. ↑ "Interface Pack200.Packer". https://docs.oracle.com/javase/8/docs/api/java/util/jar/Pack200.Packer.html. Retrieved 13 November 2019.
3. ↑ Rossum, Guido van (October 17, 2003). "[Python-Dev sort() return value"]. https://mail.python.org/pipermail/python-dev/2003-October/038855.html.

## External links

* Martin Fowler's original bliki entry coining the term
* A Delphi example of writing XML with a fluent interface
* A .NET fluent validation library written in C#
* A tutorial for creating formal Java fluent APIs from a BNF notation
* Fluent Interfaces are Evil
* Developing a fluent api is so cool

* v
* t
* e

Software design patterns

Creational|

* Abstract factory
* Builder
* Dependency injection
* Factory method
* Lazy initialization
* Multiton
* Object pool
* Prototype
* RAII
* Singleton

Structural|

* Adapter
* Bridge
* Composite
* Decorator
* Delegation
* Facade
* Flyweight
* Front controller
* Marker interface
* Module
* Proxy
* Twin

Behavioral|

* Blackboard
* Chain of responsibility
* Command
* Interpreter
* Iterator
* Mediator
* Memento
* Null object
* Observer
* Servant
* Specification
* State
* Strategy
* Template method
* Visitor

Functional|

* Closure
* Currying
* Function composition
* Functor
* Monad
* Generator

Concurrency|

* Active object
* Actor
* Balking
* Barrier
* Binding properties
* Coroutine
* Compute kernel
* Double-checked locking
* Event-based asynchronous
* Fiber
* Futex
* Futures and promises
* Guarded suspension
* Immutable object
* Join
* Lock
* Messaging
* Monitor
* Nuclear
* Proactor
* Reactor
* Read write lock
* Scheduler
* Thread pool
* Thread-local storage

Architectural|

* ADR
* Active record
* Broker
* Client–server
* CBD
* DAO
* DTO
* DDD
* ECB
* ECS
* EDA
* Front controller
* Identity map
* Interceptor
* Implicit invocation
* Inversion of control
* Model 2
* MOM
* Microservices
* MVA
* MVC
* MVP
* MVVM
* Monolithic
* Multitier
* Naked objects
* ORB
* P2P
* Publish–subscribe
* PAC
* REST
* SOA
* Service locator
* SN
* SBA
* Specification

Cloud
Distributed|

* Ambassador
* Anti-Corruption Layer
* Bulkhead
* Cache-Aside
* Circuit Breaker
* CQRS
* Compensating Transaction
* Competing Consumers
* Compute Resource Consolidation
* Event Sourcing
* External Configuration Store
* Federated Identity
* Gatekeeper
* Index Table
* Leader Election
* MapReduce
* Materialized View
* Pipes
* Filters
* Priority Queue
* Publisher-Subscriber
* Queue-Based Load Leveling
* Retry
* Scheduler Agent Supervisor
* Sharding
* Sidecar
* Strangler
* Throttling
* Valet Key

Other|

* Business delegate
* Composite entity
* Intercepting filter
* Lazy loading
* Mangler
* Mock object
* Type tunnel
* Method chaining

Books|

* Design Patterns
* Enterprise Integration Patterns

People|

* Christopher Alexander
* Erich Gamma
* Ralph Johnson
* John Vlissides
* Grady Booch
* Kent Beck
* Ward Cunningham
* Martin Fowler
* Robert Martin
* Jim Coplien
* Douglas Schmidt
* Linda Rising

Communities|

* The Hillside Group
* The Portland Pattern Repository

0.00

(0 votes)

Original source: https://en.wikipedia.org/wiki/Fluent interface. Read more

|

Retrieved from "https://handwiki.org/wiki/index.php?title=Fluent_interface&oldid=3989138"
*[v]: View this template
*[t]: Discuss this template
*[e]: Edit this template