Configuring Queues

Queues can be durable or temporary (non-durable). Temporary queues are dynamically created and destroyed by client applications. This section discusses how to create and configure durable queues.

You can also configure these options in PubSub+ Broker Manager. For more information, see Configuring Queues for PubSub+ Cloud or Configuring Queues for software event brokers and appliances.

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

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

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

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

Where:

<name> is a queue name of up to 200 characters (only reserved queue names can begin with # and invalid characters are '<>*?&;). If the name contains a hierarchy of levels (for example, "a/b") each level of the hierarchy must contain one or more valid characters, and the name can't begin or end with a slash. Each queue name in a Message VPN must be unique.

A temporary queue differs from a durable queue provisioned through the Solace CLI or PubSub+ Broker Manager in that it's dynamically provisioned by a client application and can only exist as long as the client is connected.

The no version of this command, no queue <name>, deletes the specified durable message queue from the Message VPN. However, the queue cannot be deleted until it's shutdown, which disables client access to it. For more information, see Enabling / Disabling Client Access to Queues.

The following sections discuss how you can configure the parameters and features associated with a durable queue.

You can also watch these videos about the different ways to configure queues:

Configuring Access Types

To configure the client access type for durable message queues on PubSub+ event brokers on a per-queue basis, enter the following CONFIG command.

The client access type cannot be changed until client access to the durable message queue is disabled. For more information, see Enabling / Disabling Client Access to Queues.

PubSub+(configure/message-spool/queue)# access-type {exclusive | non-exclusive}

Where:

exclusive—specifies that 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—specifies that multiple consumers can bind to the queue, which enables load balancing and consumer auto-scaling. A non-exclusive queue can be non-partitioned or partitioned.

  • For a non-partitioned queue (partition count is zero), each consumer is serviced in a round-robin fashion. If a connection fails, 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. This type of queue is sometimes referred to as a "competing consumer" queue.
  • For a partitioned queue (partition count is greater than zero), each consumer is delivered messages from one or more partitions. Messages are mapped to partitions based on a hash of the partition key, which is set by the publishing application. Message order is maintained within a partition, but not between partitions.

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

Configuring Max Number of Flows That May Bind

To configure the maximum number of flows that can bind to a durable message queue on a PubSub+ event broker on a per-queue basis, enter the following CONFIG command.

PubSub+(configure/message-spool/queue)# max-bind-count <value>

Where:

<value> is the integer value specifying the maximum number of flows that can bind to a durable message queue. The valid range is 0 to 10,000. The default value is 1,000.

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

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

Enabling / Disabling Propagating Consumer ACKs to Replicated VPNs

By default, endpoints on an active replication Message VPN propagate the consumer ACKs that they have received to the standby replication Message VPN.

To prevent the queue from propagating consumer ACKs to the standby replication Message VPN, enter the following CONFIG command:

solace(configure/message-spool/queue)# no consumer-ack-propagation

Alternatively, if the queue was allowed 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/queue)# consumer-ack-propagation

Bridges cannot bind to queues configured with consumer-ack-propagation disabled.

Configuring Queue Event Thresholds

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

solace(configure/message-spool/queue)# event

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

For specific information on the available Message VPN-level message spool events that are generated for a queue and how to set the set and clear thresholds for generating those events, see Queue Event Thresholds.

Configuring Max Permitted Number of Delivered Unacked Messages

For a given queue you can configure the maximum number of Guaranteed messages that can be delivered to a client through a subscriber flow (that is, an egress flow) but remain unacknowledged by that client. That is, how many outstanding non-returned message acknowledgments are acceptable per flow bound to the queue.

After this maximum number of delivered but unacknowledged messages is exceeded, the 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-queue)# 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 PubSub+ event broker used. The default value is 10000. If the maximum number of delivered but unacknowledged messages amongst all clients is reached, the 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.

Possible performance impact

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

Provided the application is using at least Version 10.0.2 of the JCSMP or JMS APIs, or at least Version 7.2.5 of the C, .NET, or Java RTO 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 don't 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 queue, 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 for the given durable queue, enter the following CONFIG command.

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

Where:

<size> is an integer value specifying the maximum message size (in bytes) permitted for the queue.

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

Configuring Max Redelivery Attempts

You can use the max-redelivery option to configure the maximum number of times the queue 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 dead message queue (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 queue can attempt to redeliver a message to a client, enter the following CONFIG command:

solace(configure/message-spool/queue)# 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 a Message Redelivery Delay

When client applications are consuming messages from an event broker, they may occasionally encounter conditions where they are temporarily unable to process a message. In this scenario, the application may rollback the transaction to force a redelivery of a message.

Redelivering the message immediately often does not help, as it does not allow sufficient time for the transient condition to be resolved. Configuring a message redelivery delay can help in this scenario, by suspending message delivery to the client following a transaction rollback, until a configured redelivery delay time has passed. You can also configure a multiplier to allow for exponential back-off of redelivery attempts.

When you configure a message redelivery delay, it applies only when the broker attempts to redeliver a message to a client following an application-initiated local transaction rollback. Other types of redelivery will occur without a delay.

Configuring a message redelivery delay is a Controlled Availability (CA) feature. Please contact Solace to find out if this feature is supported for your use case.

To configure a message redelivery delay, enter the following command:

solace(configure/message-spool/queue)# redelivery-delay

The CLI is now at a level where you can configure the initial interval, maximum interval, and delay interval multiplier the queue uses when it attempts to redeliver a message to a client following an application-initiated local transaction rollback.

  • To configure the initial interval, enter the following command:

    solace(.../message-spool/queue/redelivery-delay)# initial-interval <value>

    Where:

    <value> is an integer value specifying the delay between the first two delivery attempts, in milliseconds. The valid range of values is 1 to 3600000. The default is 1000.

    The no form of this command, no inital-interval, resets the value to the default.

  • To configure the maximum interval, enter the following command:

    solace(.../message-spool/queue/redelivery-delay)# max-interval <value>

    Where:

    <value> is an integer value specifying the maximum delay to be used between any two redelivery attempts, in milliseconds. The valid range of values is 1 to 10800000. The default is 64000.

    The no form of this command, no max-interval, resets the value to the default.

  • To configure the delay interval multiplier, enter the following command:

    solace(.../message-spool/queue/redelivery-delay)# multiplier <value>

    Where:

    <value> is a floating point value specifying the amount that each delay interval is multiplied by after each failed delivery attempt. The valid range of values is 1.00 to 5.00. The default is 2.00.

    The no form of this command, no multiplier, resets the value to the default.

To enable the message redelivery delay configuration, enter the following command:

solace(.../message-spool/queue/redelivery-delay)# no shutdown

To disable the message redelivery delay configuration, enter the following command:

solace(.../message-spool/queue/redelivery-delay)# shutdown

Configuring Message Redelivery

By default, the maximum number of times the queue can attempt to redeliver a message to a client is controlled by the max-redelivery command. For more information, see Configuring Max Redelivery Attempts.

You can instead disable this functionality. When message redelivery is disabled, a given message will only be attempted to be delivered from the queue once.

Disabling message redelivery is a Controlled Availability (CA) feature. Please contact Solace to find out if this feature is supported for your use case.

To disable message redelivery attempts, enter the following CONFIG command:

solace(configure/message-spool/queue)# no redelivery

To enable message redelivery attempts, enter the following CONFIG command.

solace(configure/message-spool/queue)# redelivery

Configuring Message Delivery Count

You can use the delivery-count option to enable or disable the delivery count property for messages. When enabled, each message sent from the queue to a consumer contains a property indicating whether this is the 1st, 2nd, ... or nth attempt to deliver the message to a consumer. By default, the delivery count is disabled.

The message count has the following behaviors:

  • For message browsers, the message count has the value that the next non-browser consumer will see. Browsing messages does not affect their delivery count.
  • In the case of a redundancy (HA) failover, message counts greater than 1 are reset to 2.

Enabling the message delivery count is a Controlled Availability (CA) feature. Please contact Solace to find out if this feature is supported for your use case.

To enable the delivery count for messages on the queue, enter the following CONFIG command:

solace(configure/message-spool/queue)# delivery-count

To disable the delivery count for messages, enter the following CONFIG command.

solace(configure/message-spool/queue)# no delivery-count

Configuring Delayed Delivery

By default, messages published to queues are immediately published to connected consumers. There are many use cases in which published messages must not be delivered to consumers immediately, but delivered only after a fixed delay. One example is a retry mechanism within a payment processing system. After receiving a customer order, you may want to implement a delivery delay to retry credit card transactions when the processing of the transaction fails for any reason. For more information, see Delayed Delivery.

You can use the delivery-delay option to configure a delivery delay for a queue, such that all messages destined to a queue are not eligible to be delivered for a fixed period of time.

If you are currently using dead message queues (DMQ) to implement a delivery delay, contact Solace for guidance on migrating your implementation to use the delivery-delay option instead.

To configure a delivery delay on the queue, enter the following CONFIG command:

solace(configure/message-spool/queue)# delivery-delay <delay>

Where:

<delay> is the delay, in seconds, to apply to messages arriving on the queue before the messages are eligible for delivery. The valid range is 0 to 4294967295. The default is 0.

The no version of this command, no delivery-delay, resets the delivery-delay value back to the default.

Configuring Max Spool Usage Values

To configure the maximum amount of message spool that the given queue may use, enter the following CONFIG command:

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

Where:

<size> is an integer value specifying the maximum amount of message spool disk space permitted for the queue in MB.

The no version of this command, no max-spool-usage, resets the permitted message spool usage quota available for use by the queue back to the default.

For information about the default values for this setting, see Maximum Spool Usage.

Setting Maximum Message Spool Usage to Zero

Setting the maximum message spool usage to 0 enables the Last Value Queue feature and disables endpoint quota checking. However, global quota checking and Message VPN quota checking are unaffected.

When this setting is 0 for a queue, the event broker enforces a queue depth of one by deleting older messages from the endpoint upon receiving new messages (that is, it stores only the last message spooled to it). If the queue is partitioned, each of its partitions holds the last message spooled to that partition.

For more information, see Last Value Queues.

Configuring Queue Owners

The queue owner has full unlimited permissions for the queue. That is, the owner can consume, delete, or modify topics in the queue. The ownership of a queue is established in the following manner:

  1. If a client application dynamically provisions a queue through a PubSub+ messaging API, the client username associated with the client is automatically given ownership of that queue.
  2. If a CLI user manually provisions a queue through the Solace CLI, no client username is automatically given ownership of that queue.
  3. Any CLI user with read-write or admin access to the Message VPN that the queue belongs to has full permissions on the queue (that is, management has ownership).

Client access to the durable message queue must first be disabled before assigning an owner. For more information, see Enabling / Disabling Client Access to Queues.

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

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

<owner> is the username of an existing client username account. Default owner is management.

The no version of this command, no owner, resets the owner of the queue back to the default.

Restrictions on client initiated deletions

  • Clients can't delete subscriptions on a queue if those subscriptions were added using CLI or SEMP by management users.
  • Clients can't delete a queue if the queue was created using CLI or SEMP by a management user.

Configuring Permissions for Non-Owner Clients

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

Client access to the durable message queue must first be disabled before queue permissions can be configured. For more information, see Enabling / Disabling Client Access to Queues.

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

Where:

no-access disallows access to the queue.

read-only provides clients with read-only access permission to messages spooled to the queue.

consume provides clients with read-only permission and the ability to delete messages from the queue.

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

delete provides clients with modify-topic permission and the ability to delete the queue. Note that clients cannot delete a queue 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 queue to none; that is, no access. A client access level of none is the default permission level.

Permission levels are ignored for client-usernames with Guaranteed Endpoint Permission Override enabled. For more information, see Enabling Endpoint Permission Overrides.

Receiving messages on topics that would otherwise be denied by clients' subscribe-topic ACLs

If a client binds to a queue that they do not own, they receive all the messages on the queue, including the messages that match topics that they would be denied for subscription to due to the assigned ACL. For example, if there is a queue subscribed to topic a/b, and a client successfully binds to that queue, then that client will receive all the messages on the queue, even if that client is subject to an ACL that prohibits a subscription to topic a/b.

Restrictions on client initiated subscription changes

  • Clients must have modify-topic permission set to add or remove a subscription from a queue.For more information, see Adding Topic Subscriptions to Queues.
  • Clients cannot delete subscriptions on a queue if management users added those subscriptions using CLI or SEMP.

Enabling Rejection of Low-Priority Messages

To protect against message congestion scenarios where such a large number of messages are published to a queue that system performance decreases, you can enable the queue to discard low-priority messages but continue to spool high-priority published messages. The queue can selectively discard low-priority messages only after the total number of low-priority and high-priority messages spooled exceeds the value set for the reject low-priority message limit.

By default, the reject low-priority message feature is not enabled for endpoints.

  • To avoid inadvertently discarding all low-priority messages, it's 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. For more information, see Configuring Reject Low-Priority Message Limits.
  • When this feature is enabled, the reject message to sender on discard option must also be enabled for the queue so that session events are sent to the publishing clients whenever messages are not enqueued on the queue and are discarded. For more information, see Configuring Message Discard Handling,

To enable the reject low-priority message feature for a queue, enter the following CONFIG command:

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

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

Assigning message priorities

Client applications can use the PubSub+ messaging APIs to assign message priorities through the Class of Service (COS) property.

Configuring Reject Low-Priority Message Limits

To configure a reject low-priority message limit for a queue, enter the following CONFIG command:

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

Where:

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

Configuring Message Discard Handling

The reject-msg-to-sender-on-discard option configures how a durable queue 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 queue
  • the published message exceeds the maximum message size allowed for the queue
  • the client published the message to a topic it has also subscribed to and has an active flow with "No Local Delivery"

If a 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 queue (this is the default): 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 PubSub+ APIs. PubSub+ APIs do not retransmit NACKed messages.
  • If the reject-msg-to-sender-on-discard option is not enabled for a queue: The ingress message is "silently" discarded (that is, it discards the message but returns an ACK 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 queue, enter the following CONFIG command:

solace(configure/message-spool/queue)# reject-msg-to-sender-on-discard [including-when-shutdown]

Where:

including-when-shutdown specifies to return NACKs to clients publishing messages topics if the endpoint has a matching subscription but is shutdown. Note that this parameter specifically targets messages published to topics because messages published to a queue are always NACKed when reject-msg-to-sender is enabled and the queue is shutdown.

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

Impact on transacted sessions

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, see Using Local Transactions for PubSub+ SMF APIs and Using Transacted Sessions for the PubSub+ JMS API.

Configuring Max Message TTLs

You can configure a maximum time-to-live (TTL) value for a durable endpoint so that received messages are provided with expiration value to limit how long they can remain on that durable 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 DMQ (if the publisher has flagged the message as DMQ-eligible).

Messages can also have a publisher-supplied TTL, which indicates how long the publisher considers a message to be valid. This differs from the maximum TTL for the endpoint in that the publisher TTL expiration starts when a message is published and counts down as the message passes through the network. If a message has both a publisher-assigned TTL and an endpoint-assigned maximum TTL, the event broker uses the minimum of the two TTL values when the message is in the endpoint.

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

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

Where:

<ttl> is maximum number of seconds that messages can stay on a queue that has the Respect TTL option enabled.

Conditions:

  • A max TTL value is only applied to messages when the Respect TTL option is enabled for the 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, queues associated with replication bridges, or queues associated with Config-Sync bridges.

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

Max TTL & Message VPN Bridges

Although max TTL values can be configured on queues associated with Message VPN bridges, it's recommended that you configure max TTLs on the endpoints that are the published messages' ultimate destinations to prevent messages from being discarded on the bridge queue when there are expectant downstream consumers.

Max TTL & Performance

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 TTLs

You can configure a queue 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. By default, the DMQ is set to ignore message TTL expiry times.

When a queue 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.

When a queue 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 durable queue to respect message TTLs, enter the following CONFIG command:

solace(configure/message-spool/queue)# respect-ttl

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

If a queue'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 of TTL violations.

Enforcing Whether to Respect Message Priority Values

You can configure a queue to either respect or ignore messages' priority values.

When a queue 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.

Partitioned queues do not respect message priority, even if they are configured to respect it.

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 shut down a queue before you can change whether it respects or ignores priority values.

To configure a durable queue to respect message priority values, enter the following CONFIG command:

solace(configure/message-spool/queue)# respect-message-priority

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

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

Configuring Partitioned Queues

A partitioned queue consists of a parent non-exclusive queue, along with a child queue for each partition. For more information, see Partitioned Queues.

Creating Queue Partitions

To create queue partitions for a non-exclusive queue in a given Message VPN, enter the following CONFIG commands:

solace(configure/message-spool/queue)# partition
solace(configure/message-spool/queue/partition)# count <num-partitions>

Where:

<num-partitions> specifies the number of partitions for the queue. The valid range depends on the maximum number of client connections the broker supports. The default value is 0 (that is, not partitioned). A partition count of 1 results in a partitioned queue with a parent queue and a single partition. If a queue has partitions, bound clients receive messages from individually assigned partitions instead of in a round-robin fashion.

The no version of this command no count, returns the value to the default, which removes all queue partitions and causes the queue to become a non-exclusive, non-partitioned queue. For more information, see Configuring Access Types.

If you change a queue from partitioned to non-partitioned or vice versa, the event broker unbinds all clients already bound to the queue. This ensures that the event broker and clients are consistently using (or not using) the semantics for partitioned queues. Note that any messages remaining in removed partitions are also removed.

If you change a queue from non-partitioned to partitioned, messages that are enqueued at the time of the change may get stuck because the event broker no longer delivers messages from the parent queue after the queue becomes partitioned. In this case, you can copy messages out of the parent queue.

We recommend that you ensure that messages are drained from the queue before changing the number of partitions. For more information, see Partition Scaling.

Partition scaling is service affecting. Ensure that you follow the exact procedures provided in Partition Scaling to add or remove partitions.

Configuring the Timers for Partition Rebalancing

When the number of clients drawing from a partitioned queue changes, partition rebalancing is triggered. For more information, see Partition Rebalancing.

When an event broker performs partition rebalancing, two timers are used: the rebalancing delay, and the maximum handoff timer. Depending on your deployment, you may want to change the duration of these timers.

Configuring the Rebalancing Delay

By default, event brokers wait five seconds before triggering a rebalance once it is required.

You can configure this to balance the needs of your consumer scaling strategy and stability of your consumer connections. Smaller values mean that client connects and disconnects are acted upon more quickly; larger values minimize the number of partition reassignments when clients are frequently, temporarily disconnected or when client disconnections/reconnections occur in groups (for example, with client autoscaling).

To configure the delay before a rebalance is started after it is triggered, enter the following CONFIG commands:

solace(configure/message-spool/queue/partition)# rebalance
solace(...ssage-spool/queue/partition/rebalance)# delay <seconds>

Where:

<seconds> specifies the delay (in seconds) before a rebalance is started after it is triggered. The valid range is 0 to 4294967295. The default is five seconds.

The no form of this command, no delay, returns the value to the default.

Configuring the Maximum Handoff Time

When partition rebalancing occurs, it may cause a handoff of partitions from one consumer to another. While handoffs are designed to be as unobtrusive as possible, remapping and scaling of partitions may cause application-level errors as the flow of messages belonging to one partition is moved from one consumer to another. For more information, see Partition Handoff.

By default, event brokers wait (pause message ingress) for a maximum of three seconds to allow messages to drain prior to handing off a partition while rebalancing. If there are no messages to be drained, the handoff proceeds immediately.

To configure the maximum time to wait before the event broker hands off a partition while rebalancing, enter the following CONFIG commands:

solace(configure/message-spool/queue/partition)# rebalance
solace(...ssage-spool/queue/partition/rebalance)# max-handoff-time <seconds>

Where:

<seconds> specifies the maximum time (in seconds) to wait before handing off a partition while rebalancing. The valid range is 0 to 4294967295. The default is three seconds.

The no form of this command, no max-handoff-time, returns the value to the default.

Monitoring Partitioned Queues

To display information about queue partitions, enter the following command:

show queue <name> [message-vpn <vpn-name>] partitions

Where:

<name> is the full name of the message queue, or part of the queue name with the wildcard character ? used to represent one character of the name, or the wildcard character * used to represent zero or more characters of the name, where entering only the wildcard character * for the name displays all message queues.

<vpn-name> is the name of the Message VPN the queue belongs to.

Example:

This example shows a queue with four partitions and several messages spooled in each partition.

solace(configure)# show queue test partitions

Name                                 : test
Message VPN                          : default
Partition Count                      : 4
  Operational                        : 4
Rebalance
  Delay (Seconds)                    : 5
  Max Handoff Time (Seconds)         : 3
Scaling Status                       : Ready
Rebalancing Status                   : Ready

ST(Status): UA(Unassigned), R(Ready), P(Paused), UB(Unbound)

     Queue Name                                                      Messages
Num  Assigned Client                                           ST     Spooled
---- --------------------------------------------------------- -- -----------
0    #pq/bff82b2e8c82d8c1/00000                                UA          12

1    #pq/bff82b2e8c82d8c1/00001                                UA          13

2    #pq/bff82b2e8c82d8c1/00002                                UA          13

3    #pq/bff82b2e8c82d8c1/00003                                UA          12

For a partitioned queue, the show queue command (without the partitions keyword) returns the number of spooled messages for the parent—this includes the total number of messages spooled in each partition plus any messages that were spooled to the parent queue before it became a partitioned queue.

Deleting Messages from Partitioned Queues

To delete messages that are spooled in a child queue, you must specify the name of the child queue in the delete-messages command. For example, to delete messages from partition 3 in the preceding example, run the following command:

solace(admin/message-spool)# delete-messages test #pq/bff82b2e8c82d8c1/00003

If you run the delete-messages command on the parent queue (that is, without specifying a partition), the event broker deletes any messages that were spooled directly to the parent queue before it became partitioned.

Adding Topic Subscriptions to Queues

To add a topic subscription to the given durable message queue so that Guaranteed messages published to those topics are also delivered to the queue, enter the following CONFIG command:

solace(configure/message-spool/queue)# subscription topic <topic>

Where:

<topic> is the name of the topic subscription to be added in the form a/b/c.

The no version of this command, no subscription topic, deletes the specified topic subscription from the durable queue.

Conditions:

  • Adding or deleting a topic subscription does not affect the messages that are already stored in the queue.
  • The subscription topic Queue CONFIG command and no subscription topic Queue CONFIG command can be entered multiple times to add or delete multiple topic subscriptions to the queue.
  • The queue subscriptions are constrained by the same limits put on per client subscriptions and the event broker-wide constraint of number of supported subscriptions.

Restrictions on subscription changes

  • Clients using PubSub+ Messaging APIs can't remove topic subscriptions from a queue that an administrator has added through CLI or SEMP.
  • To permit clients to add or remove subscriptions from a queue that have not been added by an administrator, a permission level of modify-topic or delete must be configured for the queue (refer to Configuring Permissions for Non-Owner Clients), or the clients must be assigned a client profile that has the guaranteed endpoint permission override enabled (refer to Allowing Clients to Create Guaranteed Endpoints).
  • Adding or removing a subscription from a queue is fully supported in a redundant event broker configuration. That is, topic subscriptions in queues can be managed on the active event broker and those subscriptions survive activity switches between event broker pairs.

Adding Topic Subscription Exceptions to Queues

To add a topic subscription exception to the given durable message queue so that Guaranteed messages published to those topics are not delivered to the queue, repeat the steps to add a subscription and add a leading "!" character to the topic name.

In other words, to add a topic subscription exception to the queue enter the following CONFIG command:

solace(configure/message-spool/queue)# subscription topic !<topic>

Where:

<topic> is the name of the topic subscription you want to exclude from the queue in the form a/b/c.

Subscription exceptions are enabled by default. If subscription exceptions are disabled, the leading "!" is treated as a literal character. For more information about enabling and disabling subscription exceptions, see System-Level Subscription Exception Configuration.

Enabling / Disabling Client Access to Queues

By default, clients are disabled from publishing and binding to queues.

To enable client access to the specified durable queue, enter the following CONFIG command:

solace(configure/message-spool/queue)# no shutdown [ingress | egress | full]

To disable client access to the specified durable queue, enter the following CONFIG command:

solace(configure/message-spool/queue)# shutdown [ingress | egress | full]

Where:

ingress specifies to enable or disable clients from publishing to the queue.

egress specifies to enable or disable clients from binding to the queue.

full specifies to enable or disable clients from publishing to the queue and binding to the queue.