| Miscellaneous

## Adding Support for Controls and Extensions

> > Prerequisite: You should be familiar with LDAP v3 controls and extensions before reading this section. These topics are covered in the Controls and Extensions lesson.

> A service provider typically supports LDAP v3 controls and extensions only when the underlying naming/directory service supports such features. Only the LDAP and LDAP-like services support these features.

> To support controls and extensions, the context implementation must implement the `LdapContext` interface. In addition, how controls and extensions are supported is closely tied to how your implementation processes LDAP requests and responses. This section gives some general hints on how to implement these features.

> #### Controls

> In the LDAP v3, you can send a request control along with any LDAP request and receive a response control along with any LDAP response. Although request and response controls are commonly paired, a one-to-one correspondence between the two is not required. For example, you can receive a response control with an LDAP response without having sent any request control with the corresponding request.

> The context implementation must be able to encode arbitrary request controls (supplied by the API user) with any LDAP request and be able to decode arbitrary response controls that accompany LDAP responses. The encoding of request controls is actually done by the individual implementations of the `Control` interface via `Control.getEncodedValue()`. The decoding of response controls is done by the response control implementations, which the context implementation selects via `ControlFactory.getControlInstance()`.

> Two types of request controls are available.

> - Connection request control. Affects how a connection is created
> - Context request control. Affects context methods
> Connection request controls are initialized by the API user's argument to the `InitialLdapContext` constructor or `LdapReferralException.getReferralContext()` and modified via `LdapContext.reconnect()`. The context implementation must maintain a context's connection request controls in the environment property `"java.naming.ldap.control.connect"` and pass this property on to `Context` instances that it creates. In this way, the derived `Context` instances will inherit the connection controls.

> The context implementation should maintain context request controls on a per `Context` instance basis and not pass them on to derived contexts. Context request controls are initialized by the API user's argument to `LdapContext.newInstance()` and modified via `LdapContext.setRequestControls()`.

> #### "Extended" Operations

> An API user invokes an "extended" operation by creating an `ExtendedRequest` and then invoking `extendedOperation()`. The context implementation is then responsible for encoding the extended request and submitting it as an LDAP "extended" operation to the LDAP server. The encoding is actually done by the individual implementations of the `ExtendedRequest` interface via `ExtendedRequest.getEncodedValue()`. When the server returns the corresponding extended response, the context implementation passes the response to `ExtendedRequest.createExtendedResponse()` to generate a response for the initial caller of `extendedOperation()`.

> From this description, the onus of handling "extended" operations appears to be on the developers of the `ExtendedRequest`s. However, this is true only for "extended" operations that have no effect on the context implementation. It is common for "extended" operations to affect the state of the context implementation. For example, the Start TLS operation enables Transport Layer Security (TLS) on an existing LDAP connection. Adding support for such an operation requires changes to any existing context implementation and likely depends on internal interfaces of the context implementation. So ususally, defining a general framework for handling arbitrary "extended" operations is difficult. Typically, the context implementation would maintain a list of "extended" operations that it would support natively. It would then inspect the object identifier of the extended responses for those operations and modify its behavior accordingly. There really is no good way to handle "extended" operations that it does not know about because it can't tell whether it should ignore or flag the operation.

| Miscellaneous