Fluent interfaces are sometimes confused with the Builder pattern, because they share method chaining and a fluent usage. However, fluent interfaces are not primarily used to create shared (mutable) objects, but to configure complex objects without having to respecify the target object on every property change.

<?xml version="1.0" encoding="UTF-8"?>

<class-diagram version="1.1.8" icons="true" automaticImage="PNG" always-add-relationships="false" generalizations="true"

realizations="true" associations="true" dependencies="false" nesting-relationships="true">

<class id="1" language="java" name="com.iluwatar.fluentinterface.App" project="fluentinterface"

file="/fluentinterface/src/main/java/com/iluwatar/fluentinterface/App.java" binary="false" corner="BOTTOM_RIGHT">

<position height="-1" width="-1" x="289" y="-8"/>

<display autosize="true" stereotype="true" package="true" initial-value="false" signature="true"

sort-features="false" accessors="true" visibility="true">

<attributes public="true" package="true" protected="true" private="true" static="true"/>

<operations public="true" package="true" protected="true" private="true" static="true"/>

</display>

</class>

<class id="2" language="java" name="com.iluwatar.fluentinterface.fluentiterable.simple.SimpleFluentIterable"

project="fluentinterface"

file="/fluentinterface/src/main/java/com/iluwatar/fluentinterface/fluentiterable/simple/SimpleFluentIterable.java"

binary="false" corner="BOTTOM_RIGHT">

<position height="-1" width="-1" x="450" y="430"/>

<display autosize="true" stereotype="true" package="true" initial-value="false" signature="true"

sort-features="false" accessors="true" visibility="true">

<attributes public="true" package="true" protected="true" private="true" static="true"/>

<operations public="true" package="true" protected="true" private="true" static="true"/>

</display>

</class>

<class id="3" language="java" name="com.iluwatar.fluentinterface.fluentiterable.lazy.LazyFluentIterable"

project="fluentinterface"

file="/fluentinterface/src/main/java/com/iluwatar/fluentinterface/fluentiterable/lazy/LazyFluentIterable.java"

binary="false" corner="BOTTOM_RIGHT">

<position height="-1" width="-1" x="860" y="391"/>

<display autosize="true" stereotype="true" package="true" initial-value="false" signature="true"

sort-features="false" accessors="true" visibility="true">

<attributes public="true" package="true" protected="true" private="true" static="true"/>

<operations public="true" package="true" protected="true" private="true" static="true"/>

</display>

</class>

<interface id="4" language="java" name="com.iluwatar.fluentinterface.fluentiterable.FluentIterable"

project="fluentinterface"

file="/fluentinterface/src/main/java/com/iluwatar/fluentinterface/fluentiterable/FluentIterable.java" binary="false"

corner="BOTTOM_RIGHT">

<position height="-1" width="-1" x="794" y="55"/>

<display autosize="true" stereotype="true" package="true" initial-value="false" signature="true"

sort-features="false" accessors="true" visibility="true">

<attributes public="true" package="true" protected="true" private="true" static="true"/>

<operations public="true" package="true" protected="true" private="true" static="true"/>

</display>

</interface>

<class id="5" language="java" name="com.iluwatar.fluentinterface.fluentiterable.lazy.DecoratingIterator"

project="fluentinterface"

file="/fluentinterface/src/main/java/com/iluwatar/fluentinterface/fluentiterable/lazy/DecoratingIterator.java"

binary="false" corner="BOTTOM_RIGHT">

<position height="-1" width="-1" x="1245" y="391"/>

<display autosize="true" stereotype="true" package="true" initial-value="false" signature="true"

sort-features="false" accessors="true" visibility="true">

<attributes public="true" package="true" protected="true" private="true" static="true"/>

<operations public="true" package="true" protected="true" private="true" static="true"/>

</display>

</class>

<interface id="6" language="java" name="java.lang.Iterable" project="fluentinterface"

file="C:/Program Files/Java/jdk1.8.0/jre/lib/rt.jar" binary="true" corner="BOTTOM_RIGHT">

<position height="-1" width="-1" x="793" y="-163"/>

<display autosize="true" stereotype="true" package="true" initial-value="false" signature="true"

sort-features="false" accessors="true" visibility="true">

<attributes public="true" package="true" protected="true" private="true" static="true"/>

<operations public="true" package="true" protected="true" private="true" static="true"/>

</display>

</interface>

<dependency id="7">

<end type="SOURCE" refId="1"/>

<end type="TARGET" refId="3"/>

</dependency>

<dependency id="8">

<end type="SOURCE" refId="1"/>

<end type="TARGET" refId="2"/>

</dependency>

<generalization id="9">

<end type="SOURCE" refId="4"/>

<end type="TARGET" refId="6"/>

</generalization>

<realization id="10">

<end type="SOURCE" refId="3"/>

<end type="TARGET" refId="4"/>

</realization>

<dependency id="11">

<end type="SOURCE" refId="1"/>

<end type="TARGET" refId="4"/>

</dependency>

<realization id="12">

<end type="SOURCE" refId="2"/>

<end type="TARGET" refId="4"/>

</realization>

<dependency id="13">

<end type="SOURCE" refId="3"/>

<end type="TARGET" refId="5"/>

</dependency>

<classifier-display autosize="true" stereotype="true" package="true" initial-value="false" signature="true"

sort-features="false" accessors="true" visibility="true">

<attributes public="true" package="true" protected="true" private="true" static="true"/>

<operations public="true" package="true" protected="true" private="true" static="true"/>

</classifier-display>

<association-display labels="true" multiplicity="true"/>

</class-diagram>

layout: pattern

title: Fluent Interface

folder: fluentinterface

permalink: /patterns/fluentinterface/

categories: Architectural

tags: Java

**Intent:** A fluent interface provides an easy-readable, flowing interface, that often mimics a domain specific language. Using this pattern results in code that can be read nearly as human language.


**Applicability:** Use the Fluent Interface pattern when

* you provide an API that would benefit from a DSL-like usage

* you have objects that are difficult to configure or use

**Real world examples:**

* [Java 8 Stream API](http://www.oracle.com/technetwork/articles/java/ma14-java-se-8-streams-2177646.html)

* [Google Guava FluentInterable](https://github.com/google/guava/wiki/FunctionalExplained)

* [JOOQ](http://www.jooq.org/doc/3.0/manual/getting-started/use-cases/jooq-as-a-standalone-sql-builder/)

**Credits**

* [Fluent Interface - Martin Fowler](http://www.martinfowler.com/bliki/FluentInterface.html)

* [Evolutionary architecture and emergent design: Fluent interfaces - Neal Ford](http://www.ibm.com/developerworks/library/j-eaed14/)

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

<parent>

<artifactId>java-design-patterns</artifactId>

<groupId>com.iluwatar</groupId>

<version>1.6.0</version>

</parent>

<modelVersion>4.0.0</modelVersion>

<artifactId>fluentinterface</artifactId>

<dependencies>

<dependency>

<groupId>junit</groupId>

<artifactId>junit</artifactId>

<scope>test</scope>

</dependency>

</dependencies>

</project>

package com.iluwatar.fluentinterface;

import com.iluwatar.fluentinterface.fluentiterable.FluentIterable;

import com.iluwatar.fluentinterface.fluentiterable.lazy.LazyFluentIterable;

import com.iluwatar.fluentinterface.fluentiterable.simple.SimpleFluentIterable;

import java.util.*;

import java.util.function.Function;

import java.util.function.Predicate;

import static java.lang.String.valueOf;

public class App {

public static void main(String[] args) {

List<Integer> integerList = new ArrayList<Integer>() {

{

add(1);

add(-61);

add(14);

add(-22);

add(18);

add(-87);

add(6);

add(64);

add(-82);

add(26);

add(-98);

add(97);

add(45);

add(23);

add(2);

add(-68);

add(45);

}

};

prettyPrint("The initial list contains: ", integerList);

List<Integer> firstFiveNegatives =

SimpleFluentIterable.fromCopyOf(integerList).filter(negatives()).first(3).asList();

prettyPrint("The first three negative values are: ", firstFiveNegatives);

List<Integer> lastTwoPositives =

SimpleFluentIterable.fromCopyOf(integerList).filter(positives()).last(2).asList();

prettyPrint("The last two positive values are: ", lastTwoPositives);

SimpleFluentIterable

.fromCopyOf(integerList)

.filter(number -> number % 2 == 0)

.first()

.ifPresent(

evenNumber -> System.out.println(String.format("The first even number is: %d",

evenNumber)));

List<String> transformedList =

SimpleFluentIterable.fromCopyOf(integerList).filter(negatives()).map(transformToString())

.asList();

prettyPrint("A string-mapped list of negative numbers contains: ", transformedList);

List<String> lastTwoOfFirstFourStringMapped =

LazyFluentIterable.from(integerList).filter(positives()).first(4).last(2)

.map(number -> "String[" + String.valueOf(number) + "]").asList();

prettyPrint(

"The lazy list contains the last two of the first four positive numbers mapped to Strings: ",

lastTwoOfFirstFourStringMapped);

LazyFluentIterable

.from(integerList)

.filter(negatives())

.first(2)

.last()

.ifPresent(

lastOfFirstTwo -> System.out.println(String.format(

"The last of the first two negatives is: %d", lastOfFirstTwo)));

}

private static Function<Integer, String> transformToString() {

return integer -> "String[" + valueOf(integer) + "]";

}

private static Predicate<? super Integer> negatives() {

return integer -> (integer < 0);

}

private static Predicate<? super Integer> positives() {

return integer -> (integer > 0);

}

private static <TYPE> void prettyPrint(String prefix, Iterable<TYPE> iterable) {

prettyPrint(", ", prefix, ".", iterable);

}

private static <TYPE> void prettyPrint(String prefix, String suffix, Iterable<TYPE> iterable) {

prettyPrint(", ", prefix, suffix, iterable);

}

private static <TYPE> void prettyPrint(String delimiter, String prefix, String suffix,

Iterable<TYPE> iterable) {

StringJoiner joiner = new StringJoiner(delimiter, prefix, ".");

Iterator<TYPE> iterator = iterable.iterator();

while (iterator.hasNext()) {

joiner.add(iterator.next().toString());

}

System.out.println(joiner);

}

}

package com.iluwatar.fluentinterface.fluentiterable;

import java.util.ArrayList;

import java.util.Iterator;

import java.util.List;

import java.util.Optional;

import java.util.function.Function;

import java.util.function.Predicate;

public interface FluentIterable<TYPE> extends Iterable<TYPE> {

/**

FluentIterable<TYPE> filter(Predicate<? super TYPE> predicate);

/**

Optional<TYPE> first();

/**

FluentIterable<TYPE> first(int count);

/**

Optional<TYPE> last();

/**

FluentIterable<TYPE> last(int count);

/**

<NEW_TYPE> FluentIterable<NEW_TYPE> map(Function<? super TYPE, NEW_TYPE> function);

/**

List<TYPE> asList();

/**

static <TYPE> List<TYPE> copyToList(Iterable<TYPE> iterable) {

ArrayList<TYPE> copy = new ArrayList<>();

Iterator<TYPE> iterator = iterable.iterator();

while (iterator.hasNext()) {

copy.add(iterator.next());

}

return copy;

}

}