Download the JDK
Search the Tutorials
Hide the TOC
Trail: Java Naming and Directory Interface(TM).
Lesson: Advanced Topics for LDAP Users
Section: Connection Management
Advanced Topics for LDAP Users
LDAP v3
JNDI as an LDAP API
How LDAP Operations Map to JNDI APIs
How LDAP Error Codes Map to JNDI Exceptions
Security
Modes of Authenticating to LDAP
Authentication Mechanisms
Anonymous
Simple
SASL
Digest-MD5
SSL and Custom Sockets
More LDAP Operations
LDAP Compare
Search Results
LDAP Unsolicited Notifications
Connection Management
Creation
Closing
Pooling
Configuration
Frequently Asked Questions
Home Page > Java Naming and Directory Interface(TM). > Advanced Topics for LDAP Users
Creation

> 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 Connection 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.

> 1. By passing a URL as the name argument to the initial context. When an LDAP or LDAPS URL is pass as a name parameter to the initial context, the information in the URL is used to create a new connection to the LDAP server, regardless of whether the initial context instance itself has a connection to an LDAP server. In fact, the initial context might not be connected to any server. See the JNDI Tutorial for more information on how URLs are used as names.
> 2. Another way that a connection is created is by use of a `Reference`. When a `Reference` containing an LDAP or LDAPS URL is passed to `NamingManager.getObjectInstance()` or `DirectoryManager.getObjectInstance()`, a new connection is created using information specified in the URL.
> 3. Finally, when a referral is followed manually or automatically, the information in the referral is used to create a new connection. See the JNDI Tutorial for information on referrals.

> #### Shared Connections

> `Context` instances and `NamingEnumeration`s 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 (i.e., no `Context`s 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.

> #### Creation Timeouts

> 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.

Previous page: Connection Management
Next page: Closing