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

Interface MessageBroker

All Known Implementing Classes:
AppMessageBroker
public interface MessageBroker
System component that provides the ability to publish (send) and subscribe to (receive) messages over the kOS network. The message broker is available in the kOS context and can be accessed using Autowired annotation.

See the package page for a more complete discussion of the kOS message broker system.

Examples

How to instantiate

 
  public class MyClass {
      // Use the kOS autowired annotation to instantiate the system message broker:
      @Autowired
      private MessageBroker messageBroker;
  }

Subscribe / Unsubscribe

 
      // Subscribe to "myTopic1" in the "mySession1" group:
      messageBroker.subscribe("mySession1", "myTopic1", this);

      // Unsubscribe from the "myTopic2" in the "mySession2" group:
      messageBroker.unsubscribe("mySession2", "myTopic2");

      // Unsubscribe from all topics in the "mySession3" group:
      messageBroker.unsubscribe("mySession3");

Send

 
      // Send a message indicating that a "myTopic1" event occurred:
      messageBroker.send("myTopic1");

      // Send a message for "myTopic2" with some sort of data (any object):
      messageBroker.send("myTopic2", someData);

      // Send a message for "myTopic3" in "mySession" with some sort of data (any object).
      // This message is sent to all sessions EXCEPT "mySession":
      messageBroker.send("mySession", "myTopic3", someData, null);

Hierarchical topics (AKA topic paths)

It is possible to create hierarchical topics using the forward-slash character. Along with the wildcard character (*), this makes it easy to subscribe to multiple related topics. The following example demonstrates this: 
 
      // Subscribe to all topics that begin with "/user/":
      messageBroker.subscribe("mySession", "/user/*", this);
In the above example, that object now receives the following messages: 
 
      messageBroker.send("/user/login");
      messageBroker.send("/user/logout");
      messageBroker.send("/user/whatever");
Since:
1.0
Version:
2022-08-31
See Also:

  • Method Details

    • subscribe

      void subscribe(Object session, String topic, MessageBrokerCallback callback)
      Subscribes to the specified topic. If the message has a body, then it will be accessible via jsonBody in the message data.
      Parameters:
      session - the session key
      topic - the topic to subscribe to
      callback - the callback to use

    • subscribe

      void subscribe(Object session, String topic, Class<?> bodyClass, MessageBrokerCallback callback)
      Subscribes to the specified topic. If a message has a body, it will be serialized to JSON. The callback has access to the JSON representation of the data in jsonBody. If a class is specified, the JSON will be deserialized at the specified class and placed in the body property of the message data.
      Parameters:
      session - the session key
      topic - the topic to subscribe to
      bodyClass - the class to serialize the body to (optional)
      callback - the callback to use

    • unsubscribe

      void unsubscribe(Object session, String topic)
      Unsubscribes from the specified topic. The unsubscribed topic must match the topic used to subscribe.
      Parameters:
      session - the session key (optional: no-op if null)
      topic - the topic to unsubscribe form

    • unsubscribe

      void unsubscribe(Object session)
      Unsubscribes from all topics in the specified session.
      Parameters:
      session - the session key (optional: no-op if null)

    • send

      void send(String topic)
      Sends a broker message to the given topic.
      Parameters:
      topic - the topic to send

    • send

      void send(String topic, Object body)
      Sends a broker message to the given topic with the given data.
      Parameters:
      topic - the topic to send
      body - the message body (optional)

    • send

      void send(String topic, Object body, Class<?> jsonView)
      Sends a broker message to the given topic with the given data.
      Parameters:
      topic - the topic to send
      body - the message body (optional)

    • send

      void send(Object session, String topic, Object body, Class<?> jsonView)
      Sends a broker message from the specified session. This session will not receive the message.
      Parameters:
      session - the sending key (optional)
      topic - the topic to send
      body - the message body (optional)
      jsonView - the view to use when converting to JSON (optional)

    • sendJson

      void sendJson(Object session, String topic, JsonNode jsonBody)
      Sends a broker message from the specified session where the body is already in parsed JSON form. This session will NOT receive the message.
      Parameters:
      session - the sending session key (optional)
      topic - the topic to send
      jsonBody - the message body in parsed JSON (optional)