Skip to content

JNDI Client

Overview

The SwiftMQ JNDI Client API provides a JNDI Context implementation for looking up JMS resources (queues, topics, connection factories) from a SwiftMQ router using the smqp protocol. It supports connection failover, authentication, and various connection parameters via the provider URL or environment properties. The API allows for robust resource lookup and optional automatic reconnection to multiple endpoints.

InitialContext Setup

To use the SwiftMQ JNDI client, create an InitialContext by supplying a Hashtable environment with at least the Context.PROVIDER_URL and Context.INITIAL_CONTEXT_FACTORY properties. The factory class is typically com.swiftmq.jndi.InitialContextFactoryImpl. The Context.PROVIDER_URL must use the smqp:// protocol and can include authentication, host, port, and additional connection parameters. Example:

Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.swiftmq.jndi.InitialContextFactoryImpl");
env.put(Context.PROVIDER_URL, "smqp://user:pass@host:4001/type=com.swiftmq.net.PlainSocketFactory;timeout=5000;keepalive=60000");
Context ctx = new InitialContext(env);

If the URL is missing or invalid, a NamingException is thrown.

Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.swiftmq.jndi.InitialContextFactoryImpl");
env.put(Context.PROVIDER_URL, "smqp://user:pass@host:4001/type=com.swiftmq.net.PlainSocketFactory;timeout=5000;keepalive=60000");
Context ctx = new InitialContext(env);

Provider URL Format

The Context.PROVIDER_URL must use the smqp:// protocol. The format is:

smqp://[<user>[:<passwd>]@]<host>:<port>[/[type=<type>][;timeout=<ms>][;keepalive=<ms>][;idleclose=<ms>][;reconnect=<boolean>][;retrydelay=<ms>][;maxretries=<int>][;host2=<host>][;port2=<port>][;debug=<boolean>]]

  • Authentication: supply username and password before the @.
  • type: socket factory class (default: com.swiftmq.net.PlainSocketFactory).
  • timeout: lookup timeout in ms.
  • keepalive: keepalive interval in ms.
  • idleclose: idle timeout for closing the connection.
  • reconnect: enable automatic reconnection (true/false).
  • retrydelay: ms to wait between retries.
  • maxretries: max number of reconnection attempts.
  • host2 and port2: secondary host/port for failover.
  • debug: enable debug output.

Example: smqp://user:pass@host:4001/type=com.swiftmq.net.PlainSocketFactory;timeout=5000;reconnect=true;host2=hostbackup;port2=4002;debug=true

// Example provider URL
String url = "smqp://user:pass@host:4001/type=com.swiftmq.net.PlainSocketFactory;timeout=5000;reconnect=true;host2=hostbackup;port2=4002;debug=true";

Lookup Operations and Naming Conventions

Resource lookup uses standard JNDI methods. For SwiftMQ, the naming conventions are: - Queue: use queuename@routername (the @routername part is mandatory for queues). - Topic: use just topicname (no @router for topics). - ConnectionFactory: use factoryname@routername.

Example lookups: 

Queue queue = (Queue) ctx.lookup("myqueue@router1");
Topic topic = (Topic) ctx.lookup("mytopic");
ConnectionFactory cf = (ConnectionFactory) ctx.lookup("ConnectionFactory@router1");

The API supports lookup(String name) and lookup(Name name). If the name is not found or times out, a NameNotFoundException is thrown.

Queue queue = (Queue) ctx.lookup("myqueue@router1");
Topic topic = (Topic) ctx.lookup("mytopic");
ConnectionFactory cf = (ConnectionFactory) ctx.lookup("ConnectionFactory@router1");

Reconnection and Failover

Automatic reconnection is supported via provider URL parameters or environment properties. To enable, set reconnect=true in the URL or set the environment property swiftmq.jndi.reconnect to true. You can specify multiple provider URLs for failover by adding Context.PROVIDER_URL_2, Context.PROVIDER_URL_3, etc. The following environment properties control reconnection: - swiftmq.jndi.reconnect: enable/disable reconnection (boolean). - swiftmq.jndi.reconnect.max.retries: max retries (default 5). - swiftmq.jndi.reconnect.retry.delay: delay between retries in ms (default 2000). - swiftmq.jndi.reconnect.debug: enable debug output (boolean).

When enabled, the context will automatically attempt to reconnect to the next available URL on connection failure, up to the configured number of retries.

env.put("swiftmq.jndi.reconnect", "true");
env.put("swiftmq.jndi.reconnect.max.retries", "10");
env.put("swiftmq.jndi.reconnect.retry.delay", "3000");
env.put("swiftmq.jndi.reconnect.debug", "true");
env.put(Context.PROVIDER_URL, "smqp://host1:4001");
env.put(Context.PROVIDER_URL + "_2", "smqp://host2:4002");

Authentication

Authentication credentials can be supplied in the provider URL as smqp://user:pass@host:port/.... The username and password are extracted and used to create the JMS connection. If authentication fails, a NamingException or JMSSecurityException is thrown. Example:

env.put(Context.PROVIDER_URL, "smqp://alice:secret@routerhost:4001");

env.put(Context.PROVIDER_URL, "smqp://alice:secret@routerhost:4001");