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.0 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:

• Check for matches during an extensible match search

• Sort results for an extensible match search by using a sort control

• Maintain an index to speed an extensible match search (optional)

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.

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.