Receiving Guaranteed Messages in the PubSub+ JCSMP API

To receive published Guaranteed messages (that is, messages that have a delivery mode of persistent or non‑persistent), a client must create a consumer flow to bind to a queue endpoint or a topic endpoint provisioned on the event broker. Once the client is bound to the endpoint, it can receive published Guaranteed messages that are delivered and spooled to that endpoint.

When a consuming client successfully receives a Guaranteed message over a flow, a corresponding application acknowledgment is required to indicate to the event broker that the client application received the message, and then the message can be removed from the endpoint.

Related Event Broker Provisioning and Configuration Information

For clients to consume messages from the Message VPN they are connected to, the event broker must have Guaranteed Messaging and message spooling enabled. In addition, the clients must be assigned appropriately configured client profiles and/or Access Control List (ACL) profiles:

  • To receive messages with a Guaranteed Transport delivery mode, clients must be assigned client profiles that have the allow-guaranteed‑message‑receive parameter enabled. In addition, if clients are going to use non-durable message consumers, the assigned client profiles must also have the allow‑guaranteed‑endpont-create parameter enabled because these clients automatically create temporary queues/topic-endpoints.
  • To allow clients to subscribe to topics (or to only a specific set of topics) clients must be assigned ACLs with the appropriate access controls.

For more information on how to configure event brokers for Guaranteed Messaging and authorizing connected clients through client profiles and ACLs, refer to Configuring Client Authentication.

Queues

Messages published to a queue destination are spooled to a matching queue endpoint on the event broker. Therefore, a queue acts as both a destination that messages can be published to and as an endpoint on the event broker that clients can bind to and then browse or consume messages from. In this way, a queue can be used in a typical Point-to-Point (P2P) model.

However, it is also possible to add Topic subscriptions to a queue so messages published to matching Topics are delivered to the queue. (For more information, refer to Adding Topic Subscriptions to Queues.) Therefore, it is also possible to use queues in a Publish and Subscribe (Pub/Sub) model.

Multiple flows can be bound to a queue, but a single spooled message can only be consumed by a single consuming client bound through one of those flows. If the queue is configured with an access type of exclusive, only the first flow to bind can actively receive messages. If the first flow disconnects, the second flow can start receiving messages, and so on. An exclusive queue always delivers messages in the order they are received.

If the queue is configured with an access type of non‑exclusive, each bound flow receives messages in a round-robin fashion. For more information on access types, refer to Defining Endpoint Properties in the PubSub+ JCSMP API.

Topic Endpoints

A topic endpoint attracts messages published to a Topic that match the Topic subscription that is associated with the endpoint. Topic endpoints are equivalent to durable topic subscriptions in Java Message Service (JMS). Topic endpoints can be used in a pub/sub model.

For an exclusive topic endpoint, only one client can bind and receive messages; if other clients attempt to bind, they will be rejected. An exclusive durable topic endpoint always delivers messages in the order they are received. For non-exclusive durable topic endpoints, multiple consumers can bind and each is serviced in round‑robin fashion.

  • When using the JCSMP or .NET APIs, a client must obtain the appropriate Topic instance to use Topic subscriptions to receive messages (refer to Creating Topics in the PubSub+ JCSMP API).
  • When using the JavaScript or Node.js APIs, both queues and topic endpoints are modeled as queues and passed in as a solace.QueueDescriptor object to the solace.MesssageConsumerProperties, which is used to create the message consumer.
  • It is possible for messages published with a Direct delivery mode to be spooled to a topic endpoint when there is a match between the message’s Topic destination and the Topic subscription set for the topic endpoint. In this case, when the message is spooled to the endpoint, it is given a non‑persistent delivery mode so that the receiving client can consume the message over its established consumer flow. For more information, refer to Topic Matching and Message Delivery Modes.

Endpoint Durability

Endpoints can be durable or temporary (that is, non-durable).

  • Durable endpoints have life spans independent of any particular session. Messages can accumulate on a durable endpoint even when no session is connected.

    Durable endpoints can only be used with a physical event broker when it has an Assured Delivery Blade (ADB) installed and Guaranteed Messaging and message spooling enabled. For information configuring an event broker for Guaranteed Messaging, refer to Guaranteed Messaging Configuration.

  • Temporary endpoints are created by the client in a session and last for the duration of the session. When a session is closed, temporary endpoints and their messages are deleted. On graceful closure of a client session, temporary endpoints are deleted immediately. On other closures (for example, when switching to a redundant event broker or a connection failure), temporary endpoints are maintained for a period of sixty seconds to allow the reestablishment of the session.