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.
SwiftMQ implements JNDI via a JMS Connection. Each
translated into a request message that is send to queue
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.
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 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 it's 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 to the router
(this is stored until he is reconnected, store-and-forward), but the
according queue object may not be requested by JNDI. That way, only the
createQueue() method would rest at the client to address the remote
To solve this problem, static remote queues may be defined in a local JNDI Swiftlet. Static remote queues are queue objects, that means addresses, which are restored on a JNDI lookup.
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 into 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
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 a 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.
The configuration of the JNDI Swiftlet is defined within the element
<swiftlet name=`sys$jndi` .../>
of the router's configuration file. One can use the SwiftMQ Exlorer or CLI for configuration as well. They both save into that 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:
|name||java.lang.String||Yes||Name of this JNDI Replication|
|keepalive-lookup-name||java.lang.String||Yes||Name to use for Lookup during Keep Alive|
|name-prefix||java.lang.String||No||For LDAP you specify cn= here|
Element List "environment-properties", Parent Element: "jndi-replication"
Environment Properties. This element list contains zero or more "environment-property" elements with this template definition:
|name||java.lang.String||Yes||Name of this Environment Property|
Element List "aliases", Parent Element: "swiftlet"
Alias Definitions. This element list contains zero or more "alias" elements with this template definition:
|name||java.lang.String||Yes||Name of this Alias|
|map-to||java.lang.String||No||Mapping to generic Name|
Element List "remote-queues", Parent Element: "swiftlet"
Remote Queue Definitions. This element list contains zero or more "remote-queue" elements with this template definition:
|name||java.lang.String||Yes||Name of this Remote Queue|
Element List "usage", Parent Element: "swiftlet"
Registered JNDI Objects. This element list contains zero or more "usage" elements with this template definition:
|name||java.lang.String||Yes||Name of this Registered JNDI Object|
|classname||java.lang.String||No||Class Name of the registered JNDI Object|