Queue Manager Swiftlet

Overview

The Queue Manager Swiftlet is responsible for managing all queue-related operations within the SwiftMQ router, including the creation, deletion, and maintenance of queues. It provides advanced queue types such as regular, temporary, clustered, and composite queues, and handles message delivery, flow control, duplicate detection, and queue metrics. The Swiftlet also exposes management commands and jobs for queue administration, monitoring, and maintenance.

Features

Queue Definition and Management

The Queue Manager Swiftlet allows you to define, configure, and manage multiple types of queues. Regular queues are defined under the queues entity, with configurable properties such as cache size, persistence mode, flow control, and duplicate detection. Temporary queues are created automatically for temporary use and have a distinct naming pattern. System queues, such as the dead letter queue (DLQ), are managed internally but can be customized via queue controllers. The Swiftlet also supports dynamic queue creation and deletion at runtime, with all queue operations being subject to authentication and authorization checks.

Queue Controllers

Queue controllers provide default configuration templates for system queues and temporary queues. They use SQL-LIKE predicates to match queue names and assign properties such as cache size, persistence mode, and flow control. This mechanism ensures that system and temporary queues are created with appropriate settings even if not explicitly defined in the queues list.

Temporary Queues

Temporary queues are automatically created with names following the pattern tmp$-. These queues are non-persistent by default and are deleted automatically when no longer needed. Their configuration is controlled via a dedicated queue controller with a predicate matching tmp$%.

Configuration Example:

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

Clustered Queues

Clustered queues allow you to aggregate multiple local queues into a single logical queue for load balancing and high availability across a SwiftMQ cluster. Messages sent to a clustered queue are distributed to bound local queues according to a dispatch policy, such as round-robin or message group-based dispatch. Clustered queues can optionally enable message grouping, ensuring that all messages with the same group property are routed to the same underlying queue. Clustered queues also support redispatch: if a bound queue has no consumer but another router in the cluster does, messages can be moved to where they can be consumed.

Message Grouping

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

Queue Bindings and Redispatch

Clustered queues bind to one or more local queues. Each binding can enable or disable redispatch, which controls whether messages are moved to other routers if no consumer is present locally. Redispatch is managed by the RedispatcherController and is triggered by cluster metrics.

Configuration Example:

<swiftlet name="sys$queuemanager">
  <clustered-queues>
    <clustered-queue name="clustered_orders" message-group-enabled="true" message-group-property="JMSXGroupID">
      <queue-bindings>
        <queue-binding name="orders1" redispatch-enabled="true"/>
        <queue-binding name="orders2" redispatch-enabled="true"/>
      </queue-bindings>
    </clustered-queue>
  </clustered-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, control whether a new message ID is generated, and optionally change the destination. Composite queues support both queue and topic bindings, and can designate a default delivery binding to receive messages not matching any selector. This enables powerful routing and filtering scenarios within the router.

Queue and Topic Bindings

Bindings can be defined for both queues and topics. Each binding can filter messages using a JMS selector, and can be configured to generate new message IDs or change the destination to the binding's queue or topic.

Default Delivery

A binding can be marked as default-delivery, ensuring that messages not matching any other binding are still delivered to at least one destination.

Configuration Example:

<swiftlet name="sys$queuemanager">
  <composite-queues>
    <composite-queue name="fanout">
      <queue-bindings>
        <queue-binding name="queueA" message-selector="priority = 'high'"/>
        <queue-binding name="queueB" default-delivery="true"/>
      </queue-bindings>
      <topic-bindings>
        <topic-binding name="alerts"/>
      </topic-bindings>
    </composite-queue>
  </composite-queues>
</swiftlet>

Queue Metrics and Monitoring

The Swiftlet collects and exposes a wide range of metrics for each queue, including message counts, consumption and production rates, total consumed and produced messages, and average message latency. These metrics are updated at a configurable interval and can be accessed via the management interface. For clustered queues, metrics are exchanged between routers to coordinate redispatch and load balancing.

Cluster Metrics Exchange

Metrics for clustered queues are published to the cluster topic (default swiftmq.cluster) at a configurable interval, allowing routers to make informed decisions about redispatch and load distribution.

Configuration Example:

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

Flow Control and Duplicate Detection

Each queue supports flow control to prevent overload by introducing delays when the queue size exceeds a configured threshold. The maximum delay and start queue size for flow control are configurable per queue. Duplicate detection can be enabled to prevent the same message from being enqueued multiple times, using a configurable backlog size for tracking recent message IDs.

Configuration Example:

<swiftlet name="sys$queuemanager">
  <queues>
    <queue name="orders" flowcontrol-start-queuesize="1000" duplicate-detection-enabled="true" duplicate-detection-backlog-size="5000"/>
  </queues>
</swiftlet>

Queue Administration Commands and Jobs

The Swiftlet provides a set of management commands and scheduled jobs for queue administration. Commands include toggling queue delivery (activate), viewing messages, exporting/importing messages, copying/moving messages between queues, removing messages, and resetting counters. Jobs can be scheduled for purging queues, cleaning up expired messages, moving messages between queues, and resetting counters across multiple queues using SQL-LIKE predicates.

Purge and Cleanup Jobs

Jobs such as Queue Purger, Queue Cleanup, and Queue Cleanup DLQ can be scheduled to remove all messages, clean up expired messages, or move expired messages to the dead letter queue, respectively. These jobs support SQL-LIKE predicates to target multiple queues.

Bulk Operations

Jobs like Multi Queue Purger and Queue Mover enable bulk operations across multiple queues, supporting optional message selectors for fine-grained control.

Internal Queue Naming

tmp$<sequence>-<startuptime> — Temporary queue created for client sessions or internal use. The name includes a sequence number and the router's startup timestamp.
tpc$<roottopic> — Virtual queue for topic broker invocation, one per root topic.
routerdlq — Dead letter queue for undeliverable or expired messages.

Configuration Guide

Defining a Persistent Queue with Custom Flow Control

Use this scenario when you need a queue that stores messages persistently and applies flow control when the queue size exceeds a threshold.

Add a queue definition under the queues entity.
Set persistence-mode to persistent.
Set flowcontrol-start-queuesize to the desired threshold.

<swiftlet name="sys$queuemanager">
  <queues>
    <queue name="orders" persistence-mode="persistent" flowcontrol-start-queuesize="1000"/>
  </queues>
</swiftlet>

Enabling Message Grouping on a Clustered Queue

Use this scenario to ensure that all messages with the same group property are delivered to the same physical queue within a clustered queue.

Define a clustered-queue under clustered-queues.
Set message-group-enabled to true.
Optionally set message-group-property and expiration settings.

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

Creating a Composite Queue for Fan-out Routing

Use this scenario to route messages from a single composite queue to multiple queues and topics, optionally using selectors.

Define a composite-queue under composite-queues.
Add queue-binding and topic-binding elements as needed.
Configure selectors and default-delivery as required.

<swiftlet name="sys$queuemanager">
  <composite-queues>
    <composite-queue name="fanout">
      <queue-bindings>
        <queue-binding name="queueA" message-selector="priority = 'high'"/>
        <queue-binding name="queueB" default-delivery="true"/>
      </queue-bindings>
      <topic-bindings>
        <topic-binding name="alerts"/>
      </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 Definition and Management

Queue Controllers

Temporary Queues

Clustered Queues

Message Grouping

Queue Bindings and Redispatch

Composite Queues

Queue and Topic Bindings

Default Delivery

Queue Metrics and Monitoring

Cluster Metrics Exchange

Flow Control and Duplicate Detection

Queue Administration Commands and Jobs

Purge and Cleanup Jobs

Bulk Operations

Internal Queue Naming

Configuration Guide

Defining a Persistent Queue with Custom Flow Control

Enabling Message Grouping on a Clustered Queue

Creating a Composite Queue for Fan-out Routing

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">`