JBoss Community Archive (Read Only)

Latest WildFly Documentation

Local JNDI

The Java EE platform specification defines the following JNDI contexts:

In addition to the standard namespaces, WildFly also provides the following two global namespaces:

Only entries within the java:jboss/exported context are accessible over remote JNDI.

For web deployments java:comp is aliased to java:module, so EJB's deployed in a war do not have their own comp namespace.

Binding entries to JNDI

There are several methods that can be used to bind entries into JNDI in WildFly.

Using a deployment descriptor

For Java EE applications the recommended way is to use a deployment descriptor to create the binding. For example the following web.xml binds the string "Hello World" to java:global/mystring and the string "Hello Module" to java:comp/env/hello (any non absolute JNDI name is relative to java:comp/env context).

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">
    <env-entry>
        <env-entry-name>java:global/mystring</env-entry-name>
        <env-entry-type>java.lang.String</env-entry-type>
        <env-entry-value>Hello World</env-entry-value>
    </env-entry>
    <env-entry>
        <env-entry-name>hello</env-entry-name>
        <env-entry-type>java.lang.String</env-entry-type>
        <env-entry-value>Hello Module</env-entry-value>
    </env-entry>
</web-app>

For more details, see the Java EE Platform Specification.

Programatically

Java EE Applications

Standard Java EE applications may use the standard JNDI API, included with Java SE, to bind entries in the global namespaces (the standard java:comp, java:module and java:app namespaces are read-only, as mandated by the Java EE Platform Specification).

  InitialContext initialContext = new InitialContext();
  initialContext.bind("java:global/a", 100);

There is no need to unbind entries created programatically, since WildFly tracks which bindings belong to a deployment, and the bindings are automatically removed when the deployment is undeployed.

WildFly Modules and Extensions

With respect to code in WildFly Modules/Extensions, which is executed out of a Java EE application context, using the standard JNDI API may result in a UnsupportedOperationException if the target namespace uses a WritableServiceBasedNamingStore. To work around that, the bind() invocation needs to be wrapped using WildFly proprietary APIs:

  InitialContext initialContext = new InitialContext();
  WritableServiceBasedNamingStore.pushOwner(serviceTarget);
  try {
    initialContext.bind("java:global/a", 100);
  } finally {
    WritableServiceBasedNamingStore.popOwner();
  }

The ServiceTarget removes the bind when uninstalled, thus using one out of the module/extension domain usage should be avoided, unless entries are removed using unbind().

Naming Subsystem Configuration

It is also possible to bind to one of the three global namespaces using configuration in the naming subsystem. This can be done by either editing the standalone.xml/domain.xml file directly, or through the management API.

Four different types of bindings are supported:

  • Simple - A primitive or java.net.URL entry (default is java.lang.String).

  • Object Factory - This allows to to specify the javax.naming.spi.ObjectFactory that is used to create the looked up value.

  • External Context - An external context to federate, such as an LDAP Directory Service 

  • Lookup - The allows to create JNDI aliases, when this entry is looked up it will lookup the target and return the result.

An example standalone.xml might look like:

<subsystem xmlns="urn:jboss:domain:naming:2.0" >
  <bindings>
    <simple name="java:global/a" value="100" type="int" />
    <simple name="java:global/jbossDocs" value="https://docs.jboss.org" type="java.net.URL" />
    <object-factory name="java:global/b" module="com.acme" class="org.acme.MyObjectFactory" />
    <external-context name="java:global/federation/ldap/example” class="javax.naming.directory.InitialDirContext" cache="true">
      <environment>
        <property name="java.naming.factory.initial" value=“com.sun.jndi.ldap.LdapCtxFactory” />
        <property name="java.naming.provider.url" value=“ldap://ldap.example.com:389” />
        <property name="java.naming.security.authentication" value=“simple” />
        <property name="java.naming.security.principal" value=“uid=admin,ou=system” />
        <property name="java.naming.security.credentials" value=“secret” />
      </environment>
    </external-context>
    <lookup name="java:global/c" lookup="java:global/b" />
 </bindings>
</subsystem>

The CLI may also be used to bind an entry. As an example:

/subsystem=naming/binding=java\:global\/mybinding:add(binding-type=simple, type=long, value=1000)

WildFly's Administrator Guide includes a section describing in detail the Naming subsystem configuration.

Retrieving entries from JNDI

Resource Injection

For Java EE applications the recommended way to lookup a JNDI entry is to use @Resource injection:

  @Resource(lookup = "java:global/mystring")
  private String myString;

  @Resource(name = "hello")
  private String hello;

  @Resource
  ManagedExecutorService executor;

Note that @Resource is more than a JNDI lookup, it also binds an entry in the component's JNDI environment. The new bind JNDI name is defined by @Resource's name attribute, which value, if unspecified, is the Java type concatenated with / and the field's name, for instance java.lang.String/myString. More, similar to when using deployment descriptors to bind JNDI entries. unless the name is an absolute JNDI name, it is considered relative to java:comp/env. For instance, with respect to the field named myString above, the @Resource's lookup attribute instructs WildFly to lookup the value in java:global/mystring, bind it in java:comp/env/java.lang.String/myString, and then inject such value into the field.

With respect to the field named hello, there is no lookup attribute value defined, so the responsibility to provide the entry's value is delegated to the deployment descriptor. Considering that the deployment descriptor was the web.xml previously shown, which defines an environment entry with same hello name, then WildFly inject the valued defined in the deployment descriptor into the field.

The executor field has no attributes specified, so the bind's name would default to java:comp/env/javax.enterprise.concurrent.ManagedExecutorService/executor, but there is no such entry in the deployment descriptor, and when that happens it's up to WildFly to provide a default value or null, depending on the field's Java type. In this particular case WildFly would inject the default instance of a managed executor service, the value in java:comp/DefaultManagedExecutorService, as mandated by the EE Concurrency Utilities 1.0 Specification (JSR 236).

Standard Java SE JNDI API

Java EE applications may use, without any additional configuration needed, the standard JNDI API to lookup an entry from JNDI:

  String myString = (String) new InitialContext().lookup("java:global/mystring");

or simply

  String myString = InitialContext.doLookup("java:global/mystring");
JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-13 13:33:05 UTC, last content change 2014-04-02 20:26:39 UTC.