Overview: How Apps Interact with PubSub+ Messaging Components

In this section we'll take you on a tour of the PubSub+ event broker's messaging components, and explain at a high level how they make data move from producers to the event broker, and from the event broker to consumers.

The PubSub+ event broker provides a foundation for multi-protocol and standards eventing including Solace Message Format (SMF), JMS1.1, MQTT3.11, REST, and AMQP1.0. As events move through the broker, they are translated from an ingress messaging protocol to an egress messaging protocol for each consumer receiving messages. Given the range of protocol support, it's important to keep in mind that each open source protocol your app might make use of adds its own twist on how the broker's messaging components operate. First we'll talk about how the Solace SMF protocol works, and then we'll discuss variations introduced by others.

On our tour, we'll look at how things operate from the perspective of your application. So, let's get started with SMF.

SMF

We're going to show you how the PubSub+ SMF protocol makes use of the PubSub+ event broker's messaging components to move data from producers to the broker, and from the broker to consumers, all from the point-of-view of your app. There are a couple of ways we're going to do this:

  • The SMF Process Flow section contains a diagram that illustrates the steps from establishing a connection through to getting data flowing. This diagram begins with your app and moves through the broker's components

  • The SMF Component Operations section has more details about the steps described in the process flow.

SMF Process Flow

In the diagram below, follow the steps from establishing a connection to the event broker through to starting the message flow.

The circled numbers in the diagram correspond to the numbered steps described in detail as follows:

Steps 1 - 5

These steps deal with the operations the application and event broker undergo to establish a connection and get ready for event messaging.

  1. Application initiates Solace API and Solace Context (Optional, can use default).
  2. Application Create and config session, Username, password, broker DNS:Port, TLS, Compression
    1. session = JCSMPFactory.onlyInstance().createSession(properties)
  3. Application connect session:
    1. session.connect();
    2. Host initiates TCP session
    3. Session sends CONNECT message
  4. Broker authenticates connection (happens automatically after step 3)
  5. Broker authorizes connection (happens automatically after step 4): an event broker sends CONNECT ACK

Steps 6, 7, 9 and 10

These steps focus on operations associated with sending and receiving event messages

  1. Application SDK creates publisher flow:
    1. prod = session.getMessageProducer(..)
    2. SDK sends last messageID sent and last messageID ACK received
    3. Broker sends last MessageID received and last messageID ACK sent
    4. Application maintains this state as message flow to allow for correct re-transmissions as required on reconnects.
  2. When a message is published:
    1. prod.send(msg,topic)
    2. Application sdk sends message and decrements available window by one
    3. Event broker receives, routes, and persists message
    4. Event broker sends ACK
    5. Application SDK receives ACK and increments available window by one.
  3. Application creates consumer flow, endpoint name, windowing sizes:
    1. cons = session.createFlow(listener, flow_prop)
    2. Application connect flow
    3. Application API handshakes flow and binds to Queue/Endpoint
    4. Messages are then able to move from broker to subscriber client.
  4. Application starts flow:
    1. cons.start()
    2. Broker sends message and decrements available window by one
    3. Client API receives message and passes to application
    4. Client SDK sends transport ACK
    5. Broker receives ACK and increments available window by one
    6. Application sends Application ACK when finished with message
    7. Broker receives Application ACK and deletes message from queue.

Step 8

This step deals with the establishment of application subscriptions.

  1. (Optional, can be admin or direct subn) Application Subscribes by adding subscription to queue:
    1. session.addSubscription(queue, topic,...)
    2. Application sends SUBSCRIBE message with topic and endpoint
    3. API sends message
    4. Broker adds subscription to connection or backing queue based on subscription endpoint
    5. Broker can send SUBACK.

Find out more about the PubSub+ components that are involved

  • Solace API: An overview of Solace API fundamentals.
  • Producer AD Flow: A client application can publish Guaranteed messages, that is, messages that the client application assigns a Persistent or Non‑Persistent delivery mode to Queue or Topic destinations.
  • Consumer AD Flow: To receive Guaranteed messages, a client must create a consumer Flow within a Session, and bind that flow to an endpoint on an event broker that messages are published or attracted to.
  • Client Profile: Client profiles are associated with client username accounts so that you can easily apply common configurations to groups of clients.
  • ACL Profile: After a client is successfully authenticated, the ACL profile assigned to the client username used by the client, or the LDAP the authorization groups that the client belongs to (when LDAP authorization is used), is checked.
  • Message VPNs: Message Virtual Private Networks (VPNs) are managed objects on PubSub+ event brokers that allow for the segregation of topic space and clients.
  • Route: Understand the fundamentals of publishing and subscribing to topics.
  • Client Username: A client is only authorized to connect to a Message VPN that is associated with a client username that that client has been assigned.
  • Queue: Basic operation of guaranteed messaging.

SMF Component Operations

In this section we're going to elaborate on the steps shown in the process flow diagram.

As we previously noted, Steps 1 - 5 deal with the operations the application and event broker go through to establish a connection and get ready for event messaging. The following sections provide more information on those steps:

Instantiating the Solace API and creating a Solace Session

Your client applications instantiate the Solace API. From here they can create Solace Contexts (which create a worker thread for event processing), and, subsequently, a Solace Session to connect to the broker. You have the flexibility to control the threading model by deciding how many sessions to add to a context. You can have multiple sessions per context, but only one context per session. If you need more threads to handle a single session, you'll need to pass event processing into an application worker thread pool. Also, a single session can only connect to a single broker instance at a time.

The Solace Session connection opens a TCP flow-controlled, bi-directional, connection from your application to the broker. This bi-directional session is the foundation of all communications for producers and consumers to send and receive messages for all Message Exchange Patterns (MEPs).

TCP Session properties

Fundamental properties of the TCP session are controlled via API session properties. This includes properties such as TCP (and possibly application) buffer sizes, and connection and reconnection behaviors. The session properties dictate the type of connection, be it plain-text, compressed , or encrypted. Finally, session properties can control application keep-alives from the client to the broker, which are used to detect connection failures.

TCP Connection

Now that we've discussed how an application connects, let's talk about the connection itself and its behavior.

As previously mentioned, every connection that sends or receives data is a stateful bi-directional TCP connection. On top of the TCP connection is a messaging layer session, which begins with a connect message, or a data message that contains credential headers that are used during authentication, which is discussed in Client Authentication. Based on destination port and connection header properties in the connection request, the broker will expect Session properties such as compression, encryption, and so on.

Broker authorizes connection

Once a session is connected to the required services and authenticated, we move on to the authorization stage. Based on the client-username in the connection credentials, two profiles are applied: the Client Profile and the ACL Profile.

  • The Client Profile sets the broker resources the client can access. This includes configuration options like the ability to send and receive persistent messages, the ability to create queues, and set how many system resource buffers the client’s connection can consume. For more information, refer to Configuring Client Profiles.
  • The ACL Profile defines which data events the client can produce and consume. For more information refer to Controlling Client Access with ACL Profiles.

Steps 6, 7, 9 and 10 focus on operations associated with sending and receiving event messages. You can find background information about those steps discussed below in Event processing Detail.

Event processing Detail

Now that we have an authenticated and authorized client connection, we're ready to send and receive messages.

For Direct event messaging this is quite simple, the client API contains a publish method to publish directly over the messaging session to send events and a subscribe directly to the messaging session connection to receive events. There are no messaging layer acknowledgments, timers, or re-transmissions, there are only TCP layer acknowledgments and retransmissions. If the TCP connection fails, and the messaging session is lost, then the events are also lost.

For Persistent event messaging things are a bit different in that there is messaging layer windowing, timers, acknowledgments, and retransmissions. This implies there's another layer of statefulness associated with persistent event publish and consumption. Each consumer state machine encapsulates an endpoint flow in the client API, and a Queue / Endpoint binding on the broker. These flows contain an endpoint, window, available window, last message sent, and last message acknowledged. This information allows the client to reconnect across sessions, and continue publish / consumption where the last session left off. If the Client-Profile allows for publishing persistent messages, there's at least one producer flow to allow publishing clients to send persistent message. If the Client-Profile allows for consuming persistent messages, there's a consumer flow per endpoint.

MQTT

Based on our understanding of SMF's operation, let's now look at how the MQTT service makes use of the PubSub+ event broker's messaging components to move data from an MQTT producer to the broker, and from the broker to MQTT consumers. First, we'll look at the Differences between MQTT and SMF, and then examine the MQTT Process Flow.

Differences between MQTT and SMF

  • VPN

    • There is no concept of a message VPN in MQTT, so for each unique message VPN created a new listen port needs to be assigned for each variant of MQTT traffic, MQTT/TCP, MQTT/WS, MQTT/TLS, MQTT/WSS.

  • QoS

    • For QoS0 and QoS1 application publication, the system behaves as it does for SMF direct and persistent messaging, where QoS0 is like direct and QoS1 is like persistent. Qos2 published messages are processed as QoS1 messages by the broker. For QoS1 subscriptions, a unique, dynamically created queue is created for each MQTT session, and subscriptions are added to that queue. This allows the queue to attract events, and the MQTT consumer can retrieve these events once they connect. Also, there's no handshake between the API and broker to learn the last message, nor is there an ACK received on re-connect, which can lead to additional re-transmissions.

MQTT Process Flow

In the diagram below, follow the steps from establishing a connection to the event broker through to starting the data flow.

The circled numbers in the diagram correspond to the numbered steps described in detail as follows:

Steps 1 - 4

These steps deal with the operations the application and event broker undergo to establish a connection and get ready for event messaging.

  1. Application initiates MQTT SDK:
    1. New MqttClient(host, clientName);
    2. Application Create and config session, broker DNS:Port, TLS, Compression
  2. Application connect session, Username, password:
    1. mqttClient.connect(connOpts);
    2. Host initiates TCP session
    3. c. Broker receives messaging layer connect.

  3. Broker authenticates connections

  4. Broker authorizes connection

Steps 5 and 7

These steps focus on operations associated with sending and receiving event messages

  1. When a message is published:

    1. mqttClient.publish(topic, message);
    2. Application sends PUBLISH message
    3. SDK store message in memory or to disk
    4. SDK sends message
    5. Broker receives message, routes and persists according to QoS
    6. Broker sends PUBACK
    7. SDK deletes message

  2. When Broker sends a message:

    1. Broker sends PUBLISH message and decrements available window
    2. Client SDK receives message and passes to application
    3. Application sends PUBACK when finished with message
    4. Broker receives PUBACK and deletes message from queue

Step 6

This step deals with the establishment of application subscriptions.

  1. When Applications subscribe:

    1. mqttClient.subscribe(topic, 1);
    2. Application sends SUBSCRIBE message
    3. SDK sends message
    4. Broker adds subscription to connection or backing queue based on subscription QoS
    5. Broker sends SUBACK

Find out more about the PubSub+ components that are involved

  • Client Profile: Client profiles are associated with client username accounts so that you can easily apply common configurations to groups of clients.
  • ACL Profile: After a client is successfully authenticated, the ACL profile assigned to the client username used by the client, or the LDAP the authorization groups that the client belongs to (when LDAP authorization is used), is checked.
  • Message VPNs: Message Virtual Private Networks (VPNs) are managed objects on PubSub+ event brokers that allow for the segregation of topic space and clients.
  • Route: Understand the fundamentals of publishing and subscribing to topics.
  • Client Username: A client is only authorized to connect to a Message VPN that is associated with a client username that that client has been assigned.
  • Queue: Basic operation of guaranteed messaging.
  • MQTT Client: Learn more about MQTT Client at the Eclipse Paho JAVA documentation.

Next Steps

For more information on how to use MQTT with PubSub+, refer to the MQTT pages in the Open APIs & Protocols section.

AMQP

The walk-through discussed in this section is a little different than that shown in previous ones. Those were based on Java. This one is based on Node.js. For AMQP Java, the JMS2.0 programing interface seems to be standard and would be the preferred option. First, we'll look at the Differences between Solace implementation of AMQP and SMF, and then examine the AMQP Process Flow.

Differences between Solace implementation of AMQP and SMF

  • Durability

    • Currently PubSub+'s AMQP solution processes only persistent messages.

  • VPN

    • There's no concept of a Message VPN in AMQP, so for each unique message VPN created, a new listen port needs to be assigned for AMQP/TCP and AMQP/TLS.

AMQP Process Flow

In the diagram below, follow the steps from establishing a connection to the event broker through to starting the data flow.

The circled numbers in the diagram correspond to the numbered steps described in detail as follows:

Steps 1 - 6

These steps deal with the operations the app and broker undergo to establish a connection and get ready for event messaging.

  1. Application creates an AMQ10 Client:

    a. new AMQP.Client(AMQP.Policy.merge({defaultSubjects : false}));

  2. Application connects the client:
    1. amqpClient.connect(pubsub+broker)
  3. Application Node initiates TCP session:
    1. Host initiates TCP session
    2. Connect opens incoming and outgoing channels for the client connection
  4. Broker authenticates connection, (Automatically from Step 3).
  5. Broker authorizes connection, (Automatic from 4):
    1. Broker sends CONNECT ACK
  6. Application creates Sender:
    1. amqpClient.createSender(queueName)
    2. SDK creates a senderSession

Steps 8 and 9

These steps focus on operations associated with sending and receiving event messages.

  1. Application create Receiver.
    1. amqpClient.createReceiver(queueName)
    2. SDK creates a receiverSession
  2. Application starts callback for messages and errors:
    1. amqpReceiver.on('message',...)
    2. data placed in AMQP frame assigned a transferId
    3. data sent then increment its next-outgoing-id, decrement its remote-incoming-window
    4. SDK will ACK frame with disposition frame

Step 7

This step deals with the establishment of application subscriptions.

  1. When a message is published:
    1. amqpSender.send(message)
    2. data placed in AMQP frame assigned a transferId
    3. data sent then increment its next-outgoing-id, decrement its remote-incoming-window
    4. Broker will ACK frame with disposition frame

Find out more about the PubSub+ components that are involved

  • Client Profile: Client profiles are associated with client username accounts so that you can easily apply common configurations to groups of clients.
  • ACL Profile: After a client is successfully authenticated, the ACL profile assigned to the client username used by the client, or the LDAP the authorization groups that the client belongs to (when LDAP authorization is used), is checked.
  • Message VPNs: Message Virtual Private Networks (VPNs) are managed objects on PubSub+ event brokers that allow for the segregation of topic space and clients.
  • Route: Understand the fundamentals of publishing and subscribing to topics.
  • Client Username: A client is only authorized to connect to a Message VPN that is associated with a client username that that client has been assigned.
  • Queue: Basic operation of guaranteed messaging.

Next Steps

For more information on how to use AMQP with PubSub+, refer to the AMQP pages in the Open APIs & Protocols section.

JMS

Now that we've had a look at SMF's operation, we're in a position to use that to understand the twist JMS has on the operation of the broker's components. First, we'll look at the Differences between JMS and SMF, and then examine the JMS Process Flow.

One other thing we'll point out is that the differences between JMS over SMF documented in this section are also the differences between JMS over AMQP.

Differences between JMS and SMF

You should note that the differences shown here, the differences between JMS over SMF, are also the differences between JMS over AMQP.

  • Persistent and Non-Persistent publisher flows

    • The JMS specification mandates synchronous and asynchronous data movement. All messages published as persistent are sent on a publisher flow with window of one and are synchronous; non-persistent messages can be sent within a configurable window on a second publisher flow.

  • JNDI

    • To use a broker as the JNDI server, the JMS API lazily opens a second session to do JNDI lookups. Although this session isn't used to send data, it could be required to resolve JNDI names of the endpoints, and so on to complete the data send and receive functions.

    Further Information on JNDI service can found in Solace JNDI Objects.

  • Topic Endpoints

    • Although SMF supports topic endpoints, its topic-to-queue mapping features are much more powerful and are the recommended approach. JMS doesn't have a programmatic interface for topic-to-queue mapping and therefore recommends topic endpoints.

    For more information, refer to Topic Endpoints.

JMS Process Flow

In the diagram below, follow the steps from establishing a connection to the event broker through to starting the data flow.

The circled numbers in the diagram correspond to the numbered steps described in detail as follows:

Steps 1 - 5

These steps deal with the operations the app and broker go through to establish a connection and get ready for event messaging.

  1. Application initiates JMS SDK which starts a single Solace Context.
    1. Application Creates initialContext , initialContext(env) with username, password, broker URL
  2. (Optional, can be programmatically created) Application does JNDI lookups to find context factory information, initialContext.lookup(CONNECTION_FACTORY_JNDI_NAME):
    1. This provides information such as messaging credentials and default message QoS, TLS, Compression
  3. Application connect connection to broker, connectionFactory.createConnection():
    1. Host initiates TCP session
    2. Broker receives messaging layer connect
  4. Broker authenticates connection
  5. Broker authorizes connection

Steps 6, 7, 8, 10, and 11

These steps focus on operations associated with sending and receiving event messages.

  1. Application does JNDI lookups to find endpoint names, initialContext.lookup(QUEUE_JNDI_NAME).
  2. Application SDK creates producer:
    1. session.createProducer(..);
    2. SDK sends last messageID sent and last messageID ACK received
    3. Broker sends last MessageID receives and last messageID ACK sent
    4. Application maintains this state as message flow to allow for correct re-transmissions as required on reconnects

  3. When producer publishes a message:

    1. producer.send(topic, message, DeliveryMode, Priority, TTL)
    2. Application sdk sends message and decrements available window by one
    3. Event broker receives, routes and persists message
    4. Event broker sends ACK
    5. Application SDK receives ACK and increments available window by one
  4. (Optional can poll for message) Application create listener:
    1. consumer.setMessageListener(..)

  5. Application starts connection, which starts all consumers:

    1. connection.start()
    2. Broker sends message and decrements available window by one
    3. Client SDK receives message and passes to application
    4. Client SDK sends transport ACK
    5. Broker receives ACK and increments available window by one
    6. Application sends Application ACK when finished with message
    7. Broker receives Application ACK and deletes message from queue.

Step 9

This step deals with the establishment of application subscriptions.

  1. (Optional for Topic Endpoints only) Application adds subscriptions:
    1. session.createConsumer(topic);
    2. Application sends SUBSCRIBE message with topic and endpoint
    3. SDK sends message
    4. Broker adds subscription to connection or topic endpoint
    5. Broker can send SUBACK

For AMQP, context and queue names are created programmatically, and an example how to create them is shown here.

Find out more about the PubSub+ components that are involved

  • Client Profile: Client profiles are associated with client username accounts so that you can easily apply common configurations to groups of clients.
  • ACL Profile: After a client is successfully authenticated, the ACL profile assigned to the client username used by the client, or the LDAP the authorization groups that the client belongs to (when LDAP authorization is used), is checked.
  • Message VPNs: Message Virtual Private Networks (VPNs) are managed objects on PubSub+ event brokers that allow for the segregation of topic space and clients.
  • Route: Understand the fundamentals of publishing and subscribing to topics.
  • Client Username: A client is only authorized to connect to a Message VPN that is associated with a client username that that client has been assigned.
  • Queue: Basic operation of guaranteed messaging.
  • Topic Endpoint: Creating durable topic subscribers.
  • Subscription: You can create message consumers to receive messages from a queue or for a specific topic.
  • Producer AD Flow: A client application can publish Guaranteed messages, that is, messages that the client application assigns a Persistent or Non‑Persistent delivery mode to Queue or Topic destinations.
  • JMS Context: A JMSContext is the main interface in the simplified JMS API introduced for JMS 2.0.
  • JMS Connection: A Connection object is a client's active connection to its JMS provider. It typically allocates provider resources outside the Java virtual machine (JVM).
  • JMS Session: A Session object is a single-threaded context for producing and consuming messages.

Next Steps

For more information on how to use JMS with PubSub+, refer to the JMS API pages in the Open APIs & Protocols section.

REST

In the previous sections, we looked at SMF's operation along with JMS and MQTT, all driven by messaging APIs. We'll now take a look at how REST's standards based HTTP exchange patterns work with the event broker's components. First, we'll look at the Differences between REST and SMF, and then examine the REST Process Flow.

Differences between REST and SMF

The REST messaging isn't driven by a messaging API, but instead by standards-based HTTP exchange patterns. However, at its core, the event broker treats REST messages exactly the same with respect to authentication, authorization, routing, and persistence. Here are the significant list of differences between the base SMF and REST:

  • Publish

    • All API publishes are HTTP POSTs with expected ACKs. The POSTs are not pipelined in that each must carry the required authentication header and are individually authenticated. This is different than a messaging-orientated protocol where the connection is authenticated with a connect messages containing authentication credentials and then the messages are pipelined on the connection.

  • Subscription

    • There is no subscription type method in HTTP. All subscriptions are done by administrative actions.

  • Event delivery to consuming applications

    • A REST delivery endpoint is used to manage the connection from the broker to the application and deliver events via standard web-hooks HTTP.

REST Process Flow

In the diagram below, follow the steps from establishing a connection to the event broker through to starting the data flow.

The circled numbers in the diagram correspond to the numbered steps described in detail as follows:

Steps 1 - 6

These steps deal with the operations the app and broker undergo to establish a connection and get ready for event messaging.

  1. Application Creates REST message:

    1. Add Authentication Header
    2. Add Content-Type Header
    3. Add Solace-Reply-Wait-Time-In-ms if reply is required
    4. Add Message Body

  2. Application Sends REST Message:

    1. URI includes Solace broker URI with destination topic or queue

  3. Broker authenticates (Automatic from 2.):

    1. URI includes Solace broker URI with destination topic or queue

  4. Broker authorizes (Automatic from 2.)

  5. Broker routes (Automatic from 2.):

    1. Based on URI

  6. Broker persists:

    1. Broker ACKS (200 OK) either empty payload or reply body

Steps 8 and 9

These steps focus on operations associated with sending and receiving event messages.

  1. Broker opens connection(s) to application via web-hooks:

    1. Broker opens connection to application. b. Broker send message with HTTP POST

  2. Application API ACK message:

    1. Broker deletes message

Step 7

This step deals with the establishment of application subscriptions.

  1. Application Subscribes:
    1. This is not done programmatically. Administrators bind RDP to Queue containing subscriptions

Find out more about the PubSub+ components that are involved

  • Client Profile: Client profiles are associated with client username accounts so that you can easily apply common configurations to groups of clients.
  • ACL Profile: After a client is successfully authenticated, the ACL profile assigned to the client username used by the client, or the LDAP the authorization groups that the client belongs to (when LDAP authorization is used), is checked.
  • Message VPNs: Message Virtual Private Networks (VPNs) are managed objects on PubSub+ event brokers that allow for the segregation of topic space and clients.
  • Route: Understand the fundamentals of publishing and subscribing to topics.
  • Client Username: A client is only authorized to connect to a Message VPN that is associated with a client username that that client has been assigned.
  • Queue: Basic operation of guaranteed messaging.

Next Steps

For more information on how to use REST with PubSub+, refer to the REST pages in the Open APIs & Protocols section.