JNDI DirContextSource – Using DirContextSourceFactory

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
- As a Global Resource
- As a Local Resource
Using the Resource
- From a Regular Webapp
Configuration Options

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:

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.
Multivalued attributes may be passed separated by a whitespace character.
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.