Previous | Next | Trail Map | Tips for LDAP Users | Frequently Asked Questions

Contexts

What is the relationship between a context and the connection to the LDAP server?

When you create an InitialContext(in the API reference documentation) or InitialDirContext(in the API reference documentation) using the LDAP service provider, a connection is set up immediately with the target LDAP server. Any contexts and NamingEnumerations(in the API reference documentation) that are derived from this initial context share the same connection as the initial context.

For example, if you invoke Context.lookup()(in the API reference documentation) or Context.listBindings()(in the API reference documentation) from the initial context and got back other contexts, all those contexts would share the same connection. If you create a new initial context, it would have its own connection.

How do I close the connection to the LDAP server?

To close the connection to the server, you invoke Context.close()(in the API reference documentation) on all contexts originated from the initial context that created the connection. Make sure that all NamingEnumeration have been completed. For those context and enumeration objects that are no longer in scope, the Java runtime system will eventually garbage collect them, thus cleaning up the state that a close() would have done. If you want to force the garbage collection, you can use the following code:
Runtime.getRuntime().gc();
Runtime.getRuntime().runFinalization();

Is the context safe for multithreaded access? Or do I need to lock/synchronize access to a context?

The answer depends on the implementation because the Context(in the API reference documentation) and DirContext(in the API reference documentation) interfaces do not specify synchronization requirements. Sun's LDAP implementation is optimized for single-threaded access. If you have multiple threads accessing the same context, each thread needs to lock the context when using it. This also applies to any NamingEnumeration that are derived from the same context. However, multiple threads can access different contexts (even ones derived from the same initial context) concurrently without locks.

Why does the LDAP provider ignore my security environment properties if I do not set the Context.SECURITY_CREDENTIALS(in the API reference documentation)(java.naming.security.credentials) property or set it to the empty string?

If you supply an empty string, an empty byte array, or null to the Context.SECURITY_CREDENTIALS environment property, anonymous bind will occur regardless of the setting of the other security-related environment properties. This is because the LDAP requires the password to be nonempty for doing any type of authentication and automatically converts the authentication to "none" if one is not supplied.

I keep getting CommunicationException(in the API reference documentation) when I try to create an initial context. Why?

If you are using Netscape Directory Server 3.11, you must set the Context.SECURITY_AUTHENTICATION(in the API reference documentation)(java.naming.security.authentication) property to "simple". The LDAP service provider by default uses CRAM-MD5, which is not supported by the Netscape server without additional software installation.

I'm seeing some strange behavior, how do I find out what's really going on?

Try using the com.sun.naming.ldap.trace.ber environment property. If the value of this property is an instance of java.io.OutputStream, trace information about BER buffers sent and received by the LDAP provider are written to that stream. If the property's value is null, no trace output is written.

For example, the following code will send the trace output to System.err.

env.put("com.sun.naming.ldap.trace.ber", System.err);

How do I use a different authentication mechanism such as Kerberos?

Currently you cannot. Sun's LDAP provider currently does not support Kerberos or other authentication mechanisms except for CRAM-MD5 and simple. Sun plans to provider a more flexible way of supporting different authentication mechanisms in the future.


Previous | Next | Trail Map | Tips for LDAP Users | Frequently Asked Questions