Switchboard: In-Process Message Router

Switchboard noun, /swɪtʃ bɔːɹd/: The electronic panel that is used to direct telephone calls to the desired recipient.

An in-process message router that helps block on asynchronous events.

• Technology stack: Java 11+
• Status: Beta, ported from an internal implementation that is used in production

Example

server.save("bob");
User user = switchboard.subscribe(userCreated("bob"), atLeastOnce(), ofSeconds(10)).get();

Features

• makes asynchronous interactions more easily
• simple, extensible API

Origin

In any non-trivial application you'll most probably seen a process like this.

Since the call to the database is synchronous we can be sure it happened before the client got the response. Testing this case is therefore relatively straightforward:

Response response = server.save(bob);
assertThat(database.getUser("bob"), is(not(nullValue())));

It all gets more difficult when you start to do time-consuming tasks in an asynchronous fashion:

The test case from above may no longer work, since we may get the response back from the server before the database finished its part.

The idea of Switchboard is to encapsulate the necessary event-based communication behind a small API that allows to write synchronous-style assertions for asynchronous messages.

The term switchboard refers to old-style telephone switchboards, i.e. big communication devices handled by a switchboard operator that allow to connect multiple parties via telephone lines, usually one caller and one receiver.

In our case those parties are threads and they talk to each other by passing messages.

Dependencies

• Java 11 or higher

Installation

Add the following dependency to your project:

<dependency>
    <groupId>io.github.whiskeysierra</groupId>
    <artifactId>switchboard</artifactId>
    <version>${switchboard.version}</version>
    <scope>test</scope>
</dependency>

Usage

Any communication via Switchboard consists of two parts: Receiving and sending messages.

Receiving messages

You receive messages by subscribing to it. Subscriptions can be done either in a blocking or non-blocking fashion. Additionally one specifies a subscription mode to indicate how much messages are going to be consumed.

Think of blocking subscriptions as actively sitting in front of the phone and waiting while non-blocking could be seen as having call forwarding from your home to your cell so you can do something else, while waiting for a call.

Subscriptions

A subscription is basically a key that specifies your requirements:

Key<UserCreated, String> userCreated(String name) {
    return Key.of(UserCreated.class, name);
}

Receiving messages in a non-blocking way is usually required if you need to subscribe to multiple different messages:

Future<User> future = switchboard.subscribe(userCreated("bob"), atLeastOnce(), ofSeconds(10));

future.get(); // wait 10 seconds
future.get(5, SECONDS); // wait at most 5 seconds

Subscription Modes

When subscribing to message you can specify one of the following modes. They have different characteristics in terms of termination and success conditions:

Mode	Termination	Success
atLeast(n)	m >= n	m >= n
atLeastOnce()	m >= 1	m >= 1
atMost(n)	m > n	m <= n
atMostOnce()	m > 1	m <= 1
exactlyOnce()	m > 1	m == 1
never()	m > 0	m == 0
times(n)	m > n	m == n

Note: Be ware that only atLeast(n) and atLeastOnce() have conditions that allow early termination for success cases before the timeout is reached. All others will wait for the timeout to ensure its success condition holds true.

Sending messages

You send messages by placing a Deliverable on the switchboard, e.g. a message:

var key = Key.of(UserCreated.class, user.id);
switchboard.publish(message(key, user));

Switchboard has an answering machine builtin. That means any message that arrives without anyone receiving it right away will be recorded and delivered as soon as at least one receiver starts listening. This is especially useful if your tests need to listen to multiple messages and their order is not guaranteed.

switchboard.publish(message);

String string = switchboard.subscribe(key, atLeastOnce(), ofSeconds(10));

The subscriber will get the message immediately upon subscription.

Getting Help

If you have questions, concerns, bug reports, etc., please file an issue in this repository's Issue Tracker.

Getting Involved/Contributing

To contribute, simply make a pull request and add a brief description (1-2 sentences) of your addition or change. For more details, check the contribution guidelines.

Alternatives

• Awaitility is a small Java DSL for synchronizing asynchronous operations
• Guava's EventBus
  See example implementation with at-least-once semantics

Credits and references

Meals at all Hours by Justin Brown is licensed under Attribution-NonCommercial-ShareAlike 2.0 Generic.