Skip to content

JNDI Client

Overview

The SwiftMQ JNDI Client API provides a JNDI-compatible interface for looking up and binding JMS resources like queues, topics, and connection factories in a SwiftMQ message broker environment. It supports advanced features such as automatic reconnection, authentication, and configurable connection parameters via the provider URL. The API is accessed through the standard JNDI InitialContext, with SwiftMQ-specific configuration options.

InitialContext Setup

To use the SwiftMQ JNDI client, create a standard JNDI InitialContext with a set of environment properties. The key properties are Context.INITIAL_CONTEXT_FACTORY (set to the SwiftMQ factory class, e.g., com.swiftmq.jndi.InitialContextFactoryImpl) and Context.PROVIDER_URL, which specifies the broker connection details in the smqp:// URL format. Optional authentication is supported by embedding the username and password in the URL (e.g., smqp://user:password@host:port). Additional connection parameters (such as socket factory, timeouts, keepalive, idleclose, reconnect options, etc.) can be appended as semicolon-separated key-value pairs after a slash in the URL.

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

Provider URL Format and Parameters

The Context.PROVIDER_URL must be in the format 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>]]. For intra-VM connections, use smqp://intravm. Parameters include: - type: Socket factory class (default: com.swiftmq.net.PlainSocketFactory) - timeout: Request timeout in ms - keepalive: Keepalive interval in ms - idleclose: Idle connection close interval in ms - reconnect: Enable automatic reconnect (true/false) - retrydelay: Delay between reconnect attempts (ms) - maxretries: Maximum reconnect attempts - host2/port2: Secondary host/port for failover - debug: Enable debug output (true/false) Authentication is handled via the username and password in the URL.

// Example with all options:
String url = "smqp://user:pass@primaryhost:4001/type=com.swiftmq.net.PlainSocketFactory;timeout=5000;keepalive=60000;idleclose=120000;reconnect=true;retrydelay=3000;maxretries=10;host2=secondaryhost;port2=4002;debug=true";

Lookup Operations and Naming Conventions

Resource lookup is performed using the standard JNDI Context.lookup(String name) method. SwiftMQ enforces specific naming conventions: - For queues: use queuename@routername (the @routername part is mandatory) - For topics: use just the topic name (no @routername) - For connection factories: use factoryname@routername The lookup returns JMS objects such as Queue, Topic, or ConnectionFactory.

Queue myQueue = (Queue) ctx.lookup("myqueue@router1");
Topic myTopic = (Topic) ctx.lookup("mytopic");
ConnectionFactory cf = (ConnectionFactory) ctx.lookup("myfactory@router1");

Reconnection Support

SwiftMQ JNDI client supports automatic reconnection to the broker if the connection is lost. Reconnection can be enabled either via provider URL parameters (reconnect=true, retrydelay, maxretries, etc.) or by setting environment properties: - swiftmq.jndi.reconnect (true/false): Enable reconnect - swiftmq.jndi.reconnect.max.retries: Maximum reconnect attempts (default 5) - swiftmq.jndi.reconnect.retry.delay: Delay between attempts in ms (default 2000) - swiftmq.jndi.reconnect.debug: Enable debug output (true/false) Multiple provider URLs can be specified for failover by adding Context.PROVIDER_URL_2, Context.PROVIDER_URL_3, etc., to the environment. The client will attempt each URL in order on reconnect.

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 is handled by embedding the username and password in the Context.PROVIDER_URL (e.g., smqp://user:password@host:port). These credentials are extracted and used when establishing the JMS connection. If no credentials are provided, the connection is attempted anonymously.

env.put(Context.PROVIDER_URL, "smqp://myuser:mypassword@localhost:4001");

Supported Operations and Limitations

The SwiftMQ JNDI context supports lookup, bind, rebind, and unbind operations. Only temporary queues and topics can be bound or rebound. Many standard JNDI operations (such as list, listBindings, createSubcontext, destroySubcontext, composeName, and rename) are not supported and will throw OperationNotSupportedException if called.

// Supported:
Object obj = ctx.lookup("myqueue@router1");
ctx.unbind("myqueue@router1");

// Not supported:
// ctx.list(""); // throws OperationNotSupportedException