- An Overview of JNDI
- J2EE and JNDI—The Application Component Environment
- The JBossNS Architecture
- Additional Naming MBeans
Additional Naming MBeans
In addition to the NamingService MBean that configures an embedded JBossNS server within JBoss, there are three additional MBean services related to naming that ship with JBoss. They are the ExternalContext, NamingAlias, and JNDIView.
The ExternalContext MBean allows you to federate external JNDI contexts into the JBoss server JNDI namespace. The term external refers to any naming service external to the JBossNS naming service running inside of the JBoss server VM. You can incorporate LDAP servers, file systems, DNS servers, and so on, even if the JNDI provider root context is not serializable. The federation can be made available to remote clients if the naming service supports remote access.
To incorporate an external JNDI naming service, you have to add a configuration of the ExternalContext MBean service to the jboss.jcml configuration file. The configurable attributes of the ExternalContext service are as follows:
JndiNameThe JNDI name under which the external context is to be bound.
RemoteAccessA 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 Context.PROVIDER_URL value of env is resolvable in the remote VM that is accessing the context. This should work for the LDAP example. For the file system example this most likely won't work unless the file system path refers to a common network path. If this property is not given it defaults to false.
CacheContextThe cacheContext flag. When set to true, the external Context is only created when the MBean is started and then stored as an in memory object until the MBean is stopped. If cacheContext is set to false, the external Context is created on each lookup using the MBean properties and InitialContext class. When the uncached Context is looked up by a client, the client should invoke close() on the Context to prevent resource leaks.
InitialContextThe fully qualified class name of the InitialContext implementation to use. Must 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. The default is javax.naming.InitialContex.
PropertiesSet the jndi.properties information for the external InitialContext. This is either a URL string or a classpath resource name. Examples are as follows:
The jboss.jcml fragment shown in Listing 3.14 shows two configurationsone for an LDAP server, and the other for a local file system directory.
Listing 3.14 ExternalContext MBean Configurations File System
<!-- Bind a remote LDAP server -->
<mbean code="org.jboss.naming.ExternalContext" name=":service=ExternalContext,jndiName=external/ldap/dscape" >
<attribute name="InitialContext"> javax.naming.ldap.InitialLdapContext </attribute>
<!-- Bind the /usr/local file system directory -->
<mbean code="org.jboss.naming.ExternalContext" name=":service=ExternalContext,jndiName=external/fs/usr/local" >
The first configuration describes binding an external LDAP context into the JBoss JNDI namespace under the name external/ldap/dscape. An example dscape.ldap properties file is as follows:
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 configuration, 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(); LdapContext 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 were 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.
The second configuration describes binding a local file system directory /usr/local into the JBoss JNDI namespace under the name external/fs/usr/local. An example local.props properties file is
With this configuration, you can access the external file system context located at file:///usr/local from within the JBoss VM using the following code fragment:
InitialContext iniCtx = new InitialContext(); Context ldapCtx = iniCtx.lookup("external/fs/usr/local");
The org.jboss.naming.NamingAlias MBean
The NamingAlias MBean is a simple utility service that allows you to create an alias in the form of a JNDI javax.naming.LinkRef from one JNDI name to another. This is similar to a symbolic link in the Unix file system. To an alias you add a configuration of the NamingAlias MBean to the jboss.jcml configuration file. The configurable attributes of the NamingAlias service are as follows:
FromNameThe location where the LinkRef is bound under JNDI.
ToNameThe to name of the alias. This is the target name to which the LinkRef refers. The name is a URL, or a name to be resolved relative to the InitialContext, or if the first character of the name is., the name is relative to the context in which the link is bound.
An example that can be found in the standard jboss.jcml configuration file is as follows:
<mbean code="org.jboss.naming.NamingAlias" name="DefaultDomain:service=NamingAlias,fromName=QueueConnectionFactory"> <attribute name="ToName">ConnectionFactory</attribute> <attribute name="FromName">QueueConnectionFactory</attribute> </mbean>
This says that the JNDI name QueueConnectionFactory should be a binding to a LinkRef that points to the binding for the JNDI name ConnectionFactory.
The org.jboss.naming.JNDIView MBean
The JNDIView MBean allows the user to view the JNDI namespace tree as it exists in the JBoss server using the JMX agent view interface. All that is required to use the JNDIView service is to add a configuration to jboss.jcml file. The JNDIView service has no configurable attributes, and so a suitable configuration is:
<mbean code="org.jboss.naming.JNDIView" name="DefaultDomain:service=JNDIView"/>
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 at http://localhost:8082/. On this page you will see a section that lists the registered MBeans by domain. It should look something like that shown in Figure 3.6, where the JNDIView MBean is under the mouse cursor.
Selecting the JNDIView link takes you to the JNDIView MBean view, which will have a list of the JNDIView MBean operations. This view should look similar to that shown in Figure 3.7.
The list operation dumps out the JBoss server JNDI namespace as an html page using a simple text view. As an example, invoking the list operation for the default JBoss-2.4.1 distribution server produced the view shown in Figure 3.8.Figure 3.6 The HTTP JMX agent view of the configured JBoss MBeans.
Figure 3.7 The HTTP JMX MBean view of the JNDIView MBean.
Figure 3.8 The HTTP JMX view of the JNDIView list operation output.