External JNDI Configuration and JNDI Viewing

Author:Scott Stark <Scott_Stark@displayscape.com>

The JNDI ExternalContext and JNDIView MBeans

The ExternalContext JNDI MBean allows one to federate external JNDI contexts into the JBoss server JNDI namespace. This allows one to incorporate LDAP servers, Filesystem directories, DNS servers, etc. even if the JNDI providers root context is not Serializable. The federation can be made available to remote client in some circumstances.

The JNDIView MBean allows one to view the JNDI namespace tree as it exists in the JBoss server using the JMX agent view interface.

Preparation of the ExternalContext MBean

First you have to add the ExternalContext service to the jboss.jcml in order to load the service. The folloing jboss.jcml fragment shows the setup for an LDAP server and a local filesystem directory:

<mbean code="org.jboss.naming.ExternalContext" name="DefaultDomain:service=ExternalContext,jndiName=external/ldap/dscape" >
    <attribute name="JndiName">external/ldap/dscape</attribute>
    <attribute name="Properties">dscape.ldap</attribute>
    <attribute name="InitialContext">javax.naming.ldap.InitialLdapContext</attribute>
    <attribute name="RemoteAccess">true</attribute>
</mbean>

<mbean code="org.jboss.naming.ExternalContext" name="DefaultDomain:service=ExternalContext,jndiName=external/fs/Scott" >
    <attribute name="JndiName">external/fs/Scott</attribute>
    <attribute name="Properties">scott_fs.props</attribute>
    <attribute name="InitialContext">javax.naming.InitialContext</attribute>
</mbean>

where:

code="org.jboss.naming.ExternalContext" specifies the class that impliments the external context mbean.
name="DefaultDomain:service=ExternalContext,jndiName=external/ldap/dscape" assigns the name of the mbean. This is using a convention that sets the service property of the key to ExternalContext and adds a jndiName property that equals the mbean JndiName attribute. This allows multiple ExternalContext mbeans to easily be located and differentiated.
JndiName is the name with which the external context is bound into the JBoss JNDI namespace
Properties is URL string to a jndi.properties style of file for the JNDI provider whose context is to be created. This can be any url for which there is a handler or a simple string in which case it is treated as a resource that can be loaded via the current thread's context class loader.
InitialContext is the class name of the InitialContext class to create. Should be one of javax.naming.InitialContext, javax.naming.directory.InitialDirContext, or javax.naming.ldap.InitialLdapContext. In the case of the InitialLdapContext, a null Controls array is used. If this property is not given it defaults to javax.naming.InitialContext
RemoteAccess is a boolean flag indicating if the external InitialContext should be bound using a Serializable form that allows a remote client to create the external InitialContext. When a remote client looks up the external context via the JBoss JNDI InitialContext they effectively create an instance of the external InitialContext using the same env properties passed to the ExternalContext mbean. This will only work if the client could do a 'new InitialContext(env)' remotely. This requires that the provider url makes sense. For the LDAP example this should work. For the FileSystem example this most likely won't work unless the FileSystem path refers to a common network path. If this property is not given it defaults to false.

This example is binding an external LDAP context into the JBoss JNDI namespace under the name "external/ldap/dscape". An example dscape.ldap properties file is:

java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
java.naming.provider.url=ldap://ldaphost.displayscape.com:389/o=displayscape.com
java.naming.security.principal=cn=Directory Manager
java.naming.security.authentication=simple
java.naming.security.credentials=secret

With this mbean loaded, you can access the external LDAP context located at "ldap://ldaphost.displayscape.com:389/o=displayscape.com" from within the JBoss VM using the following code fragment:

InitialContext iniCtx = new InitialContext();
Context ldapCtx = iniCtx.lookup("external/ldap/dscape");
...

Using the same code fragment outside of the JBoss server VM will work in this case because the RemoteAccess property was set to true. If it was set to false it would not work because the remote client would receive a Reference object with an ObjectFactory that would not be able to recreate the external IntialContext.

Preparation of the JNDIView MBean

All that is required to use the JNDIView service is to add it to jboss.jcml The mbean tag looks like this:

There are no configurable attributes. This simply loads the mbean into the JBoss server VM so that it can be used via the JMX MBean View.

Using the JNDIView MBean

To view the JBoss JNDI namespace using the JNDIView mbean, you connect to the JMX Agent View using the http interface. The default settings put this athttp://localhost:8082/. On this page you will see a section that lists the registered MBeans by domain. It should look something like this:

This is showing two registered ExternalContext mbeans(ExternalContext/fs/Scott[a filesystem] and ExternalContext/ldap/dscape[an ldap server]) mbeans as well as the JNDIView mbean. Selecting the service=JNDIView link takes you to the JNDIView MBean View which will have a list of MBean operations section similar to:

Invoking the list operation creates a dump of the JBoss JNDI namespace that includes the federated external contexts. As an example, this is the dump with the filesystem and ldap contexts. The following image displays the start of the global JNDI namespace and includes the external/fs/Scott local filesystem directory contents.