The Java Tutorials have been written for JDK 8. Examples and practices described in this page don't take advantage of improvements introduced in later releases and might use technology no longer available.
See Java Language Changes for a summary of updated language features in Java SE 9 and subsequent releases.
See JDK Release Notes for information about new features, enhancements, and removed or deprecated options for all JDK releases.
There are several ways in which a connection is created. The most common way is from the creation of an initial context. When you create an InitialContext, InitialDirContext, or InitialLdapContext by using the LDAP service provider, a connection is set up immediately with the target LDAP server named in the Context.PROVIDER_URL property. Each time an initial context is created, a new LDAP connection is created. See the Pooling section for information on how to change this behavior.
If the property value contains more than one URL, then each URL is tried in turn until one is used to create a successful connection. The property value is then updated to be the successful URL. See the JNDI Tutorial for an example of how to create an initial context using a list of URLs.
There are three other direct ways in which a connection is created.
Context instances and NamingEnumerations that are derived from one Context instance share the same connection until changes to one of the Context instances make sharing no longer possible. For example, if you invoke Context.lookup(), Context.listBindings() or DirContext.search() from the initial context and get back other Context instances, then all of those Context instances will share the same connection.
Here is
an example
.
// Create initial context DirContext ctx = new InitialDirContext(env); // Get a copy of the same context Context ctx2 = (Context)ctx.lookup(""); // Get a child context Context ctx3 = (Context) ctx.lookup("ou=NewHires");
In this example, ctx, ctx2, and ctx3 will share the same connection.
Sharing is done regardless of how the Context instance came into existence. For example, a Context instance obtained by following a referral will share the same connection as the referral.
When you change a Context instance's environment properties that are related to a connection, such as the principal name or credentials of the user, the Context instance on which you make these changes will get its own connection (if the connection is shared). Context instances that are derived from this Context instance in the future will share this new connection. Context instances that previously shared the old connection are not affected (that is, they continue to use the old connection).
Here is
an example
that uses two connections.
// Create initial context (first connection) DirContext ctx = new InitialDirContext(env); // Get a copy of the same context DirContext ctx2 = (DirContext)ctx.lookup(""); // Change authentication properties in ctx2 ctx2.addToEnvironment(Context.SECURITY_PRINCIPAL, "cn=C. User, ou=NewHires, o=JNDITutorial"); ctx2.addToEnvironment(Context.SECURITY_CREDENTIALS, "mysecret"); // Method on ctx2 will use new connection System.out.println(ctx2.getAttributes("ou=NewHires"));
ctx2 initially shares the same connection with ctx. But when its principal and password properties are changed, it can no longer use ctx's connection. The LDAP provider will automatically create a new connection for ctx2.
Similarly, if you use LdapContext.reconnect() to change the Context instance's connection controls, the Context instance will get its own connection if the connection was being shared.
If the Context instance's connection was not being shared (that is, no Contexts have been derived from it), then changes to its environment or connection controls will not cause a new connection to be created. Instead, any changes relevant to the connection will be applied to the existing connection.
Not all connection creations are successful. If the LDAP provider cannot establish a connection within a certain timeout period, it aborts the connection attempt. By default, this timeout period is the network (TCP) timeout value, which is in the order of a few minutes. To change the timeout period, you use the "com.sun.jndi.ldap.connect.timeout" environment property. The value of this property is the string representation of an integer representing the connection timeout in milliseconds.
Here is
an example
.
// 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"); // Specify timeout to be 5 seconds env.put("com.sun.jndi.ldap.connect.timeout", "5000"); // Create initial context DirContext ctx = new InitialDirContext(env); // do something useful with ctx
In this example, if a connection cannot be created within 5 seconds, an exception will be thrown.
If the Context.PROVIDER_URL property contains more than one URL, the provider will use the timeout for each URL. For example, if there are 3 URLs and the timeout has been specified to be 5 seconds, then the provider will wait for a maximum of 15 seconds in total.
See the Connection Pooling section for information on how this property affects connection pooling.