Chapter 5. Remote JNDI lookup

5.1. Registering objects to JNDI

The Java Naming and Directory Interface (JNDI) 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 JNDI needs to be looked up by remote JNDI 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 JMS queue in the messaging-activemq subsystem must be exposed for remote JNDI clients, then it must be registered to JNDI using something like java:jboss/exported/jms/queue/myTestQueue. The remote JNDI 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:2.0">
  <server name="default">
    ...
    <jms-queue name="myTestQueue" entries="java:jboss/exported/jms/queue/myTestQueue"/>
    ...
  </server>
</subsystem>

5.2. Configuring remote JNDI

A remote JNDI client can connect and lookup objects by name from JNDI. It must have the jboss-client.jar on 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

Important

JNDI invocation over HTTP is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.

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:

<dependency>
    <groupId>org.wildfly.wildfly-http-client</groupId>
    <artifactId>wildfly-http-naming-client</artifactId>
</dependency>

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.

Note

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.