Configuring Topic Endpoints

To provision a durable topic endpoint in a given Message VPN, enter the following CONFIG commands:

solace(configure)# message-spool message-vpn <vpn-name>
solace(configure/message-spool)# create topic-endpoint <name>

To edit the properties of an existing, durable topic endpoint on a given Message VPN, enter the following CONFIG command:

solace(configure)# message-spool message-vpn <vpn-name>
solace(configure/message-spool)# topic-endpoint <name>

Where:

<name> is a topic endpoint name of up to 200 characters (the only invalid characters are '<>*?&;). Each topic endpoint name in a Message VPN must be unique.

The no version of this command, no topic-endpoint <name>, deletes the specified durable topic endpoint from the Message VPN. However, the topic endpoint cannot be deleted until it is shutdown, which disables client access to the topic endpoint. Refer to Enabling/Disabling Clients from Publishing to/Consuming from Topic Endpoints for more information.

:   The name for a temporary topic endpoint can be a maximum of 250 characters. A temporary topic endpoint differs from a durable topic endpoint provisioned through the Solace CLI or SolAdmin in that it is dynamically provisioned by a client application and can only exist as long as the client is connected.

:  The topic subscription that a topic endpoint will spool messages for is not specified when a topic endpoint is provisioned; it is specified by a client when that client requests to bind a consumer flow to the topic endpoint (for information, refer to Creating Flows).

Configuring Access Types

To configure the client access type for durable topic endpoints on the Solace PubSub+ event broker on a per-topic-endpoint basis, enter the following CONFIG command.

solace(configure/message-spool/topic-endpoint)# access-type {exclusive | non-exclusive}

Where:

exclusive specifies that only one client can bind to and be serviced by the topic endpoint; if other consumers attempt to bind, they will be rejected.

non-exclusive specifies that all bound flows are able to receive messages, and when multiple flows are bound to a non‑exclusive topic endpoint, they receive messages in a round-robin fashion.

The no version of this command, no access-type, reverts the setting back to the default (exclusive).

:  The client access type cannot be changed until client access to the durable topic endpoint is shutdown (refer to Enabling/Disabling Clients from Publishing to/Consuming from Topic Endpoints).

Configuring Max Number of Flows That May Bind

To configure the maximum number of flows that can bind to a non-exclusive durable topic endpoint on the Solace PubSub+ event broker on a per-topic-endpoint basis, enter the following CONFIG command.

solace(configure/message-spool/topic-endpoint)# max-bind-count <value>

Where:

<value> is an integer value specifying the maximum number of flows that can bind to a non-exclusive durable topic endpoint. If the topic endpoint's access type has been set to exclusive, the value of max-bind-count is considered to be 1 regardless of the set value. The valid range is 0 to 10,000. The default value is 1.

The no version of this command, no max-bind-count, resets the maximum number of flows that can bind to a durable topic endpoint back to the default.

:  A single client can create multiple flows, and flows may originate from one or more clients.

Configuring Max Number of Delivered Unacked Messages

For a given topic endpoint you can configure the maximum number of Guaranteed messages that can be delivered to a consuming client through a flow but remain unacknowledged by that client. That is, how many outstanding unreturned message acknowledgments are acceptable per flow bound to the topic endpoint.

After this maximum number of delivered but unacknowledged messages is exceeded, the Solace PubSub+ event broker stops delivering messages to the client on the flow until the client acknowledges messages that are already delivered.

To configure a limit for maximum outstanding number of delivered but unacknowledged messages per flow, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# max-delivered-unacked-msgs-per-flow <max>

Where:

<max> is an integer value specifying the maximum number of messages that can be delivered to a client on a subscriber flow but remain unacknowledged by the client. The valid range is 1 to the maximum value supported by the event broker. The maximum value depends on the type of event broker used (for example, Solace PubSub+ 3530 or 3560). The default value is 10000. If the maximum number of delivered but unacknowledged messages amongst all clients is reached, the Solace PubSub+ event broker will stop delivering messages to all clients until some clients return acknowledgments back to the event broker.

The no version of this command, no max-delivered-unacked-msgs-per-flow, resets the maximum number unacknowledged messages back to the default value.

Modifying max-delivered-unacked-msgs-per-flow may negatively impact performance if it is set lower than the transport window size used by consuming clients.

Provided the application is using at least Version 10.0.2 of the Java or JMS APIs, or at least Version 7.2.5 of the C, .NET, or JavaRTO APIs, the API learns about the configured max-delivered-unacked-msgs-per-flow at bind time and adjusts its ACK threshold accordingly for best performance. If the max-delivered-unacked-msgs-per-flow is changed while clients are bound, the clients may need to be disconnected and allowed to reconnect to receive the new value.

Older versions of the APIs do not adjust their ACK threshold based on the max-delivered-unacked-msgs-per-flow setting. If applications using older versions of the API bind to the topic endpoint, its max-delivered-unacked-msgs-per-flow must be set to a value greater than or equal to the transport window size used by the applications to ensure performance.

Configuring Max Permitted Message Sizes

To configure the maximum message size allowed for the given topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# max-message-size <size>

Where:

<size> is an integer value specifying the maximum message size (in bytes) permitted for the topic endpoint. The valid range is 0 to 30000000. For Solace PubSub+ 3230, the maximum message size (in bytes) permitted for the topic endpoint is lower. The valid range for a Solace PubSub+ 3230 is 0 to 10000000. The default value is 10000000.

The no version of this command, no max-message-size, resets the permitted message size available for use by the topic endpoint back to its default value.

Configuring Max Permitted Redelivery Attempts

You can use the max-redelivery option to configure the maximum number of times the topic endpoint can attempt to redeliver a message to a client. If the number of redelivery attempts for a given message exceeds the max-redelivery value, the message is either discarded, or, if a DMQ has been created and is ready to accept messages, the message is removed and placed in the DMQ.

To configure the maximum number of times a topic endpoint can attempt to redeliver a message to a client, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# max-redelivery <count>

Where:

<count> is the maximum message redelivery attempts possible. The valid range is 0 to 255. 0 means try forever. The default is 0.

The no version of this command, no max-redelivery, resets the max-redelivery value back to the default value.

Configuring Max Spool Usage Values

To configure the maximum message spool usage for durable topic endpoints on the Solace PubSub+ event broker on a per-topic endpoint basis, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# max-spool-usage <size>

Where:

<size> is an integer value specifying the maximum amount of message spool disk space permitted for the topic endpoint in MB. The default value is 4000, and the valid range is 0 to 6000000. Setting the value to 0 is not recommended for topic endpoints.

The no version of this command, no max-spool-usage, resets the default.

Configuring Permissions for Non-Owner Clients

To configure the permission levels for all clients other than the owner of the given durable topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# permission all {read-only | consume | modify-topic | delete}

Where:

read-only provides clients with read-only access permission to messages spooled to the topic endpoint

consume provides clients with read-only permission and the ability to delete messages from the topic endpoint

modify-topic provides clients with consume permission and the ability to modify the topic or selector assigned to the topic endpoint

delete provides clients with modify-topic permission and the ability to either delete messages from the topic endpoint, or delete the topic endpoint altogether. Note that clients cannot delete a topic endpoint if it was created using the CLI or SEMP by a management user.

The no version of this command, no permission, resets the permission levels for all clients other than the owner of the topic endpoint to none; that is, no access. A client access level of none is the default permission level.

Configuring Reject Low‑Priority Message Limits

To configure a reject-low-priority-msg-limit for a topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# reject-low-priority-msg-limit <limit>

Where:

<limit> is the total number of low- and high‑priority messages spooled. When this value is exceed, the topic endpoint discards any further published low-priority messages, but spools published high-priority messages. Valid values are from 0 through 4294967295. If value of 0 is set, the topic endpoint only spools high-priority messages are spooled. The default value is 0.

Configuring Topic Endpoint Event Thresholds

To configure the thresholds that control when message spool-related events are generated for the given topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# event

The CLI is now at a configuration level from which you can configure the set and clear thresholds for various message spool events for the topic endpoint.

:  For specific information on the available Message VPN-level message spool events that are generated for a topic endpoint and how to set the set and clear thresholds for generating those events, refer to Topic Endpoint Event Thresholds.

Configuring Topic Endpoint Owners

The ownership of a topic endpoint is established in the following manner:

  • If a client application dynamically provisions a topic endpoint through a Solace messaging API, the client username associated with the client is automatically given ownership of that topic endpoint.
  • If a CLI user manually provisions a topic endpoint through the Solace CLI, no client username is automatically given ownership of that topic endpoint.
  • Any CLI user with Read-Write or Admin access to the Message VPN that the topic endpoint belongs to has full permissions on the topic endpoint (that is, management has ownership).

To give ownership of the given topic endpoint to any clients associated with a particular client username, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# owner <owner>

Where:

<owner> is an existing client username account name.

The no version of this command, no owner, resets the ownership of the topic endpoint back to the default of none.

  • Client access to the durable topic endpoint must first be disabled through before an owner can be assigned. (Refer to Enabling/Disabling Clients from Publishing to/Consuming from Topic Endpoints.)
  • The topic endpoint owner has full unlimited permissions for the topic endpoint. That is, the owner can consume (read and delete received messages), delete, or modify topics spooled to the topic endpoint.

Configuring Message Discard Handling

The reject-msg-to-sender-on-discard option configures how a durable topic endpoint should handle ingress messages discards that occur due to one or more of the following conditions:

  • adding the published message will exceed the configured message quota for the topic endpoint
  • the published message exceeds the maximum message size allowed for the topic endpoint
  • the client published the message to a topic it has also subscribed to and has an active flow with "No Local Delivery"

If published message is not spooled because of any of the conditions above, the following will occur:

  • If the reject-msg-to-sender-on-discard option is enabled for the topic endpoint, the message is discarded, and a nack is returned to the sender. In this case, the message cannot be spooled to any other queue or topic endpoint (regardless of whether those endpoints have the reject-msg-to-sender-on-discard option enabled or disabled).
    • A nack is only sent to the client if the message was originally published with a non-persistent or persistent delivery mode. If the message was published with a Direct delivery mode, but was changed to non-persistent because of a topic match, and was then discarded, a nack is not returned to the sender.
    • How to handle the nack is the responsibility of the publishing application—not Solace APIs. Solace APIs do not retransmit nacked messages.
  • If the reject-msg-to-sender-on-discard option is not enabled for the topic endpoint, the ingress message is "silently" discarded (that is, it discards the message but returns an acknowledgment to the sender). In this case, other endpoints can spool the message—if they do not encounter any of the conditions listed above.

To enable the reject-msg-to-sender-on-discard option for a durable topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# reject-msg-to-sender-on-discard 

The no version of this command, no reject-msg-to-sender-on-discard, disables the reject-msg-to-sender-on-discard option on a durable topic endpoint.

  • By default, the reject-msg-to-sender-on-discard option is not enabled for topic endpoints.
  • The reject-msg-to-sender-on-discard option also affects the behavior of transacted sessions. If ‘acks’ are being returned to the sender, then the transacted session commit succeeds. If a nack is returned to the sender, then the commit fails. For more information, refer to Using Local Transactions for Solace APIs and Using Transacted Sessions for the JMS API.

Enabling/Disabling Clients from Publishing to/Consuming from Topic Endpoints

  • To prevent client access to the specified durable topic endpoint, enter the following CONFIG command:
    solace(configure/message-spool/topic-endpoint)# shutdown [ingress | egress | full]
  • To enable client access to the specified durable topic endpoint, enter the following CONFIG command:
    solace(configure/message-spool/topic-endpoint)# no shutdown [ingress | egress | full]

Where:

ingress specifies disable messages from being added to the durable topic endpoint.

egress specifies disable clients from binding to the durable topic endpoint to consume messages from it.

full specifies disable messages from being added to the durable topic endpoint and disable clients from binding to the durable topic endpoint. This is the default value.

Enabling/Disabling Propagating Consumer Acks to Replicated VPNs

By default, endpoints on an active Replication Message VPN propagate consumer acks that they received to the standby Replication Message VPN.

  • To prevent the topic endpoint from propagating consumer acks to the standby Replication Message VPN, enter the following CONFIG command:
    solace(configure/message-spool/topic-endpoint)# no consumer-ack-propagation
  • To allow the topic endpoint to propagate consumer acks to the standby Replication Message VPN, enter the following CONFIG command to allow it to do so:
    solace(configure/message-spool/topic-endpoint)# consumer-ack-propagation

Enabling Rejection of Low‑Priority Messages

To protect against message congestion scenarios where such a large number of published messages are delivered to a topic endpoint that system performance decreases, you can enable the topic endpoint to discard low‑priority messages but continue to spool high‑priority published messages. The topic endpoint selectively discards low-priority messages only after the total number of low- and high‑priority messages spooled exceeds the value set for the reject low‑priority message limit (refer toConfiguring Reject Low‑Priority Message Limits). By default, the reject low‑priority message feature is not enabled for endpoints.

:  To avoid inadvertently discarding all low-priority messages, it is recommended that you change the default value of 0 for the reject low‑priority message limit before enabling the reject low‑priority message feature to something more appropriate for your network.

To enable the reject low‑priority message feature for a topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# reject-low-priority-msg

The no version of this command, no reject-low-priority-msg, configures the durable topic endpoint to not perform reject low‑priority message limit checking on published messages (the default configuration).

  • When this feature is enabled, the reject-msg-to-sender-on-discard option (refer to Configuring Message Discard Handling) must also be enabled for the topic endpoint so that session events are sent to the publishing clients whenever messages are not enqueued on the topic endpoint and are discarded.
  • Client applications can use the Solace messaging APIs to assign message priorities through the Class of Service (COS) property.

Configuring Max Message TTLs

You can configure a Max Time to Live (TTL) value for a durable topic endpoint so that received messages are provided with expiration value to limit how long they can remain on that durable topic endpoint when a Max TTL is used. If a message is not consumed and its expiration time is reached, the message is discarded or is moved to a Dead Message Queue (DMQ) (if the publisher has flagged the message as DMQ-eligible).

A Max TTL value is only applied to messages when the Respect TTL option is enabled for the endpoint. It is also possible for a message to have a publisher-supplied TTL, which indicates how long the publisher considers a message to be valid. This differs from Max TTL in that the publisher TTL expiration starts when a message is published and counts down as the message passes through the network. The Max TTL only applies when a message is on the endpoint. If a message has both a publisher-assigned TTL and an endpoint-assigned Max TTL, the Solace PubSub+ event broker will use the minimum of the two TTL values when the message is on the endpoint.

To define a maximum TTL for the topic endpoint to apply to messages to be spooled, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# max-ttl <ttl>

Where:

<ttl> is maximum number of seconds that messages can stay on the topic endpoint when it has respect-ttl enabled.

The no version of this command, no max-ttl, sets the default Max TTL value 0 (disabled), which means that no expiry time is applied to any received messages spooled to that endpoint.

  • Any messages already on the queue endpoint when this parameter is configured or changed will not be impacted; those messages will continue to use the TTL assigned to them (if any) when they were spooled to the endpoint.
  • A Max TTL cannot be set on DMQs.
  • Using Max TTL increases the amount of state that needs to be maintained for each message stored in the endpoint and will affect the Guaranteed messaging performance.

Enforcing Whether to Respect Message TTLs

You can configure a topic endpoint to either respect or ignore messages' Time‑to-Live (TTL) expiration values. This includes both the TTL value that can be set by publishing clients and the TTL value set on an endpoint through its configured Max TTL property.

When a topic endpoint is configured to respect message TTLs, messages' TTL values are checked. If a message’s TTL is expired, it is either removed from the message spool and discarded, or, if the message is eligible for a DMQ, it is moved to a DMQ provisioned on the event broker. If a message does not have an assigned TTL, then it will never expire. Note that by default, the DMQ is set to ignore message TTL expiry times and cannot be changed.

When a topic endpoint is configured to ignore message TTLs, spooled messages are not removed, even if they have been spooled for an amount of time that exceeds their set TTL value.

To configure a topic endpoint to respect message TTLs, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# respect-ttl

The no version of this command, no respect-ttl, configures a durable topic endpoint to ignore message TTL expiry times (the default configuration).

:   If the topic endpoint’s respect-ttl option is enabled after messages with a TTL value have been spooled, those existing spooled messages are not removed—even if their TTL expiration value has been exceeded. Only ingress messages with TTL values that are received after the respect-ttl option is enabled can be removed because TTL violations.

Enforcing Whether to Respect Message Priority Values

You can configure an endpoint to either respect or ignore messages' priority values.

When an endpoint is configured to respect message priority, the priority field in all received messages is used to deliver the message in the appropriate order, in other words messages with a higher priority are sent before messages with a lower priority.

The event broker recognizes ten levels of priority from 0 (lowest) to 9 (highest). If the priority field in the message is greater than 9, then the event broker treats it as priority 9. Received messages that do not have a priority field are treated as priority 4.

When transitioning from priority respected to ignored, all messages remain at their existing priorities. Although the queue does not respect priority values in new messages, priority values in existing messages are respected. Since new messages are treated as priority 9, when the queue is configured to ignore message priority, new messages may bypass messages that were received before the transition.

You must fully shutdown an endpoint before you can change whether it respects or ignores priority values.

Enforcing message priority increases the chance that duplicate messages will be delivered to a consuming client after it recovers from a connection failure.

To configure a topic endpoint to respect message priority values, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# respect-message-priority

The no version of this command, no respect-message-priority, configures a durable topic endpoint to ignore message priority values (the default configuration).