The Origin of the “Poutsma Principle”

One of the first things I probably need to explain is the name of this site: The Poutsma Principles. At first glance, it might sound like shameless self-promotion. And yes, maybe a little—but I can safely say I did not come up with the name myself.

A Meeting in Southampton

The name Poutsma Principle was born at a SpringSource engineering meeting in the summer of 2008, held in our Southampton office. These meetings took place once a quarter or so, and brought together the different teams working on Spring portfolio projects.

At that time, we were preparing the first release candidate of Spring Integration, which had been announced the year before. Mark Fisher—project lead of Spring Integration—was presenting the API to the rest of us.

I no longer recall all the details of his presentation, but I clearly remember two things that stood out.

Role Confusion

The API defined two main interfaces: MessageSource and MessageTarget. These defined the contracts for components that produce and consume messages, respectively. They were quite generic: many classes implemented one or both of these interfaces. Even a core class like MessageChannel implemented both.

On the surface, this made sense: if multiple components can receive messages, it is logical to share a common interface. However, conceptually this created an unfortunate side effect: it blurred the distinction between channels and endpoints. While both could technically receive messages, they serve very different roles in Enterprise Application Integration (EAI). Making them implement the same interface suggested they were interchangeable—contradicting the model Spring Integration was aiming for.

The Message Interface: Too Much, Too Mutable

The second issue I had was with the Message interface itself, which at the time looked like this:

public interface Message<T> {

    Object getId();

    MessageHeader getHeader();

    T getPayload();

    void setPayload(T payload);

    boolean isExpired();

    void copyHeader(MessageHeader header, boolean overwriteExistingValues);
}

To me, this interface was trying to do too much. The id and expiration felt like metadata better suited for the header. The copyHeader method belonged in a utility class. Most importantly, the presence of setPayload made the message mutable, and therefore not inherently thread-safe.

I Do Not Understand It—So It Must Be Wrong

When Mark finished presenting, I was confused, and said:

I do not understand it, and that probably means it is wrong.

That raised a big laugh—understandably so. In hindsight, it probably sounded more arrogant than intended. Let us chalk it up to Dutch directness.

What I meant was this:
At the time, I had been working with Spring for about four years. I had also studied Gregor Hohpe’s Enterprise Integration Patterns, and loved the clarity it brought to EAI concepts. So when I struggled to understand Spring Integration’s core API—despite being in its intended audience—I thought that might signal a deeper issue.

Revisiting the Design

Fortunately, Mark was open to feedback. A few weeks later, we sat down and worked through the issues together.

What emerged from that conversation was a clearer architectural model: channels and endpoints had distinct roles.

We also reworked the Message API. We made the Message interface immutable by removing setPayload, prioritizing thread safety. To maintain usability, we introduced MessageBuilder—a fluent API for creating or modifying messages safely. The id and expiration properties were moved into the headers.

The result was this much cleaner interface, which made it into Spring Integration 1.0, and eventually became foundational enough to move into the Spring Framework itself.

public interface Message<T> {

    MessageHeaders getHeaders();

    T getPayload();
}

Simple, focused, and easier to reason about.

Naming the Principle

At the next engineering meeting in Linz, Mark presented the revised design. One of his slides read:

Spring Integration now conforms to the Poutsma Principle.

The joke, of course, was that the design now passed the “Arjen understands it” test. That got another laugh—and the name stuck.

Beyond SpringSource

In 2010, the term made its way outside SpringSource. Iwein Fuld, a Spring Integration committer, asked to include it in the Xebia Essentials flash card series. I was honoured and happily agreed.

Wilfred Springer, who helped produce the cards, told me the principle reminded him of a quote from Bill Watterson, author of Calvin and Hobbes:

As far as I am concerned, if something is so complicated that you cannot explain it in 10 seconds, then it is probably not worth knowing anyway.

And that is how the Poutsma Principle was born.
What began as a bit of team banter ended up capturing a value I still try to follow: if your API needs too much explaining, it might need rethinking.