Fluent Interface

Fluent Interfaces ( German often translated as: "liquid interfaces," aptly as: "speaking Interface " ) is a concept for programming interfaces in software development, in which you can almost obeying program in the form of natural language sentences. The program code is then written legibly and facilitates understanding of the program.

Interfaces are often used incorrectly. Fluent interfaces can stop to their proper use by a grammar is chosen for them, which is violated by recognizable types of misuse. There are two ways to realize such " speaking Interface " by Method chaining ( methods chains) or by means of Nested Functions ( Embedded functions).


As the founder of the concept Fluent Interfaces Eric Evans and Martin Fowler apply. In the example implementation of the design pattern specification, they invented the concept to create new objects using methods chains on speaking manner.

Specification ColorSpec = new ColorSpecification ();   Specification lengthSpec = new LengthSpecification ();   if ( colorSpec.and ( lengthSpec ). isSatisfiedBy (obj )) {       ...   } In the above example is quite explicitly in the condition of the if statement, that the object obj is tested for both conditions. Another example is the speaking constructing a date.

DateFactory.newDate () year ( 2009) month ( 2) day (7).. .; Unlike the use of a constructor in which the importance of the three numerical values ​​would be hidden given by its position in the call, you can see here by the above method name explicitly, the importance to have the individual values ​​. Also, the developer of such an interface may also restrict the order in which the methods may be invoked. This means that around method calls that expect more parameters can be written more understandable.

Especially in Evans ' Domain - Driven Design Fluent interfaces play an important role, since they serve him to explicitly express specific properties of a domain in the program code. Fluent interfaces are thus one of the so-called internal domain -specific languages ​​, also known as embedded language. There are domain -specific languages ​​that are implemented in the syntax of a programming language.


Naive without grammar

The example implementation of Evans and Fowler for Specifications was kept very simple. To allow methods with chain and as above, the Interface Specification has been added only the new method and ().

Public interface Specification {         Specification and ( Specification spec);         boolean isSatisfiedBy (Object obj);     } When calling and () thus supplies each Specification another, which in turn may be derived from a call to the method and (). However, the implementation of types is enriched with functionalities by this naive approach, the remote are their actual purpose. The main disadvantage is, however, that methods may be concatenated across any order.

With grammar

Frequently, the order in which the methods of a chain methods may be strung together, a major role. The following example shows the use of Fluent interface that adds an object of type Date couple of days and hours.

Date date = CalendarUtils         . add ( 5). days ()         . add ( 10). hours ()         . tons ( date); If, as in the naive approach that return with each invocation of a method is always the same type, then the " set " will be terminated or wrong by not mandatory " set members " or some will be chained together. Thus, the exclusionary such grammar is enforced, so each call to a method must return a different type, namely the holds only now allowed follow-up methods. In the following example you can see how the method call newDate () of DateUtils leads to the return of a mediator. This then holds the follow-up method to add. The call to the add method in turn also leads to the return of a new mediator etc.

Public class DateUtils {      public static mediator newDate () {          ...      }   }     public class Mediator {       public Mediator2 add ( int i ) {           ...       }   }     public class Mediator2 {       public Mediator3 days () {           ...       }   }   ... / / Possible sentence DateUtils.newDate (). Add ( 5). Days (). ... Bernd Schiffer calls these mediators as descriptors. With the above example, a grammar is realized, which sets exactly the order in which the methods can be called. In addition, the methods chain as long as no desired object of type Date exports, as it is not yet complete. Therefore, error show when using a so- implemented class DateUtils already during the compilation of the using program and not at runtime.


The advantages are the ease of development -use programs and improved readability of this written program code.

  • Fluent interfaces can come very close to a natural language sentence. So you have to comment on just a little further.
  • With a record like fluent interface and thus insinuierten allowable sentence construction, the user gets a clearer idea about the offered functionalities and their potential use.
  • A development environment with auto-complete such as Eclipse shows which methods can be called next.


The disadvantages are the cost of the fluid interface itself and the difficult development of -use programs.

  • The realization of a grammar for fluent interface is very complex and the necessary network of mediators will quickly become confusing. In addition, is difficult to understand their level, which sentence structures are possible. By modeling by Fluent interfaces in the form of charts is an attempt to avoid this drawback. It is automatically generated from a model to the necessary mediator code, so it is only necessary to implement the behavior of the Fluent interface itself.
  • A long chain of method calls on the same line makes them difficult to debug because a call stack typically contains only the line of the error, but not the column in the source file. The same applies to the assignment of alerts from the static code analysis.


Fluent interfaces are used for different purposes. The focus is always to make explicit what is anchored in a domain.

  • Packaging of functionality As shown above, Fluent interfaces can offer existing functionality easier to understand.
  • Liquid builder Transfer the concept fluent interface to the design pattern Builder.
  • Figure strange syntax With the help of Fluent interfaces can occur in the program code strings as for interpreted languages ​​such as SQL, XPath or HQL replace conceptually easier by Views comprehensible.


Some programming languages ​​support benamte parameters, such as Smalltalk or ABAP. In these, the concept of fluent interface does not make sense because the methods interface must be talking already by the properties of the language used.

As Smalltalk:

Object param1: param2 foo: bar Example ABAP:

Lo_object -> myMethod (                 iv_param1 = foo                 iv_param2 = bar    ). Web Links

  • Template: Internet resource / Maintenance / date not in ISO format Martin Fowler: FluentInterface. December 20, 2005, accessed on 6 March 2012 ( English).
  • PHP: Chained methods / fluent interface. Retrieved on 6 March 2012.
  • Khalid Abuhakmeh: Creating a C # Fluent API. Tech.Pro, April 9, 2013, accessed on 14 April 2013 ( english, explanation of Fluent interfaces in C # for beginners).
  • Heiner Kücker: Java - fluent interface code generator based on a grammar. January 31, 2014, accessed on 31 January 2014 ( Simple Java program, which based on a grammar generates the necessary code frame for a fluent interface ).