Protocol Versions

There are two versions of the LDAP: LDAP v2 and LDAP v3. As discussed in the Comparisons lesson, there are differences between the two versions, and many features (such as referrals and pluggable authentication mechanisms) that are part of the LDAP v3 are not available in the LDAP v2. But for the most part, when you use the JNDI to access the LDAP service, you will see no difference between the two versions of the protocol.
Sun's LDAP service provider supports both versions of the protocol, and the selection of which protocol to use is based primarily on which version the LDAP server supports. By default, the LDAP provider attempts first to communicate with the specified LDAP server using version 3. If the server does not support version 3, the LDAP provider then attempts to communicate using version 2. Since the LDAP provider takes care of the selection automatically, there is seldom a need for the client to explicitly request that a particular version be used.
There are only a few reasons why you would 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 using version 3 results either in a hung client (because the server does not respond to version 3) or a protocol error (because the server responds with an incorrect error code). The other reason you might want to specify the version explicitly is if you want your program to use only version 3 (or version 2) and to fail if the contacted server does not support that version. For example, your program might need to make updates to the server's published schema, and this only makes sense 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 environment for creating initial context
Hashtable env = new Hashtable(11);
env.put(Context.INITIAL_CONTEXT_FACTORY, 
    "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://localhost:389/o=JNDITutorial");

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

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

// ... do something useful with ctx
To ask for version 3, simply replace the "2" with "3", as follows:
env.put("java.naming.ldap.version", "3");

Miscellaneous