| 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