https://github.com/whiskeysierra/switchboard
https://github.com/whiskeysierra/switchboard
in-memory java message-routing testing
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/whiskeysierra/switchboard
- Owner: whiskeysierra
- License: mit
- Created: 2017-07-21T12:02:32.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2023-06-14T22:44:02.000Z (almost 2 years ago)
- Last Synced: 2025-02-10T00:19:09.682Z (3 months ago)
- Topics: in-memory, java, message-routing, testing
- Language: Java
- Size: 985 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Switchboard: In-Process Message Router
[](https://www.flickr.com/photos/justininsd/7888302222/)
[](https://masterminds.github.io/stability/active.html)
[](https://coveralls.io/r/whiskeysierra/switchboard)
[](https://www.codacy.com/app/whiskeysierra/switchboard)
[](http://www.javadoc.io/doc/io.github.whiskeysierra/switchboard)
[](https://github.com/whiskeysierra/switchboard/releases)
[](https://maven-badges.herokuapp.com/maven-central/io.github.whiskeysierra/switchboard)
[](https://raw.githubusercontent.com/whiskeysierra/switchboard/main/LICENSE)
> **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
```java
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:
```java
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:
```xml
io.github.whiskeysierra
switchboard
${switchboard.version}
test
```
## Usage
Any communication via *Switchboard* consists of two parts: [Receiving](#receiving-messages) and [sending messages](#sending-messages).
### Receiving messages
You receive messages by [subscribing](#subscriptions) to it. Subscriptions can be done either in a [blocking](#blocking) or [non-blocking](#non-blocking)
fashion. Additionally one specifies a [*subscription mode*](#subscription-modes) 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:
```java
Key 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:
```java
Future 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*](#message):
```java
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.
```java
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](../../issues).
## 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](.github/CONTRIBUTING.md).
## Alternatives
- [Awaitility](https://github.com/awaitility/awaitility) is a small Java DSL for synchronizing asynchronous operations
- [Guava's EventBus](https://github.com/google/guava/wiki/EventBusExplained)
See [example implementation](src/test/java/switchboard/eventbus) with *at-least-once* semantics
## Credits and references
[Meals at all Hours](https://www.flickr.com/photos/justininsd/7888302222/) by
[Justin Brown](https://www.flickr.com/photos/justininsd/) is licensed under
[Attribution-NonCommercial-ShareAlike 2.0 Generic](https://creativecommons.org/licenses/by-nc-sa/2.0/).