JNDI Swiftlet

Overview

The JNDI Swiftlet provides a JNDI implementation to a Federated SwiftMQ Router Network to store and retrieve JMS administered objects.

The registration takes automatically place by the JMS Swiftlet (connection factories), the Queue Manager Swiftlet (queues), and the Topic Manager Swiftlet (topics) as soon as these resources are declared.

Lookup Implementation

SwiftMQ implements JNDI via a JMS Connection. Each Context.lookup() is translated into a request message that is sent to queue sys$jndi of the connected router. The local JNDI Swiftlet receives this request and replies with the requested JNDI object in case the object with this name is registered at the local router. This guarantees that a lookup request is first served from the local JNDI Swiftlet. If the requested object is not found, the local JNDI Swiftlet forwards the request to topic swiftmq.jndi so all other JNDI Swiftlet can now serve the lookup request, if possible.

JNDI Aliases

There is the possibility to define any aliases via the JNDI Swiftlet configuration and to map these to registered JNDI objects. Through this, the JMS clients become independent of queue locations.

For example, if a queue exists with the name mailout@router4 and an alias mailqueue is defined hereto which is then used by the JMS client during the JNDI lookup, the queue may be displaced to other routers without changing the JMS clients which access it.

Static Remote Queues

In principle, SwiftMQ's JNDI implementation is structured dynamically. Every local router got its registrations, receives lookup requests, and, if an object is saved by its name, gives this back to the client.

Problems may arise if a remote router is disconnected, but a static route exists to this router. In this case, one may send it to the router (this is stored until he is reconnected, store-and-forward), but the queue object may not be requested by JNDI. That way, only the createQueue() method would rest at the client to address the remote queue.

To solve this problem, static remote queues may be defined in a local JNDI Swiftlet. Static remote queues are queue objects, which means addresses, which are restored on a JNDI lookup.

JNDI Replication

The JNDI Swiftlet provides the opportunity to replicate its JNDI content into external JNDI servers as well. Several of those replications can be defined. Before such replications can be defined, the resp. JNDI implementation classes have to be in the system classpath of the router because the JNDI uses the system class loader to load the InitialContext class.

Once a JNDI replication is configured, it can be enabled (default is disabled). All registered JNDI objects (including JNDI aliases) of this router are then replicated into the foreign JNDI tree below the given context (default is java:/comp/env/jms). To ensure the foreign JNDI is up and running, a JNDI replication uses a keepalive mechanism to check that. On each keepalive interval, configured by the attribute keepalive-interval, the replication component performs a JNDI lookup on the name, configured by the attribute keepalive-lookup-name. It doesn't matter which name you specify here, since a NameNotFoundException is taken as ok; the foreign JNDI is up. All other exceptions are taken as the foreign JNDI is down. The replication component then tries to reconnect. Once a connection can be re-established, the whole JNDI content is replicated again.

To replicate into an LDAP server, make sure that the attribute name-prefix contains the prefix cn=. The prefix will be used during bind and unbind operations.

It is recommended to enable the jndi trace space in the Trace Swiftlet during the configuration to see what's going on during the replication.

Configuration

The configuration of the JNDI Swiftlet is defined within the element

      <swiftlet name=`sys$jndi` .../>

of the router's configuration file.

Element List "jndi-replications", Parent Element: "swiftlet"

JNDI Replication Definitions. This element list contains zero or more "jndi-replication" elements with this template definition:

Definition

Values

Element List "environment-properties", Parent Element: "jndi-replication"

Environment Properties. This element list contains zero or more "environment-property" elements with this template definition:

Definition

Values

Element List "aliases", Parent Element: "swiftlet"

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

Definition

Values

Element List "remote-queues", Parent Element: "swiftlet"

Remote Queue Definitions. This element list contains zero or more "remote-queue" elements with this template definition:

Definition

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

Registered JNDI Objects. This element list contains zero or more "usage" elements with this template definition:

Definition

Values