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:


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

The case exact matching rule plug-in OID 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


Parameter Block Identifier 


Filter factory 



Filter index, used to check an index for matches 


Not required 

Filter match 



Filter match reset 


If filter must be reset for reuse 

Filter object destructor 


If needed to free memory 



Not required 

Indexer factory 


Not required 

Indexer object destructor 


If needed to free memory 

Plug-in initialization function 

Not applicable, but instead specified in configuration settings 


Server shutdown (cleanup) function 


Not required 

Server startup function 


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.