UnboundID Server SDK

Ping Identity
UnboundID Server SDK Documentation
Getting Started with the UnboundID Server SDK

Intercepting Operations in the Server

One of the most common reasons for developing an extension is to perform some processing whenever a given kind of request is received in the server. There are a number of ways that this can be achieved using the server SDK, but in most cases the best way to achieve this would be to use a plugin or a change subscription handler. Alternately, if you want to intercept operations passing through a Directory Proxy Server instance, then you can use a proxy transformation.

Intercepting Operations with a Plugin

Plugins provide the greatest degree of flexibility in intercepting operations because they can intercept any kind of operation, and you can choose any or all of several points in the operation processing at which to inject your custom processing. For most types of operations, there are plugin points at the following times:

For search operations, you can also intercept and alter search result entries and references, and you can optionally prevent some or all of those entries and/or references from being returned. Conversely, during pre-parse, pre-operation, and post-operation phases of a search operation, you can construct additional entries and/or references to be returned to the client. For all types of operations except abandon and unbind, you can construct intermediate response messages to be returned to the client.

It is possible for a plugin to intercept operations at multiple phases during their processing if desired. For example, you could have a plugin that performs processing during both the pre-parse and post-response phases. If you need to do this and want to preserve state information to share between those phases, then you can achieve that result by attaching data to the operation that can be accessed during a later phase of processing. To attach arbitrary objects to an operation, use the ActiveOperationContext.setAttachment method, providing a unique name along with the data to be attached. You can then get information that has been attached to the operation using the OperationContext.getAttachment method using the name that you provided during the earlier phase of processing.

Note that in the Directory Proxy Server, the pre-operation and post-operation phases of a plugin will not be processed for operations that pass through the Directory Proxy Server and are forwarded to one or more backend servers, although this processing will occur for operations targeting data in the Directory Proxy Server instance itself (e.g., the configuration, schema, and monitor data). If you want to alter requests and responses passing through the Directory Proxy Server, then you should use a proxy transformation rather than a plugin.

Intercepting Operations in a Change Subscription Handler

Change subscription handlers provide the ability to perform processing for an add, delete, modify, or modify DN after other processing has completed for that operation. In many ways, change subscription handlers are very similar to post-response plugins invoked only for write operations. There are, however, two notable differences:

If you want to be notified of changes occurring within the server and don't need to alter those changes in any way, then a change notification listener may be simpler and/or more efficient than a plugin designed to achieve the same result (particularly if you want to define multiple sets of criteria to use to trigger the change subscription handler). However, if you may need to alter the contents of a request or response, or if you need to perform processing for other types of operations, then a plugin is a more appropriate choice.

Intercepting Operations in a Proxy Transformation

Proxy transformations provide a mechanism for intercepting and/or altering requests as they pass through the Directory Proxy Server to one or more backend servers. They will only be invoked for operations passing through the server and and not for operations targeting data local to the Directory Proxy Server instance (e.g., configuration, schema, and monitor data).

For operations processed through an Directory Proxy Server, proxy transformations provide the only means of altering the response that will be returned to the client, as post-operation plugins will not be invoked for such operations. There is some overlap between pre-parse plugins and request transformations because both can be used to alter the contents of a request that will ultimately be forwarded to a backend server. However, proxy transformations can be easily configured so that they are only used for data targeting certain portions of the DIT, or for operations requested by a particular set of clients, and it is even relatively simple to have different sets of transformations applied for different sets of clients. If you only want to impact operations passing through the Directory Proxy Server, then it is generally recommended that you use proxy transformations rather than plugins to achieve the desired result.