Previous | Next | Trail Map | Building a Service Provider | 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 (in the Tips for LDAP Users trail) 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(in the API reference documentation) 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(in the API reference documentation) interface via Control.getEncodedValue()(in the API reference documentation). The decoding of response controls is done by the response control implementations, which the context implementation selects via ControlFactory.getControlInstance()(in the API reference documentation).

Two types of request controls are available.

Connection request controls are initialized by the API user's argument to the InitialLdapContext constructor(in the API reference documentation) or LdapReferralException.getReferralContext()(in the API reference documentation) and modified via LdapContext.reconnect()(in the API reference documentation). 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()(in the API reference documentation) and modified via LdapContext.setRequestControls()(in the API reference documentation).

"Extended" Operations

An API user invokes an "extended" operation by creating an ExtendedRequest(in the API reference documentation) and then invoking extendedOperation()(in the API reference documentation). 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()(in the API reference documentation). When the server returns the corresponding extended response, the context implementation passes the response to ExtendedRequest.createExtendedResponse()(in the API reference documentation) 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 ExtendedRequests. 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.

Previous | Next | Trail Map | Building a Service Provider | Miscellaneous