Package com.tccc.kos.commons.core.broker

package com.tccc.kos.commons.core.broker

Provides access to the message broker.

The kOS com.tccc.kos.commons.core.broker.MessageBroker is a system component that provides a simple and reliable way for software objects to send/receive messages over the kOS network.

Within java code it is typical to use listeners to receive callbacks from other components but listeners cannot be used between different sources on the network, such as events generated by code running in a browser or events generated by another java node in the network. In addition, applications within kOS are classloader isolated to avoid hard coupling of java classes between all components. Applications interact with each other using a micro-services interface that appears as endpoints and broker messages which also provides a uniform way to integrate applications even when running on different nodes in the kOS network.

Background

The message broker uses the publish–subscribe pattern. According to Wikipedia, "In software architecture, publish–subscribe is a messaging pattern where senders of messages (publishers), do not program the messages to be sent directly to specific receivers (subscribers), but instead categorize published messages into classes without knowledge of which subscribers, if any, there may be. Similarly, subscribers express interest in one or more classes and only receive messages that are of interest, without knowledge of which publishers, if any, there are."

Overview

The message broker provides for a one-to-many distribution of messages. It gives any number of publishers (producers) the ability to send messages to any number of subscribers (consumers). The following diagram illustrates this:

  +-------------+      +---------------+      +--------------+
  | Publisher 1 | ---> |               | ---> | Subscriber A |
  +-------------+      |               |      +--------------+
  | Publisher 2 | ---> | MessageBroker | ---> | Subscriber B |
  +-------------+      |               |      +--------------+
  | Publisher 3 | ---> |               | ---> + Subscriber C |
  +-------------+      +---------------+      +--------------+
 

Messages within kOS are based on topics. A topic is a filesystem path style string which indicates the type of message. Topics are typically hierarchical with different topics related to the same overall function having the same base. For example, consider multiple messages related to state changes of a door switch. One approach may be to use topics such as:

/door/open /door/close

A client (java in a different app, java in a different node, browser application, etc...) can subscribe to these topics to monitor the state of the door. In this particular example a client must subscribe to both topics to track the state. However, since topics are hierarchical, a client can simply subscribe to the base topic with a wildcard to receive both events with a single subscription. For example, a client can subscribe using:

/door/*

The choice of topic hierarchy is beyond the scope of this note, but careful consideration of topic structure can typically result in a very simple overall implementation.

While ever message contains a topic, a message may also contain a body. Message bodies are always sent as JSON. When sending messages from java, POJO's can be used as the body of the message and they will be serialized to JSON using either the standard JSON serializer or an optional JSON view class. This provides a great degree of control over the message body without having to resort to JSON.

When receiving a message in java, the message provides two bodies, one as a parsed JsonNode tree and the other as an optionally deserialized java object. When subscribing to a topic the subscription may specify a java class to use for deserialization. As with all micro-service patterns, this provides a simple decoupling of sender to receiver as the receiver only need to define a java POJO to capture the portion of the message body that is of interest and let JSON deserialization perform the mapping. When subscribing to a wildcard topic, the jsonBody property of the message can be used to perform deferred deserialization or can be used to directly extract data.

When subscribing to a topic a session object is required. The type of the session object doesn't matter as it is simply used as a key to track subscriptions for the purpose of avoiding duplication subscriptions and to provide a simple way to unsubscribe all subscriptions related to a session. For example, an application can use the application object as the session for all subscriptions and when the application unloads it can simply unsubscribe the application object to free all current subscriptions.

Messages sent to the broker will be forwarded to any matching subscriptions and then the message will be discarded. That is, the broker is not a message queue with persistence. A vast majority of messages are simply state change events which only have meaning at the time they were sent.

Since:

1.0

Version:

2022-10-21

Class	Description
DuplicateSubscriptionException	Exception thrown when a there's an attempt to create a subscription to a topic that already exists for the given session.
MessageBroker	System component that provides the ability to publish (send) and subscribe to (receive) messages over the kOS network.
MessageBrokerCallback	Interface that defines the callback method that gets called when a broker message matching a subscribed topic is fired (published).
MessageData	A MessageBroker message forwarded to a subscriber, typically via the MessageBrokerCallback interface.