Sun ONE Directory Server 5.2 Plug-In API Programming Guide |
If you are not yet familiar with Sun ONE Directory Server software, take the time to read Sun ONE Directory Server Getting Started Guide.
Next, read this short chapter. It helps you decide whether to implement a server plug-in, and what to do next if you choose to implement one.
When to Implement a Server Plug-In
Many Sun ONE Directory Server native product features rely on server plug-ins, libraries of functions registered with the server to perform key parts of specific directory service operations. In publishing the Sun ONE Directory Server plug-in API, the Directory Server team offers you an interface to extend server capabilities for needs not met in the currently available releases of the product.
Enhancing Server Capabilities
If you must enhance server capabilities because some required feature such as custom authentication, encryption, validation, pattern matching, or notification has not yet been implemented in the product, the plug-in API may render that enhancement possible. If you can instead use standard features of the product, avoid creating a plug-in.
Maintaining Plug-Ins
Know that creating your own plug-in links your software solution to a specific product release. The plug-in API may evolve from release to release to accommodate new features. As you choose to upgrade and take advantage of new features, you may need to update your Directory Server plug-ins to account for the changes, as described in the license.
You may use the header files and class libraries solely to create and distribute programs to interface with the Software's APIs. You may also use libraries to create and distribute program "plug-ins" to interface with the Software's plug-in APIs. You may not modify the header files or libraries. You acknowledge that Sun makes no direct or implied guarantees that the plug-in APIs will be backward-compatible in future releases of the Software. In addition, you acknowledge that Sun is under no obligation to support or to provide upgrades or error corrections to any derivative plug-ins.
When providing technical support, Sun technical support personnel will request that you reproduce the problem after disactivating your custom plug-ins.
Sun Professional Services
For information about what Sun Professional Services has to offer, refer to
Sun Professional Services can help you make the right deployment decisions, and can help you deploy the right solution for your specific situation, whether or not the solution includes custom plug-ins.
How Plug-Ins Interact With the Server
All client requests to Directory Server instances undergo particular processing sequences. The exact sequence depends on the operation requested, but overall the sequences are similar. The way plug-ins handle requests is independent of how the client encodes the request. In other words, client request data appears essentially the same to plug-ins regardless of the client access protocol used to communicate with Directory Server.
In general, client request processing proceeds as follows. First, Directory Server frontend decodes the request. The core server handles the decoded request, calling the necessary backend functions to find or store entries for example. The primary function of the Directory Server backend is to read entries from and write entries to the database. Unless abandoned, a client request results in a response originating in the backend. The frontend formats the response and sends it to the client.
Figure 1-1 illustrates how client request data moves through Directory Server.
Figure 1-1    Client Request Processing
As a rule, plug-ins register functions to be called by Directory Server at specific points in the client request processing sequence. A plug-in has a specific type, such as preoperation or postoperation. A preoperation plug-in registers functions handling incoming requests before they are processed in the server. For example, a preoperation plug-in may register a pre-bind function called before the core server begins processing the client bind. The pre-bind function might redefine the way the client authenticates to Directory Server, enabling authentication against an external database. A postoperation plug-in registers functions called after a request is processed. For example, a postoperation plug-in may register a post-modification function called to log the information about the modification request. Table 1-2 provides examples for other plug-in types.
The two internal operation plug-in types form an exception to the rule that functions are called to perform client request processing. Internal operation plug-ins implement functions triggered for internal Directory Server operations. Internal operations are initiated not by client requests, but instead by Directory Server itself or by another plug-in called by Directory Server. Exercise great caution when manipulating internal operation data!
Table 1-1 summarizes when Directory Server calls documented plug-in function types.
Figure 1-2 illustrates where in the processing sequence Directory Server calls several of the plug-in types described in Table 1-1.
Figure 1-2    Plug-In Entry Points
Notice that post-operation return codes do not affect Directory Server processing.
Plug-in type and other configuration information is typically specified statically in a configuration entry.
You may include multiple plug-ins in a single shared library, but you must specify individual, server-specific configuration entries for each plug-in registered statically. This means that if you want both pre- and post-operation functions, you typically write two plug-ins and register each with Directory Server. Both plug-ins may be contained in the same shared library. Both plug-ins may communicate private data across the same operation or connection, as well, using the interface provided. It is also possible to write one plug-in that initializes other plug-ins if that is required for your deployment.
The sample plug-ins delivered with the product follow the principle of building all plug-ins into one library, then registering plug-ins individually.
Figure 1-3 shows multiple plug-ins residing in the same library.
Figure 1-3    Multiple Plug-Ins in a Shared Library
Each plug-in includes a registration routine, called by Directory Server at startup. The registration routine explicitly registers each plug-in function with Directory Server.
Example Uses
Selecting the right plug-in type for the job is an art, rather than a science. The following table suggests example uses for documented plug-in types.
The list of example uses is by no means exhaustive, but is instead intended to help you brainstorm solutions.
Where to Go From Here
We devote most of the rest of this guide to examples demonstrating the specific plug-in types.
Tip Never develop plug-ins on a production server, but instead on a test server used specifically for plug-in development.
Prepare Your Development Environment
If you have not yet installed Sun ONE Directory Server software and have not installed C language development tools for use during plug-in development, install them now. Without development tools and a functioning Directory Server, you cannot use the examples discussed here.
Learn About Plug-In Development
If you have not yet written a plug-in for the current release, refer to Chapter 3 "Getting Started With Directory Server Plug-Ins" for a demonstration of how to build a simple plug-in and register it with Directory Server.
Upgrade Existing Plug-Ins
If you already have plug-ins developed for a previous release and need to upgrade them for use with the current release, refer to Chapter 2 "What's New."
Try a Sample Plug-In
Examples for several plug-in types are provided with the product under ServerRoot/plugins/slapd/slapi/examples/. Subsequent chapters demonstrate the use of the sample plug-ins.
Find Details
Refer to the Sun ONE Directory Server Plug-In API Reference for details about particular data structures, functions, and parameter block semantics.