External JNDI Configuration and JNDI Viewing
Author:Scott Stark
<[email protected]>
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:
<!-- Bind a remote LDAP server -->
<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>
<!-- Bind the /Scott filesystem directory -->
<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:
<mbean code="org.jboss.naming.JNDIView" name="DefaultDomain:service=JNDIView" >
</mbean>
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.
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.