Queue Manager Swiftlet

Overview

The Queue Manager Swiftlet is responsible for the creation, management, and operation of all queues within a SwiftMQ router. It supports regular, temporary, composite, and clustered queues, handles message flow, queue state, and provides mechanisms for queue monitoring, maintenance, and administration.

Features

Queue Creation and Management

The Swiftlet manages all queue lifecycles, including creation, deletion, and runtime state (active/paused). Queues can be defined statically in the configuration or dynamically at runtime. Each queue can be individually configured for cache size, persistence, consumer mode, flow control, duplicate detection, and cleanup intervals. The Swiftlet also manages temporary queues, which are created on demand and automatically cleaned up.

Queue Controllers

Queue controllers allow the definition of default properties for groups of queues using SQL-LIKE predicates. This enables administrators to apply common settings (such as cache size or persistence mode) to multiple queues matching a pattern, simplifying configuration management.

Temporary Queues

Temporary queues are created with names following the pattern tmp$<sequence>-<startuptime>. They are non-persistent and automatically removed when no longer needed. Temporary queues are managed separately from regular queues and have their own queue controller configuration.

Configuration Example:

<swiftlet name="sys$queuemanager">
  <queues>
    <queue name="orders" cache-size="2000" persistence-mode="persistent"/>
  </queues>
</swiftlet>

Composite Queues

Composite queues provide a mechanism to fan out messages to multiple queues and/or topics based on configurable bindings. Each binding can specify a message selector, whether to generate a new message ID, whether to change the destination, and if it is a default delivery binding. Composite queues enable advanced routing and message distribution patterns within the router.

Queue and Topic Bindings

Bindings define the target queues or topics for message copies. Message selectors can be used to filter which messages are delivered to each binding. The default-delivery option ensures that messages not matching any other binding are still delivered.

Configuration Example:

<swiftlet name="sys$queuemanager">
  <composite-queues>
    <composite-queue name="mycomposite">
      <queue-bindings>
        <queue-binding name="queueA" message-selector="priority > 5"/>
        <queue-binding name="queueB" default-delivery="true"/>
      </queue-bindings>
      <topic-bindings>
        <topic-binding name="topic1"/>
      </topic-bindings>
    </composite-queue>
  </composite-queues>
</swiftlet>

Clustered Queues

Clustered queues allow multiple physical queues (across routers) to be grouped under a single logical queue name, providing load balancing and high availability. Message dispatching can be round-robin or based on message groups, ensuring message order for related messages. Clustered queues exchange metrics and state via a special cluster topic, enabling coordinated message delivery and redispatch across the cluster.

Message Grouping

Message grouping ensures that all messages with the same group property (e.g., JMSXGroupID) are delivered to the same physical queue within the cluster. Group expiration and cleanup intervals can be configured to manage group lifecycles.

Redispatch

If a queue in a clustered queue has no consumers but another queue in the cluster does, messages can be automatically redispatched to ensure timely delivery.

Configuration Example:

<swiftlet name="sys$queuemanager">
  <clustered-queues>
    <clustered-queue name="orders-cluster" message-group-enabled="true" message-group-property="JMSXGroupID"/>
  </clustered-queues>
</swiftlet>

Queue Monitoring and Metrics

The Swiftlet collects and exposes detailed metrics for each queue, including message rates, total produced/consumed, cache usage, and latency. These metrics are updated at a configurable interval and can be used for monitoring, alerting, and capacity planning.

Monitor Alert Thresholds

Each queue can be configured with a threshold for the number of messages, triggering alerts via the Monitor Swiftlet when exceeded.

Configuration Example:

<swiftlet name="sys$queuemanager" collect-interval="2000"/>

Queue Maintenance and Administration

A suite of administrative commands and scheduled jobs is provided for queue maintenance, including purging, moving, exporting/importing messages, and resetting counters. These can be invoked via the management interface or scheduled using the Scheduler Swiftlet.

Purge and Cleanup Jobs

Jobs can be defined to purge queues, move messages between queues, clean up expired messages, and move expired messages to the Dead Letter Queue (routerdlq). Jobs can target queues by name or pattern using SQL-LIKE predicates.

Queue Activation and Pause

Queues can be toggled between active (delivering messages to consumers) and paused states using the activate command or programmatically.

Duplicate Detection and Flow Control

Each queue supports duplicate message detection (based on message ID) and flow control to prevent overload. Duplicate detection can be enabled or disabled per queue, and the backlog size is configurable. Flow control is triggered when the queue size exceeds a threshold, introducing delays to producers.

Flow Control Parameters

Flow control is managed via the flowcontrol-start-queuesize and max-flowcontrol-delay parameters, which determine when and how much delay is applied to producers.

Internal Queue Naming

tpc$<roottopic> — Virtual queue for topic broker invocation
tmp$<sequence>-<startuptime> — Temporary queue for dynamic, short-lived use
<clientId>$<durableName> — Durable subscription queue for JMS durable topic subscribers
routerdlq — Dead Letter Queue for undeliverable or expired messages

Configuration Guide

Defining a Persistent Queue with Custom Cache Size

Use this scenario to create a queue named orders with increased cache size and persistent storage for reliable message delivery.

Edit the routerconfig.xml file.
Add a queue entry under the queues entity with the desired properties.

<swiftlet name="sys$queuemanager">
  <queues>
    <queue name="orders" cache-size="2000" persistence-mode="persistent"/>
  </queues>
</swiftlet>

Enabling Message Grouping on a Clustered Queue

Enable message grouping for a clustered queue to ensure all messages with the same group property are routed to the same physical queue.

Edit the routerconfig.xml file.
Add a clustered-queue entry with message-group-enabled set to true.

<swiftlet name="sys$queuemanager">
  <clustered-queues>
    <clustered-queue name="orders-cluster" message-group-enabled="true" message-group-property="JMSXGroupID"/>
  </clustered-queues>
</swiftlet>

Setting Up a Composite Queue for Message Fan-out

Configure a composite queue to deliver messages to multiple queues and topics based on selectors and delivery rules.

Edit the routerconfig.xml file.
Add a composite-queue entry with queue-bindings and topic-bindings as needed.

<swiftlet name="sys$queuemanager">
  <composite-queues>
    <composite-queue name="mycomposite">
      <queue-bindings>
        <queue-binding name="queueA" message-selector="priority > 5"/>
        <queue-binding name="queueB" default-delivery="true"/>
      </queue-bindings>
      <topic-bindings>
        <topic-binding name="topic1"/>
      </topic-bindings>
    </composite-queue>
  </composite-queues>
</swiftlet>

CLI Commands

activate

Description: Toggles active/pause delivery of messages to consumers.

Usage: activate <queue>

copy

Description: Copy messages.

Usage: copy <source> -queue|-topic <target> [(-selector <selector>)|(-index <start> <stop>)] [-maxlimit <nmsgs>]

export

Description: Export Messages

Usage: export <queuename> <routerdir> [-delete] [-selector <selector>]

import

Description: Import Messages

Usage: import <routerdir> <queuename> [-newid] [-delete] [-filter <regex>]

move

Description: Move messages.

Usage: move <source> -queue|-topic <target> [(-selector <selector>)|(-index <start> <stop>)] [-maxlimit <nmsgs>]

remove

Description: Remove message(s) either by message-key or by message index.

Usage: remove <queue> (<message-key>|*)|(-index <start> <stop>)

reset

Description: Resets the consumed/produced counter to zero

Usage: reset <queue>

view

Description: View Messages

Usage: view <queue> <start> (<stop>|*) [<selector>] [truncate <kb>]

Scheduler Jobs

Multi Queue Purger

Description: Purges multiple Queues

Queue Cleanup DLQ

Description: Moves expired Messages to Deadletter Queue

Queue Cleanup

Description: Cleanup expired Messages

Queue Mover

Description: Moves the Content of a Source Queue to a Target Queue

Queue Purger

Description: Purges a Queue

Queue Reset

Description: Resets produced/consumed counters

Configuration Reference

The top-level entity in routerconfig.xml is <swiftlet name="sys$queuemanager">.

`<swiftlet name="sys$queuemanager">` Properties

These properties are attributes of the <swiftlet name="sys$queuemanager"> entity.

Parameter	Type	Default	Mandatory	Reboot Required	Description
`collect-interval`	Long	`1000`	No	No	Interval for collecting the Number of Messages per Queue
`cluster-metric-interval`	Long	`10000`	No	No	Interval for sending metrics about clustered queues (min: 1000)
`max-flowcontrol-delay`	Long	`5000`	No	Yes	Maximum Flow Control Delay
`log-expired-messages`	Boolean	`false`	No	No	Log Expired Messages to the 'Warning' Log File
`log-duplicate-messages`	Boolean	`false`	No	No	Log Duplicate Messages to the 'Warning' Log File
`deliver-expired-messages`	Boolean	`false`	No	No	Deliver Expired Messages to Clients
`cluster-topic`	String	`swiftmq.cluster`	No	Yes	Cluster Message Exchange Topic
`multi-queue-transaction-global-lock`	Boolean	`false`	No	No	Use a global lock for multi Queue Transactions

<swiftlet name="sys$queuemanager" collect-interval="1000" cluster-metric-interval="10000" max-flowcontrol-delay="5000" log-expired-messages="false" log-duplicate-messages="false" deliver-expired-messages="false" cluster-topic="swiftmq.cluster" multi-queue-transaction-global-lock="false"/>

`<queue-controllers>` in `<swiftlet name="sys$queuemanager">`

Controllers for System Queues

Each <queue-controller> entry is identified by its name attribute (the System Queue Controller).

Parameter	Type	Default	Mandatory	Reboot Required	Description
`predicate`	String	—	Yes	No	Queue Name SQL-Like Predicate
`cache-size`	Integer	`500`	No	No	Message Queue Cache Size
`cache-size-bytes-kb`	Integer	`-1`	No	No	Message Queue Cache Size Bytes (KB)
`cleanup-interval`	Long	`120000`	No	No	Interval to check for expired Messages
`flowcontrol-start-queuesize`	Integer	`400`	No	No	Flow Control starts at this Queue Size
`max-messages`	Integer	`-1`	No	No	Max. Messages for this Queue
`persistence-mode`	String	`as_message`	No	No	Persistence Mode of this Queue (choices: `as_message`, `persistent`, `non_persistent`)
`consumer-mode`	String	`shared`	No	No	Consumer Mode (choices: `shared`, `exclusive`, `activestandby`)
`duplicate-detection-enabled`	Boolean	`true`	No	No	Enables/Diables Duplicate Message Detection
`duplicate-detection-backlog-size`	Integer	`2000`	No	No	Size of the Backlog for Duplicate Message Detection
`monitor-alert-threshold`	Integer	`-1`	No	No	Threshold in Number of Messages after which the Monitor Swiftlet sends a Queue Monitor Alert

<swiftlet name="sys$queuemanager">
  <queue-controllers>
    <queue-controller name="..." predicate="..."/>
  </queue-controllers>
</swiftlet>

`<clustered-queues>` in `<swiftlet name="sys$queuemanager">`

Clustered Queues

Each <clustered-queue> entry is identified by its name attribute (the Clustered Queue).

Parameter	Type	Default	Mandatory	Reboot Required	Description
`message-group-enabled`	Boolean	`false`	No	No	Enables/Diables grouping of Messages
`message-group-property`	String	`JMSXGroupID`	No	No	Name of Property to group Messages
`message-group-expiration`	Long	`-1`	No	No	Time (ms) after the last occurance after which a message group expires
`message-group-expiration-cleanup-interval`	Long	`-1`	No	No	Interval (ms) in which message groups are checked for expiration

<swiftlet name="sys$queuemanager">
  <clustered-queues>
    <clustered-queue name="..."/>
  </clustered-queues>
</swiftlet>

`<queue-bindings>` in `<clustered-queues>`

Queue Bindings

Each <queue-binding> entry is identified by its name attribute (the Queue Binding).

Parameter	Type	Default	Mandatory	Reboot Required	Description
`redispatch-enabled`	Boolean	`true`	No	No	Enables/Diables Redispatch of Messages if no Consumer is attached

<swiftlet name="sys$queuemanager">
  <clustered-queues>
    <clustered-queue name="...">
      <queue-bindings>
        <queue-binding name="..."/>
      </queue-bindings>
    </clustered-queue>
  </clustered-queues>
</swiftlet>

`<composite-queues>` in `<swiftlet name="sys$queuemanager">`

Composite Queues

Each <composite-queue> entry is identified by its name attribute (the Composite Queue).

<swiftlet name="sys$queuemanager">
  <composite-queues>
    <composite-queue name="..."/>
  </composite-queues>
</swiftlet>

`<queue-bindings>` in `<composite-queues>`

Queue Bindings

Each <queue-binding> entry is identified by its name attribute (the Queue Binding).

Parameter	Type	Default	Mandatory	Reboot Required	Description
`message-selector`	String	—	No	No	Optional Selector to filter messages for this Binding
`generate-new-message-id`	Boolean	`false`	No	No	Generates a new Message Id for this Binding's Message Copies
`change-destination`	Boolean	`false`	No	No	Changes the JMS Destination of Message Copies to the Bindung Queue
`default-delivery`	Boolean	`false`	No	No	A defaut delivery gets the message if no other binding matches.

<swiftlet name="sys$queuemanager">
  <composite-queues>
    <composite-queue name="...">
      <queue-bindings>
        <queue-binding name="..."/>
      </queue-bindings>
    </composite-queue>
  </composite-queues>
</swiftlet>

`<topic-bindings>` in `<composite-queues>`

Topic Bindings

Each <topic-binding> entry is identified by its name attribute (the Topic Binding).

Parameter	Type	Default	Mandatory	Reboot Required	Description
`message-selector`	String	—	No	No	Optional Selector to filter messages for this Binding
`generate-new-message-id`	Boolean	`false`	No	No	Generates a new Message Id for this Binding's Message Copies
`default-delivery`	Boolean	`false`	No	No	A defaut delivery gets the message if no other binding matches.

<swiftlet name="sys$queuemanager">
  <composite-queues>
    <composite-queue name="...">
      <topic-bindings>
        <topic-binding name="..."/>
      </topic-bindings>
    </composite-queue>
  </composite-queues>
</swiftlet>

`<queues>` in `<swiftlet name="sys$queuemanager">`

Queue Definitions

Each <queue> entry is identified by its name attribute (the Queue).

Parameter	Type	Default	Mandatory	Reboot Required	Description
`cache-size`	Integer	`500`	No	No	Message Queue Cache Size
`cache-size-bytes-kb`	Integer	`-1`	No	No	Message Queue Cache Size Bytes (KB)
`cleanup-interval`	Long	`120000`	No	No	Interval to check for expired Messages
`max-messages`	Integer	`-1`	No	No	Max. Messages for this Queue
`persistence-mode`	String	`as_message`	No	No	Persistence Mode of this Queue (choices: `as_message`, `persistent`, `non_persistent`)
`consumer-mode`	String	`shared`	No	No	Consumer Mode (choices: `shared`, `exclusive`, `activestandby`)
`flowcontrol-start-queuesize`	Integer	`400`	No	No	Flow Control starts at this Queue Size
`duplicate-detection-enabled`	Boolean	`true`	No	No	Enables/Diables Duplicate Message Detection
`duplicate-detection-backlog-size`	Integer	`2000`	No	No	Size of the Backlog for Duplicate Message Detection
`monitor-alert-threshold`	Integer	`-1`	No	No	Threshold in Number of Messages after which the Monitor Swiftlet sends a Queue Monitor Alert

<swiftlet name="sys$queuemanager">
  <queues>
    <queue name="..."/>
  </queues>
</swiftlet>

Changelog

13.2.2 (2026-02-26)

MessageQueue: removed duplicate listener registration

13.2.0 (2025-11-03)

Exporter.store(): fixed boundary condition; Modified Importer

13.0.2 (2024-05-06)

Modified MessageQueue

Queue Manager Swiftlet

Overview

Features

Queue Creation and Management

Queue Controllers

Temporary Queues

Composite Queues

Queue and Topic Bindings

Clustered Queues

Message Grouping

Redispatch

Queue Monitoring and Metrics

Monitor Alert Thresholds

Queue Maintenance and Administration

Purge and Cleanup Jobs

Queue Activation and Pause

Duplicate Detection and Flow Control

Flow Control Parameters

Internal Queue Naming

Configuration Guide

Defining a Persistent Queue with Custom Cache Size

Enabling Message Grouping on a Clustered Queue

Setting Up a Composite Queue for Message Fan-out

CLI Commands

activate

copy

export

import

move

remove

reset

view

Scheduler Jobs

Multi Queue Purger

Queue Cleanup DLQ

Queue Cleanup

Queue Mover

Queue Purger

Queue Reset

Configuration Reference

<swiftlet name="sys$queuemanager"> Properties

<queue-controllers> in <swiftlet name="sys$queuemanager">

<clustered-queues> in <swiftlet name="sys$queuemanager">

<queue-bindings> in <clustered-queues>

<composite-queues> in <swiftlet name="sys$queuemanager">

<queue-bindings> in <composite-queues>

<topic-bindings> in <composite-queues>

<queues> in <swiftlet name="sys$queuemanager">

Changelog

13.2.2 (2026-02-26)

13.2.0 (2025-11-03)

13.0.2 (2024-05-06)

Related Documents

`<swiftlet name="sys$queuemanager">` Properties

`<queue-controllers>` in `<swiftlet name="sys$queuemanager">`

`<clustered-queues>` in `<swiftlet name="sys$queuemanager">`

`<queue-bindings>` in `<clustered-queues>`

`<composite-queues>` in `<swiftlet name="sys$queuemanager">`

`<queue-bindings>` in `<composite-queues>`

`<topic-bindings>` in `<composite-queues>`

`<queues>` in `<swiftlet name="sys$queuemanager">`