Miscellaneous
Adding Support for Controls and Extensions
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.
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.
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 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.
- Connection request control. Affects how a connection is created
- Context request control. Affects context methods
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 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.
Miscellaneous