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 non-connection related LDAP operations such as "search" or "modify" operations. Conversely, context request controls do not affect connection-related LDAP operations. For example, when you set a context's request controls to be a critical sort control, that won't affect any LDAP "bind" operation.

A context's connection request controls are initialized using the InitialLdapContext constructor . Here is an example:

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

// Create 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 is different from context requeset controls, which are not inherited.

Changing the Connection Request Controls

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

reconnect() affects only the connection 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 by using a call to reconnect() with null as the argument.

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

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

// Do something useful with ctx

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

Finding Out the Connection Request Controls In Effect

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

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

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

// Check what controls are 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

It shows both the control that we've added (SampleRequestControl), and a "manage referral" control that the LDAP provider sends when referrals are being ignored (that is, the Context.REFERRALenvironment property is unset or has been set to "ignore"). To stop the LDAP provider from sending this control, you must set the Context.REFERRAL property to "throw" or "follow".

Initializing a Referral Context's Connection Request Controls

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

Here is an example. The referral context's connection request controls are set by passing the controls to the LdapReferralException.getReferralContext(Hashtable, Control[]) method.

The context request controls are set by calling LdapContext.setRequestControls() after the referral context has been created.

...
} catch (LdapReferralException e) {
    Control[] connCtls = new Control[]{new SampleRequestControl()};
    Control[] ctxCtls = new Control[]{new SampleRequestControl()};

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

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

Controls and Extensions