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

Protocol Versions

The LDAP is available as version 2 and version 3. As discussed in the Comparison of the LDAP and JNDI Models (in the Tips for LDAP Users trail) lesson, the two versions differ and many features (such as referrals and pluggable authentication mechanisms) that are part of version 3 are not available in version 2. But for the most part, when you use the JNDI to access the LDAP service, you will see no difference between the two versions.

Sun's LDAP service provider supports both versions, The selection of which protocol to use depends primarily on which version the LDAP server supports. By default, the LDAP provider first uses version 3 to communicate with the specified LDAP server. If the server does not support that version, then the LDAP provider attempts to communicate by using version 2. The LDAP provider handles the selection automatically, so seldom does the client need to explicitly request that a particular version be used.

Only in a few circumstances would you want to explicitly specify the protocol version. One is if the LDAP server with which you want to communicate fails to indicate that it does not support version 3. Some public servers exhibit this behavior, and an attempt to communicate with them by using version 3 results either in a hung client (because the server does not respond to the version) or a protocol error (because the server responds with an incorrect error code). Or, you might want to specify the version explicitly if you want your program to use only that version and to fail if the contacted server does not support the version. For example, your program might need to make updates to the server's published schema; this makes sense only for version 3.

To specify the protocol version, you use the "java.naming.ldap.version" environment property. Here is an example that asks for version 2 of the protocol.

// Set up the environment for creating the initial context
Hashtable env = new Hashtable(11);
env.put(Context.PROVIDER_URL, "ldap://localhost:389/o=JNDITutorial");

env.put("java.naming.ldap.version", "2");

// Create the initial context
DirContext ctx = new InitialDirContext(env);

// ... do something useful with ctx

To ask for version 3, simply replace the 2 with a 3, as follows:

env.put("java.naming.ldap.version", "3");

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