Skip to content

JNDI Swiftlet

Overview

The JNDI Swiftlet provides Java Naming and Directory Interface (JNDI) services within the SwiftMQ router. It enables registration, lookup, and replication of JMS destinations (queues and topics) and other objects in a distributed, cluster-aware manner. The Swiftlet supports integration with external JNDI servers and allows for flexible aliasing and replication configurations.

Features

JNDI Object Registration and Lookup

The JNDI Swiftlet maintains a registry of named objects, primarily JMS queues and topics, which can be registered and looked up by clients or other Swiftlets. Objects are stored in-memory and can be dynamically added or removed. Registration is performed via internal APIs or through JNDI protocol requests received over dedicated queues and topics. Lookup requests are handled by the Swiftlet and, if the object is not found locally, can be forwarded to other routers via topic-based communication. The registry supports both direct object names and aliases, enabling flexible naming schemes.

Alias Support

Aliases allow mapping alternative names to registered JNDI objects. Each alias maps to a generic name, and lookups using the alias will resolve to the target object. Aliases are managed via configuration and can be added or removed at runtime. When an alias is created or removed, the Swiftlet ensures that any external JNDI replications are updated accordingly.

Static Remote Queue Registration

The Swiftlet can pre-register remote queues in the JNDI registry. Each remote queue is identified by a name in the format <queue>@<router>. These static registrations are useful for making remote destinations available for lookup and binding in distributed environments.

Configuration Example:

<swiftlet name="sys$jndi">
  <remote-queues>
    <remote-queue name="orders@router2"/>
  </remote-queues>
  <aliases>
    <alias name="sales-orders" map-to="orders@router2"/>
  </aliases>
</swiftlet>

JNDI Replication to External Servers

The JNDI Swiftlet supports replication of its registry to external JNDI servers, such as LDAP or other directory services. Replications are defined as named entities, each with its own configuration, including enablement, keepalive interval, destination context, and environment properties (such as connection parameters for the external server). When enabled, the Swiftlet establishes a connection to the external JNDI server and binds or unbinds objects as they are registered or deregistered locally. The replication mechanism supports periodic keepalive operations to ensure the connection remains active and can automatically reconnect if necessary. Name prefixes and destination contexts can be specified to control how names are mapped in the external directory.

Environment Properties

Each replication can be configured with a set of environment properties, which are passed to the external JNDI context during connection setup. These properties typically include provider URLs, security credentials, and other context-specific parameters. Properties can be added or removed at runtime, triggering a reconnect to the external server.

Keepalive and Reconnection

A periodic keepalive operation is performed for each enabled replication, using a configurable lookup name. If the keepalive fails or the connection is lost, the Swiftlet attempts to reconnect according to the specified interval.

Configuration Example:

<swiftlet name="sys$jndi">
  <jndi-replications>
    <jndi-replication name="ldap-replication" enabled="true" keepalive-interval="30000" keepalive-lookup-name="cn=test" destination-context="ou=swiftmq,dc=example,dc=com" name-prefix="cn=">
      <environment-properties>
        <environment-property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
        <environment-property name="java.naming.provider.url" value="ldap://ldap.example.com:389"/>
        <environment-property name="java.naming.security.principal" value="cn=admin,dc=example,dc=com"/>
        <environment-property name="java.naming.security.credentials" value="secret"/>
      </environment-properties>
    </jndi-replication>
  </jndi-replications>
</swiftlet>

Distributed JNDI Access via Queues and Topics

The Swiftlet exposes its JNDI registry over the messaging layer, allowing distributed clients and routers to perform JNDI operations using special queues and topics. Requests are processed asynchronously by dedicated processors: QueueJNDIProcessor for queue-based requests and TopicJNDIProcessor for topic-based requests. Lookup, bind, rebind, and unbind operations are supported. If a lookup request cannot be satisfied locally, it is forwarded to the cluster via the topic mechanism, ensuring seamless distributed resolution.

Cluster-wide Lookup Forwarding

When a lookup request is received and the requested object is not found locally, the Swiftlet forwards the request to the cluster using a predefined topic. This enables transparent, cluster-wide JNDI resolution, so that clients can discover objects registered on any router.

Internal Queue Naming

  • JNDI — Internal queue for processing JNDI requests (lookup, bind, rebind, unbind) via queue-based messaging.

Configuration Guide

Replicating JNDI Registry to an LDAP Server

Use this scenario to automatically replicate all registered JNDI objects to an external LDAP directory. This is useful for integrating SwiftMQ with enterprise directory services, enabling non-SwiftMQ clients to discover JMS destinations.

  1. Define a JNDI replication entity with the desired name.
  2. Set enabled to true.
  3. Configure the keepalive-interval and keepalive-lookup-name as appropriate for your environment.
  4. Specify the destination-context and name-prefix to control how objects are mapped in LDAP.
  5. Add required environment properties for LDAP connectivity (such as factory, provider URL, credentials).
<swiftlet name="sys$jndi">
  <jndi-replications>
    <jndi-replication name="ldap-replication" enabled="true" keepalive-interval="30000" keepalive-lookup-name="cn=test" destination-context="ou=swiftmq,dc=example,dc=com" name-prefix="cn=">
      <environment-properties>
        <environment-property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
        <environment-property name="java.naming.provider.url" value="ldap://ldap.example.com:389"/>
        <environment-property name="java.naming.security.principal" value="cn=admin,dc=example,dc=com"/>
        <environment-property name="java.naming.security.credentials" value="secret"/>
      </environment-properties>
    </jndi-replication>
  </jndi-replications>
</swiftlet>

Defining an Alias for a Remote Queue

Use this scenario to provide a user-friendly alias for a remote queue, simplifying client lookup and decoupling client code from physical queue names.

  1. Add a remote queue entry for the target queue and router.
  2. Create an alias entity mapping the desired alias name to the remote queue name.
<swiftlet name="sys$jndi">
  <remote-queues>
    <remote-queue name="orders@router2"/>
  </remote-queues>
  <aliases>
    <alias name="sales-orders" map-to="orders@router2"/>
  </aliases>
</swiftlet>

Configuration Reference

The top-level entity in routerconfig.xml is <swiftlet name="sys$jndi">.

<jndi-replications> in <swiftlet name="sys$jndi">

JNDI Replication Definitions

Each <jndi-replication> entry is identified by its name attribute (the JNDI Replication).

Parameter Type Default Mandatory Reboot Required Description
enabled Boolean false No No Enabled/Disabled
keepalive-interval Long 60000 Yes No Keepalive Interval
keepalive-lookup-name String test Yes No Name to use for Lookup during Keep Alive
destination-context String — No No Destination Context
name-prefix String — No No For LDAP you specify cn= here 
<swiftlet name="sys$jndi">
  <jndi-replications>
    <jndi-replication name="..." keepalive-interval="..." keepalive-lookup-name="..."/>
  </jndi-replications>
</swiftlet>

<environment-properties> in <jndi-replications>

Environment Properties

Each <environment-property> entry is identified by its name attribute (the Environment Property).

Parameter Type Default Mandatory Reboot Required Description
value String — Yes No Property Value 
<swiftlet name="sys$jndi">
  <jndi-replications>
    <jndi-replication name="...">
      <environment-properties>
        <environment-property name="..." value="..."/>
      </environment-properties>
    </jndi-replication>
  </jndi-replications>
</swiftlet>

<aliases> in <swiftlet name="sys$jndi">

Alias Definitions

Each <alias> entry is identified by its name attribute (the Alias).

Parameter Type Default Mandatory Reboot Required Description
map-to String — No No Mapping to generic Name 
<swiftlet name="sys$jndi">
  <aliases>
    <alias name="..."/>
  </aliases>
</swiftlet>

<remote-queues> in <swiftlet name="sys$jndi">

Remote Queue Definitions

Each <remote-queue> entry is identified by its name attribute (the Remote Queue).

<swiftlet name="sys$jndi">
  <remote-queues>
    <remote-queue name="..."/>
  </remote-queues>
</swiftlet>