JarCastingSwitchboard: 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
