Controls and Extensions

Connection Request Controls

Connection request controls are used whenever a connection needs to be established or re-established to an LDAP server. They do not affect other nonconnection related LDAP operations, such as "search" or "modify." Conversely, context request controls do not affect connection-related LDAP operations. For example, setting a context's request controls to be a critical Sort control won't affect an LDAP "bind" operation.

You initialize a context's connection request controls by using the InitialLdapContext constructor. Here is an example.

// Create the control to use when establishing connection
Control[] connCtls = new Control[]{new SampleRequestControl()};

// Create the initial context
LdapContext ctx = new InitialLdapContext(env, connCtls);

This example creates a new InitialLdapContext instance with connection controls initialized to SampleRequestControl. Once set, the connection controls (SampleRequestControl) are inherited by all contexts derived from this context. Notice that this differs from context request controls, which are not inherited.

Changing the Connection Request Controls

You can change the connection request controls of a context by using LdapContext.reconnect(). This method establishes a new connection to the LDAP server by using the request controls supplied as the argument. If the argument is null, then no request controls are sent. Subsequent to the connection's being established, any implicit reconnections, for example those resulting from updated credentials, will also use the same controls.

reconnect() affects only the connection that is being used by the Context instance on which reconnect() is invoked. Any new Context instances that are derived from the context inherit the new connection controls, but contexts that previously shared the connection remain unchanged. That is, a context's connection request controls must be explicitly changed and is not affected by changes to another context's connection request controls.

In the following example, an InitialLdapContext is created with a SampleRequestControl. The context's connection request controls are then set to null via a call to reconnect(), with null as the argument.

// Create the control to use when establishing the connection
Control[] connCtls = new Control[]{new SampleRequestControl()};

// Create the initial context
LdapContext ctx = new InitialLdapContext(env, connCtls);

// Do something useful with ctx

// Reconnect by using no controls
ctx.reconnect(null);

Finding Out the Connection Request Controls That Are in Effect

To find out the connection request controls that are in effect for a context, you use LdapContext.getConnectControls(). Here is an example that initializes the connection request controls to be SampleRequestControl and then checks the controls by using getConnectControls().

// Create the control to use when establishing the connection
Control[] connCtls = new Control[]{new SampleRequestControl()};

// Create the initial context
LdapContext ctx = new InitialLdapContext(env, connCtls);

// Check the controls in effect for connection establishment
Control[] reqCtls = ctx.getConnectControls();

Here is the output produced by this example.

SampleRequestControl@1fa4d891
com.sun.jndi.ldap.ManageReferralControl@1fa4d59d

This output shows both the control that was added (SampleRequestControl) as well as a Manage Referral control that the LDAP provider sends when referrals are being ignored (that is, the Context.REFERRAL environment property is unset or was set to "ignore"). To stop the LDAP provider from sending this control, you must set the Context.REFERRAL property to "throw" or "follow". See the Referrals lesson for details.

Initializing a Referral Context's Connection Request Controls

Referrals are discussed in detail in the Referrals lesson. When you follow referrals automatically, the referral context inherits both the connection and the context request controls from the original context. When you handle referrals manually, you have the option of setting both controls for each referral context.

Here is an example. The referral context's connection request controls are set by passing the controls to LdapReferralException.getReferralContext(Hashtable, Control[]). After the referral context has been created, the context request controls are set via a call to LdapContext.setRequestControls().

...
} catch (LdapReferralException e) {
    Control[] connCtls = new Control[]{new SampleRequestControl()};
    Control[] ctxCtls = new Control[]{
	new SortControl(new String[]{"cn"}, Control.CRITICAL)
    };

    // Get the referral context by using connection controls
    // when establishing the connection by using the referral
    ctx = (LdapContext) e.getReferralContext(env, connCtls);

    // Set the context request controls for the referral context
    ctx.setRequestControls(ctxCtls);
}

Controls and Extensions