JNDI Swiftlet

Overview

The JNDI Swiftlet provides Java Naming and Directory Interface (JNDI) services within the SwiftMQ router. It allows JMS destinations (queues and topics) and other objects to be registered and looked up via JNDI, supporting both local and external JNDI servers. The Swiftlet also supports replication of JNDI objects to external directory services and the definition of aliases and static remote queues.

Features

JNDI Object Registration and Lookup

The JNDI Swiftlet maintains an internal registry of JNDI objects, such as queues and topics, which can be registered and looked up by name. When a JNDI object is registered, it is stored in an internal map and can be accessed via JNDI lookup requests. The Swiftlet supports registering objects directly, as well as through remote queue definitions. Lookup requests are processed via a dedicated queue and topic, ensuring both queue-based and topic-based JNDI requests are handled efficiently. If a lookup is not found locally, the request can be forwarded to other routers via the topic mechanism.

Remote Queue Definitions

Remote queues can be defined statically in the configuration, specifying fully qualified queue names (in the format @). These are registered as JNDI objects at startup and can be looked up by clients.

Alias Support

Aliases allow mapping alternative names to existing JNDI objects. When an alias is defined, lookup requests for the alias name are resolved to the mapped object. Aliases are dynamically managed and changes are reflected in the internal registry and, if replication is enabled, on external JNDI servers.

Configuration Example:

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

JNDI Replication to External Directory Services

The JNDI Swiftlet supports replication of registered JNDI objects to external JNDI servers, such as LDAP directories. Replication is configured through JNDI replication entities, each specifying connection parameters, environment properties, and replication behavior. When enabled, the Swiftlet establishes a connection to the external directory and binds or unbinds objects as they are registered or deregistered locally. Replication can be fine-tuned with options such as keepalive intervals (for periodic health checks), lookup names for keepalive operations, destination context within the external directory, and name prefixes (useful for LDAP schemas). Environment properties allow specifying custom connection settings for the external JNDI provider. Replication entities can be enabled or disabled dynamically, and changes to configuration properties are applied in real time.

Keepalive Mechanism

Each replication entity can be configured with a keepalive interval and a lookup name. The Swiftlet periodically performs a lookup operation on the external JNDI server to ensure the connection remains alive and to detect connectivity issues. If the keepalive operation fails, the Swiftlet attempts to reconnect and rebind all registered objects.

Dynamic Environment Properties

Environment properties for the external JNDI context (such as provider URL, security credentials, or factory class) are specified as a list of name/value pairs. These properties are used to initialize the external JNDI context and can be updated dynamically. Changes to environment properties trigger a reconnection to the external server.

Destination Context and Name Prefix

The destination context specifies the subcontext within the external directory where objects are bound. The name prefix allows prepending a string (such as cn=) to all bound names, which is particularly useful for LDAP directories.

Configuration Example:

<swiftlet name="sys$jndi">
  <jndi-replications>
    <jndi-replication name="ldap-replication" enabled="true" keepalive-interval="120000" keepalive-lookup-name="healthCheck" destination-context="ou=queues,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="password"/>
      </environment-properties>
    </jndi-replication>
  </jndi-replications>
</swiftlet>

JNDI Request Processing via Queue and Topic

The Swiftlet provides two mechanisms for processing JNDI requests: a dedicated queue and a dedicated topic. The queue-based processor handles direct JNDI requests sent to the internal JNDI queue, while the topic-based processor subscribes to the JNDI topic and processes distributed JNDI requests. This dual mechanism ensures that both local and remote JNDI lookups, binds, rebinds, and unbinds are supported, providing flexibility for clients and other routers in a networked environment.

Distributed JNDI Lookup

If a lookup request cannot be resolved locally, the Swiftlet can forward the request to the JNDI topic, allowing other routers to respond if they have the requested object registered.

Internal Queue Naming

• JNDI_QUEUE — Internal queue used to process JNDI requests (lookup, bind, rebind, unbind) via queue-based messaging.
• JNDI_TOPIC — Internal topic used to process distributed JNDI requests and enable forwarding of lookup requests across routers.

Configuration Guide

Replicating JNDI Objects to an LDAP Directory

Use this scenario to automatically publish all registered JNDI objects (such as queues and topics) to an external LDAP directory for centralized management and lookup by external clients.

1. Define a JNDI replication entity with appropriate environment properties for the LDAP server.
2. Set the replication entity's enabled attribute to true.
3. Specify the keepalive interval and lookup name for health checking.
4. Optionally set the destination context and name prefix for LDAP schema compatibility.

<swiftlet name="sys$jndi">
  <jndi-replications>
    <jndi-replication name="ldap-replication" enabled="true" keepalive-interval="60000" keepalive-lookup-name="test" destination-context="ou=queues,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="password"/>
      </environment-properties>
    </jndi-replication>
  </jndi-replications>
</swiftlet>

Defining a Static Remote Queue and Alias

Use this scenario to make a remote queue available for JNDI lookup and provide an alias for easier client access.

1. Define the remote queue with its fully qualified name (@).
2. Create an alias mapping a friendly name to the remote queue.
3. Clients can now perform JNDI lookups using either the alias or the full queue name.

<swiftlet name="sys$jndi">
  <remote-queues>
    <remote-queue name="orders@router2"/>
  </remote-queues>
  <aliases>
    <alias name="orderQueue" 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>

Related Documents

• JMS Swiftlet