1 Understanding Basic Oracle Unified Directory Plug-in Concepts

This chapter contains the following sections:

1.1 Determining Whether You Should Implement an OUD Plug-In

The Oracle Unified Directory (OUD) plug-in API provides the means to extend existing Directory Server functionality. You may want to develop a plug-in if you have a very specific directory server requirement that OUD cannot address straight out of the box. For example, OUD plug-ins have been used successfully to achieve the following:

  • LDAP error code and error message writing

  • On-demand password migration

  • Authentication using multiple password types

  • Operation routing based on criteria in user entry

Some of these plug-ins have played a role in helping Oracle customers to seamlessly migrate to OUD. These are just examples of how Directory Server functionality can be enhanced by customizing LDAP operations and programatically manipulating results.

As you analyze the benefits and costs of developing your own OUD plug-in, consider the following:

  • To minimize potential points of failure in your directory deployment, you should develop your own OUD plug-in only when no existing OUD functionality, nor any combination of OUD features, can achieve the results you require.

  • When upgrading to a later release, you will have to determine whether your custom plug-in is still relevant in light of new OUD functionality that may evolve over time. Moreover, you may have to update your plug-in to ensure backward or forward compatibility with later releases of OUD.

1.2 OUD Plug-Ins and OUD Workflows

An OUD plug-in-in can be seen as a new type of OUD workflow element. Workflows and workflow elements are fundamental building blocks within the OUD directory architecture. For information about how workflows and workflow elements work within the Oracle Unified Directory architecture, see the Oracle Fusion Middleware Administrator's Guide for Oracle Unified Directory.

An OUD plug-in can be inserted into any OUD workflow element tree. The following are typical tasks that an OUD plug-in can perform within a workflow element tree:

  • Intercept LDAP requests from the previous workflow elements in the chain, and keep the option to change or extend them.

  • Intercept LDAP entries and results from next workflow element in the chain.

  • Stack and leverage other workflow elements delivered out of the box with OUD.

  • Invoke a plug-in upon receipt of LDAP requests, and after the routing decision is done by the workflow.

The following figure illustrates a typical OUD workflow containing a Naming Context workflow and a DN Renaming workflow element. An OUD plug-in is inserted downstream from these building blocks, and upstream from a remote backend workflow element.

Description of wfevsplugins-2.png follows
Description of the illustration ''wfevsplugins-2.png''

Once you have developed a number of OUD plug-ins, you can form a plug-in chain within an OUD workflow.

1.3 OUD Plug-In Implementation Points

OUD plug-ins interact with the OUD core server through the following sets of implementation points:

  • Administrative plug-in management: startup, shutdown, status, and configuration changes

  • LDAP operation handling

  • The context that is the main interface between the plug-in and the core directory server as it is used to log requests and to create instances of objects manipulated by the plug-in API

The implementation points for managing the plug-in are defined in the oracle.oud.plugin.ManagedPlugin interface:

  • The initializePlugin() method is invoked when the plug-in is initialized at server startup time.

  • The finalizePlugin() method is invoked when the plug-in is stopped.

  • The handleConfigurationChange() method is invoked whenever the plug-in configuration is changed. See also Section 3.1.4, "Making Dynamic OUD Plug-In Configuration Changes."

Implementation points for intercepting LDAP operations are defined in the oracle.oud.plugin.RequestManager interface. See also Section 3.6, "Internal Operations."

1.4 About Oracle Unified Directory Plug-Ins

An Oracle Unified Directory plug-in is an implementation of oracle.oud.plugin.ManagedPlugin which is formed from the following three Java interfaces: oracle.oud.RequestManager, oracle.oud.plugin.Plugin, and oracle.oud.plugin.ManagedPlugin.


Defines a method for each type of operation defined by the LDAP protocol. The method named handleAdd is called each time the plug-in is involved in an LDAP add operation. Similar methods exist for bind, compare, delete, modify, modifyDN, and search operations. Exceptions exist for the abandon and unbind operations; these two types of request cannot be intercepted.


Associates a name to the plug-in that is unique per instance. Identifying plug-ins is helpful when a plug-in routes the received requests to a particular plug-in among multiple plug-ins.


Defines the life cycle of the plug-in. The life cycle begins with the initialization of the plug-in when the server starts or the plug-in is created. Once initialized, a plug-in is able to receive configuration changes. When the server is shut down or the plug-in is removed from the server configuration, the plug-in is finalized.

An OUD plug-in can be followed by one or more plug-ins in a process chain. The most common case is an OUD plug-in that is followed by only one plug-in. This type of plug-in receives requests, may perform extra actions such as logging or modifying the received requests, and then forwards the requests to the next plug-in. When the LDAP operation returns a response, similar actions can be performed.

A plug-in that has no subsequent plug-ins in the process chain is responsible for storing the entries manipulated by the LDAP requests. The storage can be local or remote. In both cases, the plug-in is responsible for assigning the result of the received LDAP requests.

A plug-in that is followed by multiple plug-ins in the process chain is the most difficult case. This type of plug-in is used for only complex architectures that include distribution or load balancing. For example, this type of plug-in might be used for routing bind requests on dedicated plug-ins, and routing other LDAP operations on other plug-ins.

The OUD plug-in API provides a default implementation of the oracle.oud.plugin.ManagedPlugin Java interface that is the abstract class oracle.oud.plugin.AbstractPlugin. This class provides a default implementation of a plug-in that performs no action apart from forwarding the received requests to its next plug-in the chain of processing. The default implementation assumes that the plug-in has at least one subsequent plug-in. But you can overwrite appropriate methods to change the default behavior if necessary.You should make your plug-in implementation derive from the oracle.oud.plugin.AbstractPlugin class. This will optimize backward compatibility in case the implemented Java interface is changed.