Sun Java System Directory Server Enterprise Edition 6.2 Developer's Guide

Chapter 1 Before You Start Writing Plug-Ins

This chapter helps you to decide whether to implement a server plug-in. It also explains what to do next if you choose to implement a plug-in.

This chapter covers the following topics:

When to Implement a Server Plug-In

Many Sun Java System Directory Server native product features rely on server plug-ins. Plug-ins are libraries of functions that are registered with the server to perform key parts of specific directory service operations.

The Directory Server plug-in API provides an interface to add server capabilities that are not in the current releases of the product. If you must add server capabilities because a required feature has not yet been implemented, the plug-in API might render that enhancement possible. If you can instead use standard features of the product, avoid creating a plug-in.

Maintaining Plug-Ins

Be aware that creating your own plug-in links your software solution to a specific product release. The plug-in API can evolve from release to release to accommodate new features. As you choose to upgrade to take advantage of new features, you might need to update your Directory Server plug-ins.

You can use the header files with class libraries solely to create and distribute programs to interface with the Software’s APIs. You can also use libraries to create, then distribute program “plug-ins” to interface with the Software’s plug-in APIs. You cannot 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 request that you reproduce the problem after turning your custom plug-ins off.

Sun Services

Sun Services can help you make the right deployment decisions. Sun Services can also help you to 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 that the client has requested. Yet 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, the Directory Server front end decodes the request. The core server handles the decoded request, calling the necessary back end functions to find or store entries, for example. The primary function of the Directory Server back end is to retrieve and store entries. Unless abandoned, however, a client request results in a response originating in the back end. The front end formats the response and sends it to the client.

The following figure illustrates how client request data moves through Directory Server.

Figure 1–1 Client Request Processing

Diagram shows how Directory Server receives, processes,
and responds to a client application request.

As a rule, plug-ins register functions to be called by Directory Server at specific steps of processing the client request. A plug-in has a specific type, such as preoperation or postoperation. A preoperation plug-in registers functions that handle incoming requests before the requests are processed in the server. For example, a preoperation plug-in can register a pre-bind function that is called before the core server begins processing the client bind. The pre-bind function might redefine how the client authenticates to Directory Server, enabling authentication against an external database. A postoperation plug-in registers functions that are called after a request is processed. For example, a postoperation plug-in might register a post-modification function that is called to log the information about the modification request. Example Uses 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 that are triggered for internal Directory Server operations. Internal operations are initiated not by client requests, but by Directory Server or by another plug-in called by Directory Server. Exercise caution when manipulating internal operation data.

The following table summarizes when Directory Server calls documented plug-in function types.

Table 1–1 Server Plug-In Types

Plug-In Type 

When Called 

Entry store-fetch 

Immediately before writing a directory entry to or immediately after reading a directory entry from the directory database 

type: ldbmentryfetchstore

Extended operation 

For processing an LDAP v3 extended operation 

type: extendedop

Internal postoperation 

After completing an operation initiated by Directory Server, for which no corresponding client request exists 

type: internalpostoperation

Internal preoperation 

Before performing an operation initiated by Directory Server, for which no corresponding client request exists 

type: internalpreoperation

Matching rule 

When finding search result candidates based on an extensible match filter for search operations only 

type: matchingrule

Object 

Depends on the functions that are registered. (This type is generic and is used to register other types) 

type: object

Password check 

When performing a strong check on a userPassword value to add or modify

type: passwordcheck

Password storage scheme 

When storing an encoded userPassword value that cannot be decrypted

type: pwdstoragescheme

Postoperation 

After completing an operation requested by a client 

type: postoperation

Preoperation 

Before performing an operation requested by a client 

type: preoperation

The following figure illustrates where in the processing sequence Directory Server calls some of the plug-in types described in Table 1–1.

Figure 1–2 Plug-In Entry Points

Diagram identifies points in client request processing
where plug-ins may be called.

Notice that postoperation return codes do not affect Directory Server processing.

The plug-in type and plug-in configuration information are typically specified statically in a configuration entry.

You can include multiple plug-ins in a single shared library, but you must specify individual, server-specific configuration entries for each plug-in that is registered statically. This means that if you want preoperation and postoperation functions, you typically write two plug-ins. Then you register each plug-in with Directory Server. Both plug-ins can be contained in the same shared library. Both plug-ins can communicate private data across the same operation or connection, as well, using the interface provided. You can also write one plug-in that initializes other plug-ins, if that configuration 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.

The following figure shows multiple plug-ins that reside in the same library.

Figure 1–3 Multiple Plug-Ins in a Shared Library

Diagram shows multiple plug-ins of different types may
be linked in a single shared library.

Each plug-in includes a registration routine that is called by Directory Server at startup. The registration routine explicitly registers each plug-in function with Directory Server.


Caution – Caution –

Plug-in libraries are linked with Directory Server. Plug-ins execute in the same memory address space as Directory Server. Plug-ins have direct access to data structures used by Directory Server. As a result, plug-ins can corrupt memory used by Directory Server. Such memory corruption can result in database corruption. Due to this danger, never use an untested plug-in on a production Directory Server.

Furthermore, Directory Server runs as a multi threaded process. Code you write for a plug-in must be reentrant. Multiple threads can call your entry point simultaneously. These threads can be rescheduled at any time.


Example Uses

To select 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.

Table 1–2 Plug-In Example Uses by Type

Plug-In Type 

Example Uses 

Entry store-fetch 

Encoding and decoding entire plug-in entries 

Auditing or logging each entry as the entry is written to disk 

Extended operation 

Adding client services that are not available in LDAP v3 such as digital signatures in requests and responses 

Internal postoperation 

Auditing results of internal operations initiated by another plug-in 

Internal preoperation 

Preempting internal operations initiated by another plug-in 

Matching rule 

Offering enhanced sounds-like matching for directory searches 

Object 

Developing a plug-in that registers a group of other plug-ins with Directory Server 

Password check 

Forcing new passwords to conform to corporate policy for password syntax 

Password storage scheme 

Using a custom algorithm for password encryption instead of one of the algorithms supported by the standard product 

Postoperation 

Associating alerts and alarms sent after particular operations 

Auditing changes to specific entries 

Performing cleanup after an operation 

Preoperation 

Handling custom authentication methods external to the directory 

Forcing syntax checking for attribute values before adding or modifying an entry 

Adding attributes to or deleting attributes from a request 

Preprocessing client request content to translate requests from legacy applications 

Approving or rejecting the content of a client modification request before processing the request 

The list of example uses is by no means exhaustive, but is instead intended to help you brainstorm solutions.

Where to Go From Here

Most of the rest of this guide is devoted to examples that demonstrate the specific plug-in types.


Caution – Caution –

Never develop plug-ins on a production server, but instead on a test server used specifically for plug-in development.


Prepare Your Development Environment

You might not have installed Sun Java System Directory Server software. You might not have installed development software for the C language for use during plug-in development. Install the software 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 4, Getting Started With Directory Server Plug-Ins. The chapter helps you to build a simple plug-in, and to register the plug-in with Directory Server.

Upgrade Existing Plug-Ins

If you maintain plug-ins developed for a previous release of Directory Server, refer to Chapter 2, Changes to the Plug-In API Since Directory Server 5.2 and Chapter 3, Changes to the Plug-In API From Directory Server 4 to Directory Server 5.2 for information about what has changed.

Try a Sample Plug-In

Examples for several plug-in types are provided with the product in install-path/examples Subsequent chapters demonstrate the use of the sample plug-ins.

Find Details

See Part II, Directory Server Plug-In API Reference for details about particular data structures, functions, and parameter block semantics.