6 Creating Custom Comparators for the OHMPI Match Engine

Custom Comparator Overview

Creating a custom matching comparator for the OHMPI Match Engine requires coding the processing and validation logic for the comparator in Java. The OHMPI Match Engine provides the interfaces and supporting Java classes you need to implement in order to incorporate the comparators into a master person index application.

The OHMPI Match Engine framework consists of two modules. The real-time module stores the basic logic for the matching comparators. The design-time module stores all of the configuration logic for the comparators, including parameter validations, data source definitions, and curve adjustment logic. The two pieces are pulled together by the configuration in the comparators list file (comparatorsList.xml). For each custom comparator package you create, you need to create a comparators list file.

You can define the following information in the comparators list for each comparator you create.

• A code that is used to reference the comparator in the match configuration file (matchCOnfigFile.cfg).

• The class that defines the comparator logic.

• Parameters for the comparator. Parameter values are entered in the match configuration file for any entries that reference the comparator.

• Any classes from which the comparator class inherits.

• Data sources that provide additional information to the comparator during the match process.

• Whether to use curve adjustment logic for the comparator.

After you create the package, you can import the custom comparators into NetBeans using the easy import function of Oracle Healthcare Master Person Index. When you import the files, OHMPI automatically validates the files and merges the comparators list information into the comparators list for the application. You can then add and configure entries in matchConfigFile.cfg that reference the comparator, which makes the comparator available to be used in the match string.

About the Comparator Package

After you register your custom comparators and you create and compile the comparators and any configuration classes, you need to package the files in a JAR file so they are available for import into NetBeans. For optimal usage, it is best to package all similar comparators in a unique JAR file. You can create single packages for each comparator, or combine them into one package.

The JAR file includes the following:

• The comparator Java classes

• The comparators list file (comparatorsList.xml)

• Any parameter validation classes (only if the comparators take parameters)

• Any data source loading or validation classes (only if the comparators use external data files)

• Any curve adjustment classes (only if the comparators use curve adjustment for weight calculation)

For the JAR file to have the correct structure, the comparatorsList.xml file should be at the same level as the com folder that contains the Java classes.

Step 1: Create the Custom Comparator Java Class

The first step to creating custom comparators is defining the matching logic in custom comparator Java classes that are stored in the real-time module of the OHMPI Match Engine. Follow these guidelines when creating the class:

• Create a working directory that will contain all the Java packages and the comparators list file for the new comparators.

• The Java classes need to implement com.sun.mdm.matcher.comparators.MatchComparator.java interface, located in Matcher.jar. This class includes the methods described below.

Once you create the Java classes, continue to Step 2: Register the Comparator in the Comparators List.

Step 2: Register the Comparator in the Comparators List

In order to include new comparators in a master person index application, you need to create a comparators list file defining the configuration of the comparators. When you import the comparator package into the master person index application, this file is read and the entries are added to the comparators list for the project.

Below is a sample comparators list file. Note that the first comparator includes all possible configurations (parameters, dependency classes, data sources, and curve adjust). Most comparators will not be that complex. The second comparator class defines two comparators, Approx and Adjust.

<?xml version="1.0" encoding="UTF-8"?>
<comparators-list xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation="comparatorsList.xsd">
    <group description="New group of comparators" 
     path="com.mycomparators.matchcomparators">
        <comparator description="New Exact Comparator">
            <className>NewExactComparator</className>
            <codes>
                <code description="New Exact Comparator" name="Exact" />
            </codes>
            <params>
              <param description="Fixed length" name="length" 
               type="java.lang.Integer" />
              <param description="Data type" name="dataType" 
               type="java.lang.String" />
            </params>
            <data-sources>
              <datasource description="Serial numbers" type="java.io.File" />
            </data-sources>
            <dependency-classes>
              <dependency-class matchfield="Serial" 
               name="com.genericcomparaotrs.StringComparator" />
            </dependency-classes>
            <curve-adjust status="true" />
        </comparator>
       <comparator description="New Approximate Comparator">
            <className>NewApproxComparator</className>
            <codes>
                <code description="New approximate comparator" name="Approx" />
                <code description="New adjustable comparator" name="Adjust" />
            </codes>
        </comparator>
     </group>               
</comparators-list>

Step 3: Define Parameter Validations (Optional)

If your custom comparators take parameters, you should create a Java class that validates the parameter properties. You need to perform this step if you defined parameters for the comparator in comparatorsList.xml. You do not need to create this file in the same package as the Java comparator class, but for packaging purposes, create it in the same working folder.

Step 4: Define Data Source Handling (Optional)

If your custom comparators use external data sources to provide additional information for matching weight calculations, you need to create a Java class that lets you load the file to memory or have real-time access to the data file content. You can also define validations to perform. You do not need to create this file in the same package as the Java comparator class, but for packaging purposes, create it in the same working folder.

You need to perform this step if you defined lines similar to the following in comparatorsList.xml:

<data-sources>
   <datasource description="Serial numbers" type="java.io.File" />
</data-sources>

Step 5: Define Curve Adjustment or Linear Fitting (Optional)

If your custom comparators use curve adjustment or linear fitting to adjust matching weight calculations, you need to create a Java class that defines the curve. You do not need to create this file in the same package as the Java comparator class, but for packaging purposes, create it in the same working folder.

You need to perform this step if you defined the following line in comparatorsList.xml for the comparator:

<curve-adjust status="true" />

Step 6: Compile and Package the Comparator

Before you perform these steps, make sure you have completed Step 1: Create the Custom Comparator Java Class through Step 5: Define Curve Adjustment or Linear Fitting (Optional).

When you are finished defining all the Java classes for the comparators and have registered each comparator in your comparators list file, you can compile the Java code and package the files into a JAR file that you can then import into a master person index application. Compile the classes using the compiler of your choice.

To package the files, create a temporary directory and copy the comparators list file to the directory. Copy all the class folders and files to the same directory. The top level of the temporary directory should include comparatorsList.xml and a com folder (which contains all the Java classes). Create a JAR file of the directory. For more information about the JAR package, see About the Comparator Package.

After you compile and package the comparator, continue to Step 7: Import the Comparator Package Into Oracle Healthcare Master Person Index.

Step 7: Import the Comparator Package Into Oracle Healthcare Master Person Index

You need to import the new comparators into NetBeans to make them available to all master person index applications or only the current application.

Step 8: Configure the Comparator in the Match Configuration File

After you import custom comparators, you need to add them to the match configuration file (matchConfigFile.cfg) and define the matching configuration. This makes the comparator available for use in the master person index match string. For information about this file, see Understanding the OHMPI Match Engine Match Configuration File. For instructions on modifying the file, see the Oracle Healthcare Master Person Index Configuration Guide.