The Solace PubSub+ event broker supports two types of endpoints for receiving, storing, and delivering Guaranteed messages:
Endpoints are of local event broker significance only, and are not a network wide concept insofar as a consumer must connect to the event broker that has the endpoint. There is no propagation through event broker to event broker control / routing protocols of the existence of endpoints. Thus, there is no enforcement of endpoint name uniqueness throughout a network by the event brokers.
A queue acts as both a destination that clients can publish messages to, and as an endpoint that clients can bind consumers to and consume messages from. A queue is typically used in a point-to-point (PTP) messaging environment.
Although many consumers can bind to a queue, an individual message spooled to a queue can only be consumed by a single consumer.
It's 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.
Queues are significantly more flexible than topic endpoints and are the recommended approach for most applications. The use of topic endpoints should be restricted to JMS applications.
A queue has an access type, which determines how messages are delivered when multiple consumer flows are bound to it. Queues can be assigned one of the following access types:
- Exclusive: Only one consumer can receive a message at any one time, while additional consumers may be connected as standby. That is, only one Flow can be active. Only the first consumer to bind can receive messages. If the first consumer disconnects, the second consumer receives data, and so on. An exclusive queue always delivers messages in the order they are received.
- Non‑exclusive: Multiple consumers can bind to a non-exclusive queue. Each consumer is serviced in round‑robin fashion. This provides load-balancing; however, if a connection fails, then unacknowledged messages are delivered to another consumer with the re-delivered flag set. In this way, messages can be delivered to consumers out of order.
The access type can be changed for a durable queue, but only when client access to the queue has been disabled.
Also, a queue's access type doesn't affect the ability of clients to browse a message on a queue with a queue browser
You can add one or more topic subscriptions to a durable queue so that Guaranteed messages published to matching topics are also delivered to and spooled by the queue.
As shown in the illustration below, this allows a single message published to a topic to be delivered to a combination of topic endpoints, one or more queues, or even clients with matching Direct Messaging topic subscriptions. For information on how a message’s delivery mode can be changed to deliver a message to a client’s topic subscription, refer to Topic Matching & Message Delivery Modes.
Possible Routing of a Message According to its Topic
Any Guaranteed messages published to topics that match subscriptions associated with queues are delivered to those queues. Error indications are returned to the publisher if the message cannot be delivered to one or more queues for any reason. That is, the feedback to the publisher is identical to that provided when the messages are published directly to the queues).
Topic subscription to queue mappings are applicable to both durable and non‑durable queues. Deletion of a queue for any reason results in the deletion of all topic subscription to queue mappings for that queue.
It's also possible for published Guaranteed messages to be spooled to a queue if the queue is assigned a topic subscription that matches the message’s topic destination. For more information, refer to Adding Topic Subscriptions to Queues
In addition to topic subscriptions, you can add one or more topic subscription exceptions to a durable queue so that Guaranteed messages published to matching topics are discarded and not delivered to the queue.
Using topic subscription exceptions allows you to easily exclude specific topics from the set of topics delivered to a queue by adding a leading "!" character to the topic subscription. For example, if you add a topic subscription "animals/f*" and a topic subscription exception "!animals/fox" to a queue, guaranteed messages published to "animals/frog" are delivered to the queue; however, messages published to "animals/fox" are discarded.
Topic subscription exceptions are enabled by default, and always take precedence over subscriptions regardless of the order in which the subscriptions and the exceptions are configured. To enable or disable this functionality on event brokers refer to System-Level Subscription Exception Configuration.
For information describing how to add subscription exceptions to queues refer to Adding Topic Subscription Exceptions to Queues.
A topic endpoint attracts messages published to a topic for which the topic endpoint has a matching topic subscription. The topic subscription for the topic endpoint is specified in the client request to bind a Flow to that topic endpoint.
Topic endpoints can be used in a pub/sub model. They are equivalent to durable topic subscriptions in Java Message Service (JMS).
Queues and topic endpoints can be either durable or temporary.
Durable queues and topic endpoints are provisioned objects on the event broker that have a life span independent of a particular client session. They also survive an event broker restart and are preserved as part of the event broker configuration for backup and restoration purposes. Administrators can provision durable queues and topic endpoints through the Solace CLI, SEMP, or SolAdmin; client applications can dynamically provision durable endpoints through the Solace messaging APIs.
A durable endpoint has an associated access type which determines how messages are delivered to bound consumer flows. Durable endpoints can be assigned one of the following access types:
- Exclusive: For a queue, multiple subscriber flows established by clients can be bound, but only one flow out of all the bound flows is able to receive messages at a time. The first flow to bind to the queue can consume messages from it, and when that flow disconnects, the next oldest flow to bind becomes active and can begin receiving messages, and so on .For a topic endpoint, only one consumer can bind and receive messages; if other consumers attempt to bind, they will be rejected. An exclusive durable topic endpoint always delivers messages in the order they are received.
- Non‑exclusive: For either queues or topic endpoints, multiple consumers can bind to a non-exclusive durable topic endpoint, and each is serviced in round‑robin fashion.
Temporary queues and topic endpoints are dynamically created and destroyed by client applications. Temporary queues and topic endpoints are typically used as temporary destinations for service requests.
When a client application has a connected session, it can provision a temporary queue or topic endpoint and create a consumer flow to bind to it. These temporary queues and topic endpoints are non-durable because they only last as long as the client’s session is connected. Only a single consumer may bind to a non-durable endpoint, and there is no support for multiple consumers or non-exclusive access.
The naming of the temporary destinations is controlled by the application. On a BIND request from the client, a name is provided. It the destination does not exist, one is created.
When a client dynamically creates a queue, it is configured by those endpoint properties and provision flags that the client may provide with a create API function or method. Any other endpoint parameters are then configured with the values used for endpoints provisioned by an administrator through the Solace CLI. By default, the system defaults are used. However, it is also possible to use CLI-provisioned queues and topic endpoints with custom values, and those values will be applied to any new client-created queues and topic endpoints.
A non-durable queue or topic endpoint can be dynamically created if:
- The client is associated with a profile that permits clients to create endpoints. See Allowing Guaranteed Endpoint Creates.
- The maximum number of endpoints available for the Message VPN that the client is connected has not been reached. See Configuring the Max Number of Endpoints.
The maximum number of endpoints permitted per client username within a client profile has not been exceeded. See Configuring the Max Endpoints Permitted Per Client Username.
The number of endpoints does not exceed the system-wide limit.
Any queue, durable or non-durable, with a commonly recognized name is a well-known queue. The well-known queue name is specified by the application rather than being generated by the API. Applications can send messages to a well-known queue without any communication with the creator of the queue. A well-known queue name can be used to send messages to the queue, as long as it exists somewhere within a network of event brokers.
One of the key features of the well-known queue is its durability. Administrators can use queue templates to control the durability of well-known queues. A well-known durable queue can be converted to a well-known non-durable queue by specifying durability override through a queue template. To learn how to configure durability override using a queue template, refer to Configuring Queue Templates. For overview information on queue templates, see Endpoint Templates.
Also, when using a well-known non-durable queue in a request/reply messaging pattern, there is a race condition where the recipient of a request might reply before the respondent's node knows how to route the response to the requestor's node. As such, well-known queues are not recommended for use in a request/reply messaging pattern. For the request/reply pattern, it is recommended to use the client's #P2P topic prefix for a direct messaging reply-to and an Anonymous Queue's network topic as a reply-to for guaranteed messaging.
Well-known queues can be created by management interfaces such as the Solace CLI, Solace PubSub+ Manager, SEMPv2, or they can be created by applications through the Solace Messaging API (See Dynamically Provisioning Endpoints).
Unlike well-known queues, the anonymous queue name is generated by the API rather than being specified by the application, hence the queue name is not well-known. To send a message to an anonymous queue, the destination must be sent to peers as it is not known ahead of time. Often this is done in the reply-to field of a message in a request/reply messaging pattern. A mechanism is built into Solace PubSub+ networks to prevent race conditions in sending to anonymous queues after they are created. This makes anonymous queues particularly well-suited for request/reply messaging patterns.
Anonymous queues are always non-durable, which means the queue and the data on the queue are removed when a client unbinds from the queue or the client is disconnected and fails to re-establish session within sixty seconds.
The flow chart below shows the layers of access control that are used to determine whether clients may bind to and browse or consume messages from endpoints.
Access Control Layers Used for Consuming Clients
The first layer is a configuration in the associated client profile that determines whether the client is permitted to receive Guaranteed messages. If this is allowed, then the endpoint permissions are checked.
The endpoint permission rules are:
- The owner has full access to an endpoint. The owner of an endpoint is configurable. In the case of dynamically‑created endpoints, the default owner is the client username of the client that created the endpoint.
- CLI-created queues and topic endpoints can only be deleted through the CLI.
- Each endpoint has a “Permission All” parameter that determines what access control clients other than the owner of an endpoint have. By default, the “Permission All” parameter has a permission level of
none. However, permissions can be explicitly specified when the endpoint is initially created through the CLI or dynamically through a messaging API. The permission level can also be changed through the CLI.
The permissions available at the following levels are:
- none—no access.
- read-only—allows the messages only to be read; they cannot be removed or consumed from the message spool.
- consume—allows messages to be browsed and consumed from the message spool.
- modify-topic—allows the topics assigned to endpoints to be modified. Modify-topic also implicitly includes same permissions as consume.
- delete—allows deleting queues or topic endpoints. Delete also implicitly includes same permissions as modify-topic.
Client applications using Solace enterprise APIs can create a queue browser in a session to look at messages spooled on a queue in order of oldest to newest without consuming them. That is, browsing messages returns the full content of messages, complete with all message headers and payloads, but those browsed messages are not removed from the message spool. You should be aware that when you browse a queue that has an active consumer, it's possible that the browser won't receive all messages published to the queue because the consumer can receive and acknowledge messages before they are delivered to the browser
The figure below shows how a Browser Flow returns messages from the queue, without consuming them so that clients with established Flows can still consume them. In this example, a selector string is also used so that the client application only browses messages that match that selector. (Refer to Selectors for more information.)
Selectors are filters that clients can apply when they bind to endpoints. They enable clients to filter which messages they are interested in receiving, as determined by the messages’ header field and property values. A selector is a string up to a maximum of 2,000 bytes that uses a conditional expression syntax that is a subset of SQL92.
As shown in the figure below, selectors can filter messages from queues and topic endpoints.
- For queues: Any messages that do not match the client’s selector string are not delivered to the requesting client, but remain in the queue.
- For topic endpoints: Any messages that do not match the selector are not delivered to the requesting client, but are removed from the topic endpoint.
Selectors on topic endpoints are a background process to avoid slowing down publishing pipelines. It is possible to see the number of messages in a topic endpoint shrink as the selector is applied. For example, if 100 messages are published which match the associated topic of a topic endpoint, then these 100 messages are spooled into the topic endpoint. The associated selector starts testing these 100 new messages, and any messages that the selector rejects are removed from the topic endpoint. If there is a selector associated with a topic endpoint, then the selector must filter the messages prior to delivery to the flow. If either the topic or selector changes, then all messages are removed from the topic endpoint before applying the new topic and selector.
Client applications can also specify a selector string when browsing a queue so that the client only browses messages that match the selector.
Guaranteed Message Selectors
By default, Guaranteed messages are removed from a durable endpoint's message spool and discarded when:
- the number of redelivery attempts for a message exceeds the Max Redelivery value for the original destination endpoint;
- or a message’s TTL value has been exceeded and the endpoint is configured to respect message TTL expiry times.
However, messages that are flagged as DMQ-eligible by the publishing client can be sent to a DMQ assigned to the endpoint rather than be discarded.
Any durable queue on the same Message VPN as the endpoint that the messages were spooled to can be assigned as that endpoint's DMQ. Although durable endpoints are assigned a default DMQ (
#DEAD_MSG_QUEUE), every durable endpoint can be assigned a specific DMQ. Therefore, there can be multiple DMQs per Message VPN.
If an endpoint's assigned DMQ does not exist, the Guaranteed messages will be discarded even if they are DMQ-eligible. In addition, although it is the default DMQ, a management user must manually create the
The following are use-cases for how using different endpoints within a Message VPN associated with different DMQs might be advantageous:
When messages are delivered to an endpoint through topic-to-queue mapping, and that message is subsequently moved to the default DMQ used by multiple endpoints, there is no way for an application servicing the DMQ to know which endpoint the message came from. Having a DMQ that is used only by a single endpoint would solve this problem.
- It is possible to deliberately use message TTLs in conjunction with the DMQs to achieve a delayed delivery of messages. If client applications bind to a DMQ rather than a "regular" endpoint, they will only consume expired messages that were moved a DMQ. In this use-case, applications don’t want the messages from multiple endpoints converging on a single DMQ.
For configuration information, see Dead Message Queues.
If a queue is assigned a max-spool-usage value of 0, the queue can only spool the last message it received. In this configuration, the queue is acting as a so-called Last Value Queue. For instructions on how to set max-spool-usage to 0, refer to Configuring Max Spool Usage Values.
Last Value Queues always store the last message received, regardless of the priority value of the message (see Message Priority).
Application of topic subscriptions
A client publishing Guaranteed messages can apply a topic subscription to a Last Value Queue so that it attracts all the messages that the client publishes. This allows the client to use the Last Value Queue to accurately determine the very last Guaranteed message that it successfully published.
This could be beneficial, for example, if an application failure occurs after a message has been published. In this case, if the client application does not receive an acknowledgment from the event broker for the message, it does not know if the published message was lost entirely, or if the message was received but just the acknowledgment was lost. If a Last Value Queue is used, when the client reconnects and rebinds to the Last Value Queue, it can determine what was the last successfully published message, and it can continue publishing from where it left off without creating duplicate messages or losing messages.
When there is more than one publisher for a given topic, the publisher should be identified in the published topic, which can be wildcarded by subscribing applications.
For example, assign the Last Value Queue for each publishing client a topic subscription of the form
Pub1/> for the first publisher,
Pub2/> for the second publisher, and so on). The clients can then publish messages to topics of the form
uniquePubId/some/hierarchical/topic/. For example,
Pub1 might publish to
Pub2 might publish to
Pub2/price/equities/apple, and so on. This allows clients to specifically subscribe to their own Last Value Queue, but other clients, who also want to receive messages on those topics, can use a topic subscription of the form
*/some/hierarchical/topic. For example,
Message selectors are not supported with Last Value Queues.
Endpoint templates are configurable objects that administrators can use to specify custom attributes and parameters for any new client created endpoints. Any custom configuration associated with the endpoint template will be applied to the client created endpoints based upon the endpoint name. You can associate multiple queues to an endpoint template; this means that the clients can use multiple templates to create endpoints with different characteristics.
Administrators can choose which client created endpoints use specific endpoint templates through two mechanisms:
- Endpoint Templates have a
name-filterthat allows them to match an endpoint name to an endpoint template. This allows client-created queues or topic endpoints the ability to copy attributes from the specified endpoint template dynamically when being created. Refer to Setting Name Filters to Match Queue Names or Setting Name Filters to Match Topic Endpoint Names for more information.
- Client Profiles have an optional
copy-from-template-on-createcommand that can be used to copy custom values from an endpoint template to a client created endpoint. Any custom configuration made to the given endpoint template will apply to the client created endpoint by any client using that Client Profile. For more information on this topic, go to Configuring Initial Values for Client-Created Endpoints.
In the below topics we will discuss the type of endpoints that are eligible for using templates and the endpoint fields that are copied from the template to the client created endpoints.
This feature only applies to Solace PubSub+ event broker 9.4.0 release onwards.
The following table provides information on the types of endpoints that use templates.
|Category||API Created||Endpoint Type||Can use Template from Client Profile||Included in Template name matching|
|SMF/AMQP Queues/Topic Endpoints||Yes||Well Known||Yes||Yes|
|SMF/AMQP Queues/Topic Endpoints||Yes||Anonymous||Yes||No|
|Administrator Created Queues/Topic Endpoints (CLI/SEMP/WebUI)||No||Any||No||No|
|Clustering Queues||No||Well Known||No||No|
The attributes that are copied from an endpoint template to the client-created queues or topic endpoints depend on whether the endpoint is a queue, topic endpoint, or a Dead Message Queue (DMQ). Not all configurable values are copied from an endpoint template to a queue, topic endpoint, or a DMQ.
|Attribute Copied During Creation of|
|Attribute||Queue||Topic Endpoint||DMQ||MQTT Session Queue|
|Primary/Backup (VR Index)||×||×||×||×|
|Consumer Ack Propagation||✓||✓||✓||✓|
|Event/Bind Count Thresholds||✓||✓||✓||✓|
|Event/Reject Low Priority Message Thresholds||✓||✓||✓||✓|
|Even/Spool Usage Thresholds||✓||✓||✓||✓|
|Max Bind Count||✓||✓||✓||✓|
|Max Delivered Unacked Message Per Flow||✓||✓||✓||✓|
|Max Message Size||✓||✓||✓||✓|
|Max Spool Usage||✓||✓||✓||✓|
|Reject Low Priority Message Limit||✓||✓||×||✓|
|Reject Message to Sender on Discard||✓||✓||✓||✓|
|Respect Message Priority||✓||✓||✓||×|
To learn how to configure endpoint templates, go to Configuring Endpoint Templates.