JMS Swiftlet

JMS Implementation

The JMS Swiftlet implements the JMS 1.1 specification.

Queue Location Dependency

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.

Multiple Queue Receivers

Usually, a queue has one receiver that fetches and processes the messages. SwiftMQ permits the creation of 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 throughput.

Queue Names

Due to location dependency, a queue name must always be completely qualified to ensure correct message routing:

  <queue>@<routername>

An 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 a JNDI alias for queues to avoid definitions of router names in JMS applications.

Predefined Queue unrouteable

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 traveling the router network. These messages become unrouteable and will be forwarded to the queue unrouteable on the specific router. To get these messages, a JMS application can create a QueueReceiver and send them again e. g. with a new destination.

Predefined Queue routerdlq

The predefined queue routerdlq is the router's dead-letter 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.

Predefined Topic swiftmq.jndi

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.

Topic Location Independency

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.

Topic Hierarchy

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
Copy

Publishing and subscribing rules to nodes in a hierarchy:

• Selecting a specific node in a topic hierarchy publishes messages to the addressed node and all concerning sub-nodes. Example: publishing to node iit.sales send the messages also to iit.sales, iit.sales.US, iit.sales.EU.

• Subscribing to a specific node in a topic hierarchy means receiving all messages addressed to this node and all parent and sub-nodes. Example: subscribing to iit.sales.US one receives all messages published in iit, iit.sales, and iit.sales.US; subscribing to iit.sales one receives all messages published in iit, iit.sales, iit.sales.US, iit.sales.EU, but you don't receive the messages published in the iit.projects hierarchy.

• A subscriber receives a message only once, regardless of the number of topics his subscription matches.

SQL-Like Predicate Topic Addressing

As an extension to the normal topic node- and subnode-addressing scheme, SwiftMQ provides SQL-Like predicate topic addresses. So every specified subnode could be a SQL-Like predicate. A SQL-Like predicate could contain wildcards that match a single character (the underscore '_'), or any characters (the percent sign '%'). The 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.

Durable Subscribers

Durable Subscribers (Programmatically)

The JMS specification may be unclear concerning the creation, reconnection, change, and deletion of durable subscribers. So let's have a look at how it works in reality:

Creating a durable subscriber:

• A valid client id must be set with setClientID() as the first method call after creating a connection or the client id has to be preset within the connection factory.

• A TopicSession must be created.

• Choose one of the createDurableSubscriber() methods.

• The durable subscriber is now in place and receives all the messages addressed to this topic.

Reconnect to an existing durable subscriber:

• Same procedure as above; supply the same parameters to createDurableSubscriber().

Changing an existing durable subscriber:

• Same procedure as above, but supply different parameters on createDurableSubriber() (except the durable subscriber name, which must match, otherwise a new one is created).

• The durable subscriber will be dropped with all content and re-created with the new parameters.

Deleting an existing durable subscriber:

• A valid client id must be set with setClientID() as the first method call after creating a connection or the client id has to be preset within the connection factory.

• A TopicSession must be created.

• The unsubscribe() method must be called with the name of the durable subscriber.

• The durable subscriber will be dropped with all content.

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 (Administratively)

Durable subscribers can be created and removed administratively via SwiftMQ Explorer App or CLI.

To create a durable subscriber with SwiftMQ Explorer App, select the node Active Durable Topic Subscribers of the Topic Manager Swiftlet's Usage folder:

Click on 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 by JMS clients:

To remove an existing durable subscriber with SwiftMQ Explorer, select its entry and click on Delete Entity and the durable subscriber will be removed:

Vendor Message Properties

JMS provides the possibility to specify vendor-specific message properties. These properties have the prefix JMS_<vendor>. SwiftMQ defines the following vendor properties:

JMS Examples

The SwiftMQ distribution contains a directory "samples" with various example programs. To use it, please consult the Readme.txt stored in the "samples" directory.

Thread Pools

The JMS Swiftlet uses the following thread pools:

• jms.connection

• jms.session

jms.connection

This thread pool is shared from all JMS connections at the router side and used for outbound writes from the router to JMS clients. These outbound writes are actually very short running tasks and a single thread of thread pool jms.connection can handle hundreds of connections. However, if there are slow network connections or if large messages are being transferred, the thread blocks until the outbound write have been completed and other writes are stacked up and have to wait. The default setting for this pool is min-threads=5, max-threads=5. It ensures that there are always free threads, even when the above conditions occur. The max-threads attribute should be increased when all threads of this pool are continuously busy.

jms.session

This thread pool is shared from all JMS sessions on the router side. In fact, all JMS work will be done from this pool. The work is scheduled as a so-called async task that is dispatched into this pool. These tasks are actually short running so a thread from this pool will not block. The only exceptions are persistent operations, e.g. large messages stored via the JDBC Store Swiftlet. This can take time and a thread will block until the operation has been finished. The default setting for this pool is min-threads=5, max-threads=5. It ensures that there are always free threads, even when the above conditions occur. The max-threads attribute should be increased when all threads of this pool are continuously busy.

Configuration

The configuration of the JMS Swiftlet is defined within the element

      <swiftlet name="sys$jms" .../>

of the router's configuration file.

Attributes of Element "swiftlet"

Definition

Values

Element List "intravm-connection-factories", Parent Element: "swiftlet"

IntraVM Connection Factories. This element list contains zero or more "intravm-connection-factory" elements with this template definition:

Definition

Values

Element List "listeners", Parent Element: "swiftlet"

Listener Definitions. This element list contains zero or more "listener" elements with this template definition:

Definition

Values

Element List "host-access-list", Parent Element: "listener"

Host Access List. This element list contains zero or more "host-access-entry" elements with this template definition:

Definition

Element List "connection-factories", Parent Element: "listener"

Connection Factories. This element list contains zero or more "connection-factory" elements with this template definition:

Definition

Values

Element List "usage", Parent Element: "swiftlet"

Active JMS Connections. This element list contains zero or more "usage" elements with this template definition:

Definition

Values

Element List "tempqueues", Parent Element: "usage"

Temporary Queues created by this Connection. This element list contains zero or more "tempqueue" elements with this template definition:

Definition

Element List "sessions", Parent Element: "usage"

JMS Sessions created by this Connection. This element list contains zero or more "tempqueue" elements with this template definition:

Definition

Values

Element List "receiver", Parent Element: "tempqueue"

Queue Receivers created by this Session. This element list contains zero or more "receiver" elements with this template definition:

Definition

Values

Element List "browser", Parent Element: "tempqueue"

Queue Browsers created by this Session. This element list contains zero or more "browser" elements with this template definition:

Definition

Values

Element List "sender", Parent Element: "tempqueue"

Queue Senders created by this Session. This element list contains zero or more "sender" elements with this template definition:

Definition

Values

Element List "publisher", Parent Element: "tempqueue"

Topic Publishers created by this Session. This element list contains zero or more "publisher" elements with this template definition:

Definition

Values

Element List "durables", Parent Element: "tempqueue"

Durable Topic Subscriber created by this Session. This element list contains zero or more "durables" elements with this template definition:

Definition

Values

Element List "subscriber", Parent Element: "tempqueue"

Topic Subscriber created by this Session. This element list contains zero or more "subscriber" elements with this template definition:

Definition

Values