JBoss.org Community Documentation
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-service.xml
configuration file. The configurable attributes of the ExternalContext
service are as follows:
JndiName : The JNDI name under which the external context is to be bound.
RemoteAccess
: 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 can 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.
CacheContext
: The 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.
InitialContext
: The 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
.
Properties
: The Properties
attribute contains the JNDI properties for the external InitialContext
. The input should be the text equivalent to what would go into a jndi.properties
file.
PropertiesURL
: This set the jndi.properties
information for the external InitialContext
from an external properties file. This is either a URL, string or a classpath resource name. Examples are as follows:
file:///config/myldap.properties
http://config.mycompany.com/myldap.properties
/conf/myldap.properties
myldap.properties
The MBean definition below shows a binding to an external LDAP context into the JBoss JNDI namespace under the name external/ldap/jboss
.
<!-- Bind a remote LDAP server --> <mbean code="org.jboss.naming.ExternalContext" name="jboss.jndi:service=ExternalContext,jndiName=external/ldap/jboss"> <attribute name="JndiName">external/ldap/jboss</attribute> <attribute name="Properties"> java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory java.naming.provider.url=ldap://ldaphost.jboss.org:389/o=jboss.org java.naming.security.principal=cn=Directory Manager java.naming.security.authentication=simple java.naming.security.credentials=secret </attribute> <attribute name="InitialContext"> javax.naming.ldap.InitialLdapContext </attribute> <attribute name="RemoteAccess">true</attribute> </mbean>
With this configuration, you can access the external LDAP context located at ldap://ldaphost.jboss.org:389/o=jboss.org
from within the JBoss VM using the following code fragment:
InitialContext iniCtx = new InitialContext(); LdapContext ldapCtx = iniCtx.lookup("external/ldap/jboss");
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 InitialContext
<!-- Bind the /usr/local file system directory --> <mbean code="org.jboss.naming.ExternalContext" name="jboss.jndi:service=ExternalContext,jndiName=external/fs/usr/local"> <attribute name="JndiName">external/fs/usr/local</attribute> <attribute name="Properties"> java.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory java.naming.provider.url=file:///usr/local </attribute> <attribute name="InitialContext">javax.naming.IntialContext</attribute> </mbean>
This configuration describes binding a local file system directory /usr/local
into the JBoss JNDI namespace under the name external/fs/usr/local
.
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");
Note that you need to use the Sun JNDI service providers, which must be downloaded from http://java.sun.com/products/jndi/serviceproviders.html. The provider JARs should be placed in the server configuration lib
directory.