Endpoints

The Solace PubSub+ message broker supports two types of endpoints for receiving, storing, and delivering Guaranteed messages:

Endpoints are of local message broker significance only, and are not a network wide concept insofar as a consumer must connect to the message broker that has the endpoint. There is no propagation through message broker to message broker control / routing protocols of the existence of endpoints. Thus, there is no enforcement of endpoint name uniqueness throughout a network by the message brokers.

Queues

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.

Queue Access Types

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

Adding Topic Subscriptions to Queues

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

Adding Topic Subscription Exceptions 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 message 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.

Topic Endpoints

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).

Endpoint Durability

Queues and topic endpoints can be either durable or temporary.

Durable Endpoints

Durable queues and topic endpoints are provisioned objects on the message broker that have a life span independent of a particular client session. They also survive a message broker restart and are preserved as part of the message 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.

Durable Endpoint Access Types

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 Endpoints

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:

Endpoint Permissions and Access Control

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.

Browsing Queues

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.)

Queue Browsing

Selectors

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

Guaranteed Message Selectors

Dead Message Queues

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 #DEAD_MSG_QUEUE.

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.

Last Value 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.

Message priority

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 message 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.

Publisher identification

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 uniquePubId/> (with 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 Pub1/price/equities/apple, while 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, */price/equities/apple.

Message selectors

Message selectors are not supported with Last Value Queues.