Custom Plug-ins for Master Index Custom Transaction Processing

You can add custom processing to the master index application by adding your own code to new Java classes in the EJB project for the master index application. These classes are called custom plug-ins. This ability allows you to tailor how messages are processed by the master index application. Plug-ins can be used to customize field validations, update policies, match processing logic, and record retrieval, and to create custom components for the master index application, such as custom phonetic encoders, block pickers, or query builders. You can create as many classes as you need to carry out the custom processes.

The following sections describe custom plug-ins that define custom processing. These are explained more fully in Oracle Java CAPS Master Index Configuration Reference .

• Master Index Update Policy Plug-ins – Define custom processing logic to perform against the resulting record of a transaction before it is stored in the database.

• Master Index Field Validation Plug-ins – Define validations to perform against specific fields, such as checking the local ID length and format.

• Master Index Field Masking Plug-ins – Define how the values for sensitive fields are hidden on the MIDM from users who do not have permission to view them.

• Master Index Match Processing Logic Plug-ins – Define custom logic based on predefined decision points for how records are matched during a transaction.

• Master Index Custom Plug-in Exception Processing – Define how exceptions are handled by the custom plug-ins you create.

Master Index Update Policy Plug-ins

For the primary transactions performed by the master index application, you can define additional custom processing to perform against the record that results from a transaction. The policies you define are invoked by the Update Manager and are applied to the resulting records after they are processed by the survivor calculator. The modifications made to a record by an update policy determine how the record is stored in the database. By creating custom plug-ins, you can create additional Java classes to support the update policies you define.

Update policies are specified in the UpdatePolicy section of update.xml, and there are several different types. Each policy modifies an enterprise object (class com.sun.mdm.index.objects.EnterpriseObject) and must implement com.sun.mdm.index.update.UpdatePolicy, which contains one method, applyUpdatePolicy. The syntax is as follows:

public EnterpriseObject applyUpdatePolicy(EnterpriseObject before, EnterpriseObject after)

This method throws two exceptions: com.sun.mdm.index.master.UserException and com.sun.mdm.index.objects.exception.ObjectException.

Enterprise Merge Policy

The enterprise merge policy defines additional processing to perform after two enterprise objects are merged. The processing defined in this policy acts against the surviving record of the merge. In the EnterpriseMergePolicy element in update.xml, enter the fully qualified name of this custom plug-in.

Enterprise Unmerge Policy

The enterprise unmerge policy defines additional processing to perform after an unmerge transaction occurs. The processing defined in this policy acts against the surviving record of the merge transaction that was unmerged. In the EnterpriseUnmergePolicy element of update.xml, enter the fully qualified name of this custom plug-in.

Enterprise Update Policy

The enterprise update policy defines additional processing to perform after a record is updated. In the EnterpriseUpdatePolicy element of update.xml, enter the fully qualified name of this custom plug-in.

Enterprise Create Policy

The enterprise create policy defines additional processing to perform after a new record is inserted into the master index database. In the EnterpriseCreatePolicy element of update.xml, enter the fully qualified name of this custom plug-in.

System Merge Policy

The system merge policy defines additional processing to perform after two system objects are merged. The processing defined in this file acts against the surviving enterprise record of the merge (and not the system record). In the SystemMergePolicy element of update.xml, enter the fully qualified name of this custom plug-in.

System Unmerge Policy

The system unmerge policy defines additional processing to perform after system objects are unmerged. The processing defined in this file acts against the surviving enterprise record of the system merge transaction that was unmerged. In the SystemUnmergePolicy element in update.xml, enter the fully qualified name of this custom plug-in.

Undo Assumed Match Policy

The undo assumed match policy defines additional processing to perform after an assumed match transaction is reversed. In the UndoAssumeMatchPolicy element in update.xml, enter the fully qualified name of this custom plug-in.

Master Index Field Validation Plug-ins

You can define validations to be performed against certain fields before information is entered into the master index database. Once you create the custom plug-ins containing the validation logic, enter the name of the plug-in in validation.xml. Follow these guidelines when implementing custom field validators.

• The custom validation classes must implement com.sun.mdm.index.objects.validation.ObjectValidator.

• The exception thrown is com.sun.mdm.index.objects.validation.exception.ValidationException.

One default field validator, validate-local-id, is provided to validate system and local ID fields before processing data into the database. This is described in Oracle Java CAPS Master Index Configuration Reference .

Master Index Field Masking Plug-ins

There might be instances where you want to mask certain data in records from general users of the Master Index Data Manager and only allow access by administrators. To do this, you can create a custom plug-in that displays asterisks (or other symbols) in place of the field values on the MIDM. Once you define the custom plug-in, specify the name of the custom plug-in Java class in the object-sensitive-plug-in-class element of midm.xml).

Master Index Match Processing Logic Plug-ins

You can implement custom plug-ins that customize the way the execute match methods process data into the master index application. When a record is entered into the master index system, match processing is performed by calling one of the following “execute match” functions from the MasterController class.

• executeMatch

• executeMatchUpdate

• executeMatchDupRecalc

• executeMatchUpdateDupRecalc

• executeMatchGui (this method is only called by the MIDM)

These methods contain standard logic for processing records through the master index database, weighting incoming records against existing records, and then using those weights to determine whether to insert a new record or update an existing record. In addition to configuring the match processing logic in master.xml, you can customize certain aspects of the processing logic using custom plug-ins that contain functions found in the ExecuteMatchLogics class.

Custom Match Processing Logic Methods

There are five decision branches where custom logic can be inserted. At specific points in match processing, the execute match methods look for the value of the methods listed below. For more information about the methods, see the Javadocs for the master index. These methods are contained in the ExecuteMatchLogics class in the package com.sun.mdm.index.master. For information about where the decision points are reached in the processing logic and how to change the logic, see Oracle Java CAPS Master Index Processing Reference. The following methods specify the custom logic.

• bypassMatching - Indicates whether to perform the match process on incoming records or to bypass the match process.

• disallowAdd - Indicates whether an incoming message can be inserted as a new record.

• disallowUpdate - Indicates whether an incoming record can update an existing record.

• rejectAssumedMatch - Indicates whether to accept or reject an assumed match of two records.

• rejectUpdate - Indicates whether to accept or reject an update to an existing record.

Custom Match Processing Logic Plug-in Requirements

The custom plug-ins you create to define custom execute match logic must extend the ExecuteMatchLogics class. In addition, the following classes must be imported into the custom plug-in.

• com.sun.mdm.index.objects.SystemObject

• com.sun.mdm.index.objects.EnterpriseObject

• com.sun.mdm.index.objects.exception.ObjectException

• com.sun.mdm.index.master.ExecuteMatchLogics

• com.sun.mdm.index.master.CustomizationException

Custom Match Processing Configuration

If you create a custom plug-in that defines custom processing logic for the execute match methods, you must specify those custom plug-ins in master.xml in the master index project. If you create a plug-in for customizing logic in the execute match methods used by the back-end, specify the name of that class in the logic-class element. If you create a plug-in for the MIDM, specify the name of that class in the logic-class-gui element. For example:

<logic-class>com.sun.mdm.index.user.CustomCollaboration</logic-class>
<logic-class-gui>com.sun.mdm.index.user.CustomMIDM</logic-class-gui>

For more information about master.xml, see Oracle Java CAPS Master Index Configuration Reference .

Master Index Custom Plug-in Exception Processing

If a custom plug-in throws an exception of the class ObjectException or SystemObjectException, multiple stack traces are logged in the server log file, which can make operational management tasks more difficult. For cases where you do not want stack traces to be logged, configure your custom plug-ins to throw exceptions of the class UserException or one of its derived classes (DataModifiedException or ValidationException). This is useful for user errors on the Master Index Data Manager (MIDM). When one of these exceptions is thrown, no stack trace is entered in the log file but an error message still appears on the MIDM.

For more information about these exception classes, see the Javadocs for Oracle Java CAPS Master Index.