Previous | Next | Trail Map | Tips for LDAP Users | Connections

Connection Pooling

Note: Connection pooling is supported only on the Java 2 SDK, v 1.4.1, and later releases.
The Connection Creation section described when connections are created. It described how several Context instances can share the same connection. In this type of sharing, operations from the different Context instances are multiplexed onto the same connection. You can control the degree of sharing by deciding when to create a new initial context and when to obtain a derived Context instance from an existing Context instance. This type of connection sharing satisfies most applications.

Another type of connection sharing supported by the LDAP service provider is called connection pooling. In this type of sharing, the LDAP service provider maintains a pool of (possibly) previously used connections and assigns them to a Context instance as needed. When a Context instance is done with a connection (closed or garbage collected), the connection is returned to the pool for future use. Note that this form of sharing is sequential: a connection is retrieved from the pool, used, returned to the pool, and then, retrieved again from the pool for another Context instance.

The pool of connections is maintained per Java runtime system. As such, it can be used by all of the ways in which a connection can be created, as described in the Connection Creation section. For example, a connection required for processing a referral can use a pooled connection, as can a connection required for constructing an InitialContext. For some situations, this can improve performance significantly. For example, only one connection is required for processing a search response that contains four referral references to the same LDAP server if connection pooling is used. Without connection pooling, such a scenario would require four separate connections.

A pooled connection can be shared by multiple Context instances, using the same model described in the Connection Creation section. The only difference is that the underlying connection might have come from a pool instead of being created fresh.

The rest of this lesson describes in more detail how to use connection pooling.

How to Use Connection Pooling

You request connection pooling by adding the property, "com.sun.jndi.ldap.connect.pool" to the environment properties passed to the initial context constructor. Here is an example.
// Set up environment for creating initial context
Hashtable env = new Hashtable(11);
env.put(Context.PROVIDER_URL, "ldap://localhost:389/o=JNDITutorial");

// Enable connection pooling
env.put("com.sun.jndi.ldap.connect.pool", "true");

// Create one initial context (Get connection from pool)
DirContext ctx = new InitialDirContext(env);

// do something useful with ctx

// Close the context when we're done
ctx.close();   // Return connection to pool

// Create another initial context (Get connection from pool)
DirContext ctx2 = new InitialDirContext(env);

// do something useful with ctx2

// Close the context when we're done
ctx2.close();   // Return connection to pool

This example creates two initial contexts in succession. The second initial context will reuse the connection used by the first. To run this program and observe how the connections are retrieved and returned to the pool, use the following command line.

#java -Dcom.sun.jndi.ldap.connect.pool.debug=fine UsePool
This should produce output that looks as follows.
Create com.sun.jndi.ldap.LdapClient@5d173[localhost:389]
Use com.sun.jndi.ldap.LdapClient@5d173
{ou=ou: NewHires, objectclass=objectClass: top, organizationalUnit}
Release com.sun.jndi.ldap.LdapClient@5d173
Use com.sun.jndi.ldap.LdapClient@5d173
{ou=ou: People, objectclass=objectClass: top, organizationalunit}
Release com.sun.jndi.ldap.LdapClient@5d173

You can decide when and where to use pooling by including or omitting the "com.sun.jndi.ldap.connect.pool" property, and thus control pooling on a per-context basis. In the previous example, if you removed this property from the environment properties before creating the second initial context, the second initial context would not use a pooled connection. The presence of this property in the environment also determines whether pooled connections are used for referral handling and processing of LDAP URLs passed to the initial context. For example, when this property is present in the environment when the provider is processing a referral, the provider will use a pooled connection for the referral.

The LDAP provider keeps track of whether a connection is being used through indications from the application. It assumes that an application that is maintaining an open context handle is using the connection. Therefore, in order for the LDAP provider to properly manage the pooled connections, you must be diligent about invoking Context.close() on contexts that you no longer need.

Bad connections are automatically detected and removed from the pool by the LDAP provider. The probability of a context ending up with a bad connection is the same regardless of whether connection pooling is used.

Creation Timeout

The pool of connections maintained by the LDAP service provider may be limited in size; this is described in detail in the Connection Pooling Configuration section. When connection pooling has been enabled and no pooled connection is available, the client application will block, waiting for an available connection. You can use the "com.sun.jndi.ldap.connect.timeout" environment property to specify how long to wait for a pooled connection. If you omit this property, the application will wait indefinitely.

This same property is also used to specify a timeout period for establishment of the LDAP connection, as described in the Connection Creation section.

When Not to Use Pooling

Pooled connections are intended to be reused. Therefore, if you plan to perform operations on a Context instance that might alter the underlying connection's state, then you should not use connection pooling for that Context instance. For example, if you plan to invoke the Start TLS extended operation on a Context instance, or plan to change security-related properties (such as "" or "") after the initial context has been created, you should not use connection pooling for that Context instance because the LDAP provider does not track any such state changes. If you use connection pooling in such situations, you might be compromising the security of your application.

Previous | Next | Trail Map | Tips for LDAP Users | Connections