public class InitialLdapContext
extends InitialDirContext
implements LdapContext

This class is the starting context for performing LDAPv3-style extended operations and controls.

See javax.naming.InitialContext and javax.naming.InitialDirContext for details on synchronization, and the policy for how an initial context is created.

Request Controls

When you create an initial context (InitialLdapContext), you can specify a list of request controls. These controls will be used as the request controls for any implicit LDAP "bind" operation performed by the context or contexts derived from the context. These are called connection request controls. Use getConnectControls() to get a context's connection request controls.

The request controls supplied to the initial context constructor are not used as the context request controls for subsequent context operations such as searches and lookups. Context request controls are set and updated by using setRequestControls().

As shown, there can be two different sets of request controls associated with a context: connection request controls and context request controls. This is required for those applications needing to send critical controls that might not be applicable to both the context operation and any implicit LDAP "bind" operation. A typical user program would do the following:

InitialLdapContext lctx = new InitialLdapContext(env, critConnCtls);
lctx.setRequestControls(critModCtls);
lctx.modifyAttributes(name, mods);
Controls[] respCtls =  lctx.getResponseControls();

It specifies first the critical controls for creating the initial context (critConnCtls), and then sets the context's request controls (critModCtls) for the context operation. If for some reason lctx needs to reconnect to the server, it will use critConnCtls. See the LdapContext interface for more discussion about request controls.

Service provider implementors should read the "Service Provider" section in the LdapContext class description for implementation details.

public InitialLdapContext()
                   throws NamingException

public InitialLdapContext(Hashtable<?,?> environment,
                          Control[] connCtls)
                   throws NamingException

Constructs an initial context using environment properties and connection request controls. See javax.naming.InitialContext for a discussion of environment properties.

This constructor will not modify its parameters or save references to them, but may save a clone or copy. Caller should not modify mutable keys and values in environment after it has been passed to the constructor.

connCtls is used as the underlying context instance's connection request controls. See the class description for details.

public ExtendedResponse extendedOperation(ExtendedRequest request)
                                   throws NamingException

public LdapContext newInstance(Control[] reqCtls)
                        throws NamingException

Creates a new instance of this context initialized using request controls. This method is a convenience method for creating a new instance of this context for the purposes of multithreaded access. For example, if multiple threads want to use different context request controls, each thread may use this method to get its own copy of this context and set/get context request controls without having to synchronize with other threads.

The new context has the same environment properties and connection request controls as this context. See the class description for details. Implementations might also allow this context and the new context to share the same network connection or other resources if doing so does not impede the independence of either context.

public void reconnect(Control[] connCtls)
               throws NamingException

Reconnects to the LDAP server using the supplied controls and this context's environment.

This method is a way to explicitly initiate an LDAP "bind" operation. For example, you can use this method to set request controls for the LDAP "bind" operation, or to explicitly connect to the server to get response controls returned by the LDAP "bind" operation.

This method sets this context's connCtls to be its new connection request controls. This context's context request controls are not affected. After this method has been invoked, any subsequent implicit reconnections will be done using connCtls. connCtls are also used as connection request controls for new context instances derived from this context. These connection request controls are not affected by setRequestControls().

Service provider implementors should read the "Service Provider" section in the class description for implementation details.

public Control[] getConnectControls()
                             throws NamingException

public void setRequestControls(Control[] requestControls)
                        throws NamingException

Sets the request controls for methods subsequently invoked on this context. The request controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

This removes any previous request controls and adds requestControls for use by subsequent methods invoked on this context. This method does not affect this context's connection request controls.

Note that requestControls will be in effect until the next invocation of setRequestControls(). You need to explicitly invoke setRequestControls() with null or an empty array to clear the controls if you don't want them to affect the context methods any more. To check what request controls are in effect for this context, use getRequestControls().

public Control[] getRequestControls()
                             throws NamingException

public Control[] getResponseControls()
                              throws NamingException

Retrieves the response controls produced as a result of the last method invoked on this context. The response controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

These response controls might have been generated by a successful or failed operation.

When a context method that may return response controls is invoked, response controls from the previous method invocation are cleared. getResponseControls() returns all of the response controls generated by LDAP operations used by the context method in the order received from the LDAP server. Invoking getResponseControls() does not clear the response controls. You can call it many times (and get back the same controls) until the next context method that may return controls is invoked.