Using DirContextSourceFactory

Have you ever wondered why it is a snap to use a JDBC DataSource in a servlet container but not a JNDI DirContext? Now it is!

Most containers support resource management for a webapp through factories by implementing javax.naming.spi.ObjectFactory. This factory implements the interface and allows you to use the DirContextSource in your webapp but fully managed by your container.

Contents:

Resource Declaration Examples

There are two ways to declare a resource in Apache Tomcat: as a global resource and then linking into the webapp or as a local resource within an application.

As a Global Resource

Navigate in your server.xml to /Server/GlobalNamingResources and add the following element:

[…]
<GlobalNamingResources>
  <!-- Add this -->
  <Resource name="ldap/name" type="net.sf.michaelo.dirctxsrc.DirContextSource"
    factory="net.sf.michaelo.dirctxsrc.DirContextSourceFactory"
    urls="ldap://hostname ldap://another-hostname" />
</GlobalNamingResources>
[…]

This resource still needs to be linked to your application. Open or create your app's context.xml and add:

<Context>
[…]
  <!-- Add this -->
  <ResourceLink global="ldap/name" name="ldap/localName"
    type="net.sf.michaelo.dirctxsrc.DirContextSource" />
[…]
</Context>

Now you have successfully linked a global resource to your webapp. It is now ready to use.

As a Local Resource

If you prefer to keep resources locally, open or create your app's context.xml and add:

<Context>
[…]
  <!-- Add this -->
  <Resource name="ldap/localName" type="net.sf.michaelo.dirctxsrc.DirContextSource"
    factory="net.sf.michaelo.dirctxsrc.DirContextSourceFactory"
    urls="ldap://hostname ldap://another-hostname" />
[…]
</Context>

Using the Resource

It takes now only a few lines of code to get that resource in your app's code, regardless whether it's a global or a local resource.

From a Regular Webapp

Open a class and go ahead as follows:

[…]
Context initCtx = new InitialContext();
Context envCtx = (Context) initCtx.lookup("java:comp/env");
DirContextSource contextSource = (DirContextSource) envCtx.lookup("ldap/localName");
// try and catch block omitted for the sake of brevity,
// handle NamingException appropriately
DirContext context = contextSource.getDirContext();
// Perform operations
context.close();
[…]

Configuration Options

The factory offers the same configuration properties as the builder class but exposes them as XML attributes. I.e., this factory is fully backed by the Builder class. Due to this fact, please note the following prior setting up a resource:

  1. Though all values are passed as strings, they are preprocessed by the builder before building the actual context source. Incompatible values will cause an exception to be thrown.
  2. Multivalued attributes may be passed separated by a whitespace character.
  3. Omitted attributes are subject to the default values set by the builder. See Javadoc for details.
Attribute Builder Equivalent Optional Valid Value(s) Description
name – no any string A name for this resource relative to java:comp/env.
type – no net.sf.michaelo.dirctxsrc.DirContextSource Preset class name of this resource.
factory – no net.sf.michaelo.dirctxsrc.DirContextSourceFactory Preset class name of this resource's factory.
contextFactory contextFactory(String) yes Any class (name) implementing the InitialContentFactory interface See Javadoc.
urls Builder(String…) no A list of LDAP URLs See Javadoc.
auth auth(Auth) yes none or gssapi (case-insensitive) See Javadoc.
loginEntryName loginEntryName(String) yes any string See Javadoc.
objectFactories objectFactories(String…) yes A list of classes (names) implementing either the ObjectFactory or the DirObjectFactory interface See Javadoc.
mutualAuth mutualAuth(boolean) yes true or false (boolean) See Javadoc.
qop qop(String…) yes A list of auth, auth-int and/or auth-conf See Javadoc.
debug debug(boolean) yes true or false (boolean) See Javadoc.
retries retries(int) yes positive integer See Javadoc.
retryWait retryWait(int) yes positive integer See Javadoc.
binaryAttributes binaryAttributes(String…) yes A list or attribute names See Javadoc.
referral referral(String) yes ignore, throw or follow See Javadoc.
additionalProperties additionalProperty(String, Object) yes A list of properties and values Semicolon-separated name value pairs: name=value;name2=value2;…. See Javadoc.