Chapter 5. Remote JNDI lookup

5.1. Registering Objects to Java Naming and Directory Interface

The Java Naming and Directory Interface is a Java API for a directory service that allows Java software clients to discover and look up objects using a name.

If an object registered to Java Naming and Directory Interface needs to be looked up by remote Java Naming and Directory Interface clients, for example clients that run in a separate JVM, then it must be registered under the java:jboss/exported context.

For example, if a Jakarta Messaging queue in the messaging-activemq subsystem must be exposed for remote Java Naming and Directory Interface clients, then it must be registered to Java Naming and Directory Interface using java:jboss/exported/jms/queue/myTestQueue. The remote Java Naming and Directory Interface client can then look it up by the name jms/queue/myTestQueue.

Example: Configuration of the Queue in standalone-full(-ha).xml

<subsystem xmlns="urn:jboss:domain:messaging-activemq:4.0">
  <server name="default">
    <jms-queue name="myTestQueue" entries="java:jboss/exported/jms/queue/myTestQueue"/>

5.2. Configuring Remote JNDI

A remote JNDI client can connect and look up objects by name from JNDI. To use a remote JNDI client to look up objects, it must have the jboss-client.jar in its class path. The jboss-client.jar is available at EAP_HOME/bin/client/jboss-client.jar.

The following example shows how to look up the myTestQueue queue from JNDI in a remote JNDI client:

Example: Configuration for an MDB Resource Adapter

Properties properties = new Properties();
properties.put(Context.INITIAL_CONTEXT_FACTORY, "org.wildfly.naming.client.WildFlyInitialContextFactory");
properties.put(Context.PROVIDER_URL, "remote+http://HOST_NAME:8080");
context = new InitialContext(properties);
Queue myTestQueue = (Queue) context.lookup("jms/queue/myTestQueue");

5.3. JNDI Invocation Over HTTP

JNDI invocation over HTTP includes two distinct parts: the client-side and the server-side implementations.

5.3.1. Client-side Implementation

The client-side implementation is similar to the remote naming implementation, but based on HTTP using the Undertow HTTP client.

Connection management is implicit rather than direct, using a caching approach similar to the one used in the existing remote naming implementation. Connection pools are cached based on connection parameters. If they are not used in the specified timeout period, they are discarded.

In order to configure a remote JNDI client application to use HTTP transport, you must add the following dependency on the HTTP transport implementation:


To perform the HTTP invocation, you must use the http URL scheme and include the context name of the HTTP invoker, wildfly-services. For example, if you are using remote+http://localhost:8080 as the target URL, in order to use HTTP transport, you must update this to http://localhost:8080/wildfly-services.

5.3.2. Server-side Implementation

The server-side implementation is similar to the existing remote naming implementation but with an HTTP transport.

In order to configure the server, you must enable the http-invoker on each of the virtual hosts that you wish to use in the undertow subsystem. This is enabled by default in the standard configurations. If it is disabled, you can re-enable it using the following management CLI command:

/subsystem=undertow/server=default-server/host=default-host/setting=http-invoker:add(http-authentication-factory=myfactory, path="/wildfly-services")

The http-invoker attribute takes two parameters: a path that defaults to /wildfly-services and an http-authentication-factory that must be a reference to an Elytron http-authentication-factory.


Any deployment that aims to use the http-authentication-factory must use Elytron security with the same security domain corresponding to the specified HTTP authentication factory.