com.orchestranetworks.addon.mame.service.matching

Interface MatchingOperations

public interface MatchingOperations

Provides matching operations for the EBXâ„¢ Match and Merge Add-on. These operations must be called within a different EBX context, such as a: user service, script/user task, or trigger.

All the matching operations are required to have an activated matching configuration for the table.

The operations allow matching records or values against existing table records. Records that are in a merged or deleted state are not considered. The dataspace is locked during the execution a matching operation to prevent concurrent modification of the data.

Using this class

In order to create an instance of this class, the external program must provide an authenticated session:

  MatchingOperations.getMatchingOperations(session);
  

Performance

To ensure the best performance when matching, please review the Matching performance topic in the Administrator Guide. //

Code Sample

 public class CustomMatchingUserServiceSample implements UserService {
      
     public void setupDisplay(UserServiceSetupDisplayContext context, UserServiceDisplayConfigurator configurator) {

         Session session = context.getSession();
         AdaptationHome dataspace = context.getRepository().lookupHome(HomeKey.parse("BMAME-TEST"));
         Adaptation dataset = dataspace.findAdaptationOrNull(AdaptationName.forName("testMame"));
         AdaptationTable table = dataset.getTable(Path.parse(PathPerson._People.getPathInSchema().format()));

         MatchingOperations matchingOperations = OperationsFactory.getMatchingOperations(session);

         // execute a synchronous matching process to match an EBX record only
                  PrimaryKey myPk = PrimaryKey.parseString("1");
            matchingOperations.matchRecord(table, myPk, "matchingPolicyCode_NameComp");

         // execute an asynchronous matching process to match an entire EBX table
           MatchingProcess matchingProcessTable = matchingOperations.matchTable(table, null);

         // execute an asynchronous matching process to match an entire table
           Request request = table.createRequest();
           RequestSortCriteria sortCriteriaOnPersonFirstName = new RequestSortCriteria();
           sortCriteriaOnPersonFirstName.add(PathPerson._People._FirstName);
           request.setSortCriteria(sortCriteriaOnPersonFirstName);

           MatchingProcess matchingProcessRecords = matchingOperations.matchRecords(table, request, "matchingPolicyCode");

         // execute simulate match on a record
           Adaptation record2 = table.lookupAdaptationByPrimaryKey(PrimaryKey.parseString("2"));

           SimulationResult simulationResult = matchingOperations.simulateMatch(record2, null);

         // execute simulate match on a field node with specific a specific value
           Map <SchemaNode, Object> myMap = new HashMap<>();
           SchemaNode schemaNode = table.getTableNode().getNode(PathPerson._People._LastName);
           myMap.put(schemaNode, "test");

           SimulationResult simulationResultForSpecificValues = matchingOperations.simulateMatch(table, myMap, null);
 

Method Summary

Modifier and Type	Method and Description
MatchingComparator	getComparator(com.onwbp.adaptation.AdaptationTable table, String policyCodeOrNull) TODO @cls: check content
void	matchRecord(com.onwbp.adaptation.AdaptationTable table, com.onwbp.adaptation.PrimaryKey recordPrimaryKey, String policyCodeOrNull) Executes a matching operation on a record against an EBX table.
MatchingProcess	matchRecords(com.onwbp.adaptation.AdaptationTable table, com.onwbp.adaptation.Request request, String policyCodeOrNull) Executes a matching operation with a specific request on a EBX table.
MatchingProcess	matchTable(com.onwbp.adaptation.AdaptationTable table, String policyCodeOrNull) Executes a matching operation on an entire EBX table.
SimulationResult	simulateMatch(com.onwbp.adaptation.Adaptation record, String policyCodeOrNull) Simulates a match record operation.
SimulationResult	simulateMatch(com.onwbp.adaptation.AdaptationTable table, Map<com.orchestranetworks.schema.SchemaNode,Object> values, String policyCodeOrNull) Simulates a match table operation for specific values.

Method Detail

matchRecord

void matchRecord(com.onwbp.adaptation.AdaptationTable table,
                 com.onwbp.adaptation.PrimaryKey recordPrimaryKey,
                 String policyCodeOrNull)
          throws com.orchestranetworks.service.OperationException,
                 com.orchestranetworks.addon.mame.common.InvalidStateException,
                 com.orchestranetworks.addon.mame.common.InvalidParameterException

Executes a matching operation on a record against an EBX table. Note that this method execute a synchronous matching process.

Parameters:

table - An EBX table

recordPrimaryKey - The record on which you want to run matching

policyCodeOrNull - Identifier of the matching policy. Specify null to apply the default matching policy

Throws:

com.orchestranetworks.service.OperationException - When unexpected errors occurs

com.orchestranetworks.addon.mame.common.InvalidParameterException - When there is no record with the primary key 'recordPrimaryKey' in the table, or the 'policyCode' is empty

com.orchestranetworks.addon.mame.common.InvalidStateException - When one of the following errors occur: 1. No matching policy conforms to the input 'policyCode' 2. Matching on the current 'table' is paused 3. Matching policy is found, but inactive

matchTable

MatchingProcess matchTable(com.onwbp.adaptation.AdaptationTable table,
                           String policyCodeOrNull)
                    throws com.orchestranetworks.service.OperationException,
                           com.orchestranetworks.addon.mame.common.InvalidStateException,
                           com.orchestranetworks.addon.mame.common.InvalidParameterException

Executes a matching operation on an entire EBX table. Note that this method execute an asynchronous matching process.

Parameters:

table - An EBX table

policyCodeOrNull - Identifier of the matching policy. Specify null to apply the default matching policy

Returns:

MatchingProcess The information of a matching execution

Throws:

com.orchestranetworks.service.OperationException - When unexpected errors occurs

com.orchestranetworks.addon.mame.common.InvalidParameterException - When at least on of the parameters is not valid

com.orchestranetworks.addon.mame.common.InvalidParameterException - When there is no record with the primary key 'recordPrimaryKey' in the table, or the 'policyCode' is empty

com.orchestranetworks.addon.mame.common.InvalidStateException - When one of the following errors occur: 1. No matching policy conforms to the input 'policyCode' 2. Matching on the current 'table' is paused 3. Matching policy is found, but inactive 4. An asynchronous matching process is already running in the same table

matchRecords

MatchingProcess matchRecords(com.onwbp.adaptation.AdaptationTable table,
                             com.onwbp.adaptation.Request request,
                             String policyCodeOrNull)
                      throws com.orchestranetworks.service.OperationException,
                             com.orchestranetworks.addon.mame.common.InvalidStateException,
                             com.orchestranetworks.addon.mame.common.InvalidParameterException

Executes a matching operation with a specific request on a EBX table. Note that this method execute an asynchronous matching process.

Parameters:

request - EBX Request from a table

policyCodeOrNull - The matching policy code from a matching configuration. Specify null to apply the default matching policy

Returns:

MatchingProcess The information of a matching execution

Throws:

com.orchestranetworks.service.OperationException - When unexpected errors occur

com.orchestranetworks.addon.mame.common.InvalidParameterException - When least one of the 'recordPks' is not found in the table or the 'policyCode' is empty

com.orchestranetworks.addon.mame.common.InvalidStateException - When one of the following errors occur: 1. No matching policy conforms to the input 'policyCode' 2. Matching on the current 'table' is paused 3. Matching policy is found, but inactive 4. An asynchronous matching process is already running in the same table

simulateMatch

SimulationResult simulateMatch(com.onwbp.adaptation.Adaptation record,
                               String policyCodeOrNull)
                        throws com.orchestranetworks.addon.mame.common.InvalidParameterException,
                               com.orchestranetworks.addon.mame.common.InvalidStateException

Simulates a match record operation. When the simulate service is called, matching results are not persisted into the MatchResult table.

Parameters:

record - The record on which we want to perform the simulation to find matches or suspects

policyCodeOrNull - Identifier of the matching policy. Specify null to apply the default matching policy

Returns:

SimulationResult The information of the matching simulation.

Throws:

com.orchestranetworks.addon.mame.common.InvalidParameterException - When there is no record with the primary key 'recordPrimaryKey' in the table, or the 'policyCode' is empty

com.orchestranetworks.addon.mame.common.InvalidStateException - When one of the following errors occur: 1. No matching policy conforms to the input 'policyCode' 2. Matching on the current 'table' is paused 3. Matching policy is found, but inactive

simulateMatch

SimulationResult simulateMatch(com.onwbp.adaptation.AdaptationTable table,
                               Map<com.orchestranetworks.schema.SchemaNode,Object> values,
                               String policyCodeOrNull)
                        throws com.orchestranetworks.addon.mame.common.InvalidParameterException,
                               com.orchestranetworks.addon.mame.common.InvalidStateException,
                               com.orchestranetworks.service.OperationException

Simulates a match table operation for specific values. When the simulate service is called, matching results are not persisted in the MatchResult table.

Parameters:

table - An EBX table

values - A value represents an EBX schema node with a specific value

policyCodeOrNull - The matching policy code from a matching configuration. Specify null to apply the default matching policy

Returns:

SimulationResult The information of the matching simulation.

Throws:

com.orchestranetworks.addon.mame.common.InvalidParameterException - When there is no record with the primary key 'recordPrimaryKey' in the table, or the 'policyCode' is empty

com.orchestranetworks.addon.mame.common.InvalidStateException - When one of the following errors occur: 1. No matching policy conforms to the input 'policyCode' 2. Matching on the current 'table' is paused 3. Matching policy is found, but inactive

com.orchestranetworks.service.OperationException

getComparator

MatchingComparator getComparator(com.onwbp.adaptation.AdaptationTable table,
                                 String policyCodeOrNull)
                          throws com.orchestranetworks.addon.mame.common.InvalidParameterException,
                                 com.orchestranetworks.addon.mame.common.InvalidStateException

TODO @cls: check content

Create a comparator to compare records based on decision tree that configured in matching policy

Parameters:

table - An EBX table

policyCodeOrNull - The matching policy code from a matching configuration. Specify null to apply the default matching policy

Returns:

AdaptationComparator

Throws:

com.orchestranetworks.addon.mame.common.InvalidParameterException - The 'policyCode' is empty

com.orchestranetworks.addon.mame.common.InvalidStateException - When one of the following errors occur: 1. No matching policy conforms to the input 'policyCode' 2. Matching on the current 'table' is paused 3. Matching policy is found, but inactive