Chapter 21. Configuring the Naming Subsystem

21.1. About the Naming Subsystem

The naming subsystem provides the JNDI implementation for JBoss EAP. You can configure this subsystem to bind entries in global JNDI namespaces. You can also configure it to activate or deactivate the remote JNDI interface.

The following is an example of the naming subsystem XML configuration example with all of the elements and attributes specified. 

<subsystem xmlns="urn:jboss:domain:naming:2.0">
    <bindings>
        <simple name="java:global/simple-integer-binding" value="100" type="int" />
        <simple name="java:global/jboss.org/docs/url" value="https://docs.jboss.org" type="java.net.URL" />
        <object-factory name="java:global/foo/bar/factory" module="org.foo.bar" class="org.foo.bar.ObjectFactory" />
        <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/new-alias-name" lookup="java:global/original-name" />
    </bindings>
    <remote-naming/>
</subsystem>

21.2. Configuring Global Bindings

The naming subsystem allows you to bind entries into the java:global, java:jboss, or java global JNDI namespaces; however, it is recommended that you use the standard portable java:global namespace.

Global bindings are configured in the <bindings> element of the naming subsystem. Four types of bindings are supported:

Configuring Simple Bindings

The simple XML configuration element binds primitive or java.net.URL entries.

  • The name attribute is mandatory and specifies the target JNDI name for the entry.
  • The value attribute is mandatory and defines the entry’s value.
  • The optional type attribute, which defaults to java.lang.String, specifies the type of the entry’s value. In addition to java.lang.String, you can specify primitive types and their corresponding object wrapper classes, such as int or java.lang.Integer, and java.net.URL.

The following is an example of a management CLI command that creates a simple binding. 

/subsystem=naming/binding=java\:global\/simple-integer-binding:add(binding-type=simple, type=int, value=100)

Resulting XML Configuration

<subsystem xmlns="urn:jboss:domain:naming:2.0">
    <bindings>
        <simple name="java:global/simple-integer-binding" value="100" type="int"/>
    </bindings>
    <remote-naming/>
</subsystem>

Use the following command to remove the binding. 

/subsystem=naming/binding=java\:global\/simple-integer-binding:remove

Binding Object Factories

The object-factory XML configuration element binds javax.naming.spi.ObjectFactory entries.

  • The name attribute is mandatory and specifies the target JNDI name for the entry.
  • The class attribute is mandatory and defines the object factory’s Java type.
  • The module attribute is mandatory and specifies the JBoss Module ID where the object factory Java class can be loaded from.
  • The optional environment child element can be used to provide a custom environment to the object factory.

The following is an example of a management CLI command that creates an object factory binding. 

/subsystem=naming/binding=java\:global\/foo\/bar\/factory:add(binding-type=object-factory, module=org.foo.bar, class=org.foo.bar.ObjectFactory, environment=[p1=v1, p2=v2])

Resulting XML Configuration

<subsystem xmlns="urn:jboss:domain:naming:2.0">
    <bindings>
        <object-factory name="java:global/foo/bar/factory" module="org.foo.bar" class="org.foo.bar.ObjectFactory">
            <environment>
                <property name="p1" value="v1" />
                <property name="p2" value="v2" />
            </environment>
        </object-factory>
    </bindings>
  </subsystem>

Use the following command to remove the binding. 

/subsystem=naming/binding=java\:global\/foo\/bar\/factory:remove

Binding External Contexts

Federation of external JNDI contexts, such as LDAP context, are achieved using the external-context XML configuration element.

  • The name attribute is mandatory and specifies the target JNDI name for the entry.
  • The class attribute is mandatory and indicates the Java initial naming context type used to create the federated context. Note that such type must have a constructor with a single environment map argument.
  • The optional module attribute specifies the JBoss Module ID where any classes required by the external JNDI context can be loaded from.
  • The optional cache attribute, which defaults to false, indicates whether the external context instance should be cached.
  • The optional environment child element can be used to provide the custom environment needed to look up the external context.

The following is an example of a management CLI command that creates an external context binding. 

/subsystem=naming/binding=java\:global\/federation\/ldap\/example:add(binding-type=external-context, cache=true, class=javax.naming.directory.InitialDirContext, module=org.jboss.as.naming, environment=[java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory, java.naming.provider.url="ldap://ldap.example.com:389", java.naming.security.authentication=simple, java.naming.security.principal="uid=admin,ou=system", java.naming.security.credentials=secret]

Resulting XML Configuration

<subsystem xmlns="urn:jboss:domain:naming:2.0">
  <bindings>
    <external-context name="java:global/federation/ldap/example" module="org.jboss.as.naming" 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>
  </bindings>
</subsystem>

Use the following command to remove the binding. 

/subsystem=naming/binding=java\:global\/federation\/ldap\/example:remove
Note

Resource look up for JNDI providers that do not properly implement the lookup(Name) method can result in a "javax.naming.InvalidNameException: Only support CompoundName names" error.

You might be able to work around this issue by specifying that the external context environment use the lookup(String) method instead by adding the following property; however, this can result in a performance degradation. 

<property name="org.jboss.as.naming.lookup.by.string" value="true"/>

Binding Lookup Aliases

The lookup element allows you to bind existing entries into additional names or aliases.

  • The name attribute is mandatory and specifies the target JNDI name for the entry.
  • The lookup attribute is mandatory and indicates the source JNDI name.

The following is an example of a management CLI command that binds an existing entry to an alias. 

/subsystem=naming/binding=java\:global\/new-alias-name:add(binding-type=lookup, lookup=java\:global\/original-name)

Resulting XML Configuration

<lookup name="java:global/new-alias-name" lookup="java:global/original-name" />

Use the following command to remove the binding. 

/subsystem=naming/binding=java\:global\/c:remove

21.3. Configuring the Remote JNDI Interface

The remote JNDI interface allows clients to look up entries in remote JBoss EAP instances. The naming subsystem can be configured to deactivate or activate this interface, which is activated by default. The remote JNDI interface is configured using the <remote-naming> element.

Use the following management CLI command to activate or reactivate the remote JNDI interface. 

/subsystem=naming/service=remote-naming:add

Use the following management CLI command to deactivate the remote JNDI interface. 

/subsystem=naming/service=remote-naming:remove
Note

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