Chapter 22. Configuring 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>

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 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)

<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 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])

<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 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])

<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

<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 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)

<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

JBoss EAP 7.1 introduces the ability to dynamically change JNDI bindings without forcing a server reload or restart. This feature can be useful if the network service endpoints are dynamically reconfigured due to version updates, testing requirements, or application feature updates.

To update a JNDI binding, use the rebind operation. The rebind operation takes the same arguments as the add operation. This command works for all binding types except for external-context binding types. External context bindings require additional dependencies, which affect the Modular Service Container (MSC) state, so they cannot be restarted without restarting services.

The following command dynamically changes the JNDI binding that was defined in the Configuring Simple Bindings example.

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

For more information about how to configure global bindings in the naming subsystem, see Configuring Global Bindings.

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