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

How Matching Rule Plug-Ins Work

This section summarizes what matching rule plug-ins are and how Directory Server handles them.

What a Matching Rule Is

A matching rule defines a specific way to compare attribute values that have a given syntax. In other words, a matching rule defines how potentially matching attributes are compared.

Every matching rule is identified by a unique object identifier (OID) string. A client application that requests a search can specify the matching rule OID in the search filter. The OID indicates to Directory Server how to check for a match of two attribute values.

In practice, a client application might want only entries with attribute values that match the value provided exactly. The sample plug-in demonstrates how you might implement a solution for that case. Another client might want to sort entries according to the rules for a given locale. Directory Server actually uses a matching rule plug-in to handle locale—specific matching.

Chapter 11, Directory Server Internationalization Support, in Sun Java System Directory Server Enterprise Edition 6.2 Reference includes a list of matching rules. Directory Server supports the rules for internationalized searches. You can also view the list by searching the default schema.


$ ldapsearch -h localhost -p 1389 -b cn=schema cn=schema matchingRules

Requesting a Matching Rule

To request a custom matching rule on a specific attribute, a client application includes the matching rule OID in the search filter. LDAP v3 calls these search filters extensible match filters. An extensible match filter looks like the following:

(cn:2.5.13.5:=Quentin)

This filter tells the server to search for Quentin in the common name (CN) of the entries by using matching rule 2.5.13.5. The matching rule happens to be a case exact match.

The case exact matching rule plug-in OID 2.5.13.5 enables Directory Server to perform the search correctly. Directory Server calls code in this matching rule plug-in to check for matches during a search. The server also uses the code to generate indexes that accelerate case exact searches. The indexes also help to sort entries found during such searches.

What a Matching Rule Plug-In Does

A matching rule plug-in can provide code to do the following:

To enable these capabilities, the plug-in implements matching and indexing routines that Directory Server calls to handle requests involving the particular matching rule.

The plug-in also implements factory functions that specify which routine to call when handling a particular matching rule. As a result, a plug-in can support multiple matching rules. Yet, plug-ins implementing only one matching rule also require factory function code to wrap indexing and matching routines. A plug-in therefore requires many lines of code and several functions to handle even a minimal matching rule.

The following table shows all the functions that a matching rule plug-in can implement.

Table 11–1 Functions Defined in Matching Rule Plug-Ins

Type 

Parameter Block Identifier 

Required? 

Filter factory 

SLAPI_PLUGIN_MR_FILTER_CREATE_FN

Required 

Filter index, used to check an index for matches 

SLAPI_PLUGIN_MR_FILTER_INDEX_FN

Not required 

Filter match 

SLAPI_PLUGIN_MR_FILTER_MATCH_FN

Required 

Filter match reset 

SLAPI_PLUGIN_MR_FILTER_RESET_FN

If filter must be reset for reuse 

Filter object destructor 

SLAPI_PLUGIN_DESTROY_FN

If needed to free memory 

Indexer 

SLAPI_PLUGIN_MR_INDEX_FN

Not required 

Indexer factory 

SLAPI_PLUGIN_MR_INDEXER_CREATE_FN

Not required 

Indexer object destructor 

SLAPI_PLUGIN_DESTROY_FN

If needed to free memory 

Plug-in initialization function 

Not applicable, but instead specified in configuration settings 

Required 

Server shutdown (cleanup) function 

SLAPI_CLOSE_FN

Not required 

Server startup function 

SLAPI_START_FN

Not required 

Refer to Part II, Directory Server Plug-In API Reference for details about parameter block identifiers that you can use with matching rule plug-ins.