Versioning

Overview

Versioning ensures compatibility between different SwiftMQ releases and takes place within the following areas:

  • SMQP protocol
  • SMQPR protocol
  • SMQPHA protocol
  • HA replication tunnel protocol
  • JMS
  • JNDI
  • Routing connections
  • Route exchange
  • Pub/sub subscription exchange
  • Management via SwiftMQ Explorer, CLI, CLI Admin API

SMQP Protocol

SMQP is the abbreviation of "SwiftMQ Protocol" and is used as the underlying protocol between JMS clients and a SwiftMQ router. The complete SMQP protocol stack is versioned. So far, it is possible to remove complete stacks out of swiftmq.jar once it expires in future. There is one non-versioned SMQP request to select the protocol stack which is used from JMS clients as the first request to negotiate the protocol version. Thereafter, a complete versioned protocol stack is used.

Specifying the SMQP Protocol Version

Since release 7.3.2 it is possible to specify a particular SMQP protocol version to connect to a SwiftMQ Universal Router. This is only necessary if it is required to connect with a higher versioned JMS client (e.g. CLI) to an older versioned SwiftMQ Universal Router, e.g. if the SwiftMQ Universal Router can't be upgraded due to internal reasons. To use most recent client-side features, the SMQP protocol version can be set with the following system property:

        -Dswiftmq.smqp.version=<version>

where "version" is one of the following:

  • 400
  • 500
  • 510
  • 600
  • 610
  • 630
  • 750

Version 750 is the latest version and default. The protocol version changes if there is a protocol change. For example, version 510 did change with SwiftMQ release 5.1.0. All further releases until 6.0.0 are using version 510 but also contain lower versioned protocol stacks. For example, a SwiftMQ Universal Router 5.2.5's default version is 510 but can also serve versions 500 and 400. A SwiftMQ Universal Router 7.3.2's default version is 630 but can also serve versions 610, 600, 510, 500 and 400.

SMQPR Protocol

SMQPR is the abbreviation of "SwiftMQ Protocol for Routing" and is used as the underlying protocol between SwiftMQ routers to exchange messages over routing connections. It uses also versioned protocol stacks and a non-versioned SMQPR request to negotiate the protocol version.

SMQPHA Protocol

SMQPHA is the abbreviation of "SwiftMQ Protocol for High Availability" and is used as the underlying protocol between ACTIVE and STANDBY HA instances of a SwiftMQ HA Router. It uses also versioned protocol stacks and a non-versioned SMQPHA request to negotiate the protocol version.

HA Replication Tunnel Protocol

HA replication tunnel protocol is used on top of a SMQPHA replication tunnel. The versioning takes place per tunnel. So it's possible to have different protocol versions per replication tunnel.

JMS

JMS clients and a SwiftMQ router are using SMQP to interact. All JMS client classes as well as all corresponding classes at the JMS Swiftlet of the router are versioned. The JMS Swiftlet provides multiple versions, where each version is completely separated from each other version. A JMS connection is created via a connection factory which is either obtained from JNDI or created the proprietary way. Both ways result in a versioned connection factory which launches a versioned connection object on the JMS client. The JMS client uses versioned SMQP to connect to a router, negotiate the version with the router which then launches a versioned connection by itself. Therefore, it is possible to connect a 4.0.0 and a 5.0.0 JMS client to the same 5.0.0 router, using different versioned connection classes on the router side.

JNDI

JNDI is realized on top of a JMS connection. Before the JNDI request is sent to the router, a versioned JMS connection will be established. Thereafter, JNDI requests are sent via internal JMS destinations. These JNDI requests are versioned as well. The JNDI Swiftlet provides sets of versioned request handlers, where each set is completely separated from each other.

The JMS Swiftlet registers connection factories within JNDI. It does this by registering a container under the given name, e.g. "QueueConnectionFactory". The container has a dedicated entry with a connection factory for every version the JMS Swiftlet provides. Each entry contains a factory name to create the connection factory. For example, if a JMS Swiftlet provides versions 4.0.0, 4.1.0 and 5.0.0, then the container has 3 entries. When a JMS client performs a JNDI lookup, the container is returned, the appropriate version entry is selected (e.g. if the client has 4.0.0 then the 4.0.0 entry is selected out of 4.0.0, 4.1.0, 5.0.0), and the connection factory is created from the factory with the name, specified in the entry. Thereafter, the connection factory is returned from the JNDI lookup.

Routing Connections

SwiftMQ Universal Routers are using SMQPR to interact. All connection classes are versioned and completely separated. During the connect, the appropriate version is negotiated and versioned routing connections are launched on each side. New releases will contain multiple versions and can therefore interact with older releases.

Route Exchange

After a versioned routing connection has been established, routes are exchanged between the corresponding routers. Routes are versioned and being converted to the version the corresponding router accepts.

Pub/Sub Subscription Exchange

Those notifications are exchanged between Topic Manager Swiftlets to ensure that pub/sub messages are sent to remote routers if they have at least one subscription for a particular topic. Notification exchange starts first after a route is known and continues on each appropriate event. The notifications are versioned and being converted to the version the corresponding Topic Manager Swiftlets accepts.

Management via SwiftMQ Explorer, CLI, CLI Admin API

A SwiftMQ administration tool and the corresponding Management Swiftlet of the particular router negotiate a protocol version during the connect. If the Management Swiftlet supports the requested protocol version, it loads the protocol stack and uses it for any further communication with that tool. Therefore, an administration tool is able to manage a router network containing routers with different protocol versions simultaneously.