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="{NamingSubsystemNamespace}"> <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="jakarta.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 tojava.lang.String
, specifies the type of the entry’s value. In addition tojava.lang.String
, you can specify primitive types and their corresponding object wrapper classes, such asint
orjava.lang.Integer
, andjava.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="{NamingSubsystemNamespace}"> <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 jakarta.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="{NamingSubsystemNamespace}"> <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 tofalse
, 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=jakarta.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="{NamingSubsystemNamespace}"> <bindings> <external-context name="java:global/federation/ldap/example" module="org.jboss.as.naming" class="jakarta.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
Resource look up for JNDI providers that do not properly implement the lookup(Name)
method can result in a "jakarta.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. Dynamically change JNDI bindings
JBoss EAP 7.1 introduced 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.
21.4. 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
Only entries within the java:jboss/exported
context are accessible over remote JNDI.