Queues are the base for the Point-To-Point message model. This model is usually taken to implement server inbound queues. Queues are location dependent. They reside on a specific router, usually for a long time. Sending messages to a queue could be performed from every router in a network that has a route to the router where the queue is hosted. Receiving messages from a queue is limited to the queue's hosting router. It is not possible to create a QueueReceiver for a queue on a different router.
Usually a queue has one receiver that fetches and processes the messages. SwiftMQ permits to create multiple receivers per queue. With this approach a 'natural' round-robin scheduling takes place where each receiver fetches the next available message from the top of the queue. This means that a load balancing on the client side could be easily implemented by simply starting more client process instances to increase the message troughput.
Due to location dependency, a queue name must always be completely qualified to ensure correct message routing:
<queue>@<routername>
In exception to this rule, the initial definition of queues in the Queue Manager configuration must always be without the router name. This makes it easy to change it. For this reason it is suggested to define an JNDI alias for queues to avoid definitions of router names into JMS applications.
There is one predefined queue on each router for messages that cannot be routed to their destination queue because the queue is dropped while the message is travelling the router network. These messages become unroutable and will be forwarded to the queue "unroutable" on the specific router. To get this messages, a JMS application can create a QueueReceiver and send them again e. g. with a new destination.
The predefined queue "routerdlq" is the router's deadletter queue and serves as a destination for expired messages if the Queue Manager's job "Queue Cleanup DLQ" is used. See the Queue Manager Swiftlet documentation.
There is one predefined topic that is shared between JMS clients and internal SwiftMQ Swiftlets; the topic to broadcast JNDI lookups, the use of which is restricted to SwiftMQ's JNDI implementation. The topic name is "swiftmq.jndi". To use this topic, a publish-grant is needed. This could simply be done by defining this grant within the public group. For details have a look at the Authentication Swiftlet configuration.
In contrast to queues (PTP message model), topics are location independent. They are available on every router in a connected router network due to automatic broadcasts of local subscribers from every router to all connected routers in the network. In fact, one can publish or subscribe from any router in a router network if the authentication process on the specific local router was successful.
SwiftMQ provides the possibility to define topic hierarchies in the form <roottopic>.<subtopic>.<subsubtopic> etc.
Example:
iit.sales.EU
iit.sales.US
iit.projects.swiftmq.users
news.weather.forecasts
sports.formula1.MichaelSchumacher
Publishing and subscribing rules to nodes in a hierarchy:
As an extension to the normal topic node- and subnode-addressing scheme, SwiftMQ provides SQL-Like predicate topic addressing. So every specified subnode could be a SQL-Like predicate. A SQL-Like predicate could contain wildcards which match a single character (the underscore '_'), or any characters (the percent sign '%'). Escape character is '\'.
Example:
To address the topic iit.sales.US one can also write iit.s%s._S; to address all subnodes within the same hierarchy level on hierarchy iit concerning swiftmq the predicate is iit.%.swiftmq.
Root nodes cannot be addressed as a predicate; i. e. it is not possible to specify i%.%.swiftmq.
Predicate topics are normal topic destinations and are not available via JNDI lookups. To create a predicate topic, one has to use the createTopic() method from a TopicSession.
Example:
Topic allSwiftMQ = topicSession.createTopic("iit.%.swiftmq");
msg.setJMSDestination(allSwiftMQ);
publisher.publish(msg);
Access to predicate topics must be granted by the Authentication Swiftlet just like normal topics.
The JMS specification may be unclear concerning creation, reconnection, change and deletion of durable subscribers. So let's have a look at how it works in reality:
Creating a durable subscriber:
Reconnect to an existing durable subscriber:
Changing an existing durable subscriber:
Deleting an existing durable subscriber:
Durable subscribers are location dependent. They reside on a specific router and can only be accessed from that router on which they have been created.
Durable subscribers can be created and removed administratively via SwiftMQ Explorer or CLI.
To create a durable subscriber with SwiftMQ Explorer, select the node "Active Durable Topic Subscribers" of the Topic Manager Swiftlet's "Usage" folder. Right mouse click opens a popup menu:
Select "Create a new Entity":
The "Name" has to of <clientid>$<durablename>. "Bound To" will be set from SwiftMQ during the creation of the durable subscriber and contains its queue name. After pushing the "Create" button, the durable subscriber is created and can be used from JMS clients:
To remove an existing durable subscriber with SwiftMQ Explorer, select its entry and do a right mouse click. This opens up a popup menu. Select the only entry "Delete Entity" and the durable subscriber will be removed:
JMS provides the possibility to specify vendor specific message properties. These properties have the prefix JMS_<vendor>. SwiftMQ defines the following vendor properties:
| Property Name | Type | Content |
|---|---|---|
| JMS_SWIFTMQ_CID | String | Contains the client id of the message producer. |
| JMS_SWIFTMQ_UR_REASON | String | Contains the reason for unroutable messages. |
The SwiftMQ distribution contains a directory "samples" with various example programs. To use it, please consult the Readme.txt stored in the "samples" directory.