Package 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);

         // execute evaluate matching between two records
         // that using default matching policy
           Adaptation record3 = table
                   .lookupAdaptationByPrimaryKey(PrimaryKey.parseString("3"));
           EvaluateMatchingResult evaluateMatchingResult = matchingOperations
                   .evaluateMatching(record2, record3, null);

           // gets result of pre-processing
           PreProcessingResult preProcessingResult = evaluateMatchingResult
                                                    .getPreProcessingResult();

           // gets result of decision tree execution
           MatchingResultType matchingResult = evaluateMatchingResult
                                                         .getMatchingResult();

           // gets and travels decision tree nodes in the decision
           // from the root node to the last node
           Iterator<DecisionNode> decisionNodes =
                                          evaluationMatchingResult
                                                  .getDecisionNodes()
                                                  .iterator();

           MatchingResultType matchingResult;
           while (decisionNodes.hasNext()) {
               DecisionNode currentNode = decisionNodes.next();
               if (currentNode.isLastNode()) {
                   matchingResult = currentNode.getMatchingResult();
               } else {
                   System.out.println("Decision node name: "
                                                     + currentNode.getName());
                   Collection<DecisionField> decisionFields =
                                      currentNode.getDecisionFields();
                   for (DecisionField field : decisionFields) {
                       System.out.println(
                          String.format("Field %s - Score %f",
                                                  field.getLabel(),
                                                  field.getComparisonScore())
                       );
                   }
               }
           }
      }
 }

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      EvaluateMatchingResult evaluateMatching​(com.onwbp.adaptation.Adaptation record1, com.onwbp.adaptation.Adaptation record2, java.lang.String policyCodeOrNull)
      Executes an evaluate matching operation on two records.
      MatchingComparator getComparator​(com.onwbp.adaptation.AdaptationTable table, java.lang.String policyCodeOrNull)
      Creates a comparator to compare records based on decision tree configured in matching policy.
      void matchRecord​(com.onwbp.adaptation.AdaptationTable table, com.onwbp.adaptation.PrimaryKey recordPrimaryKey, java.lang.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, java.lang.String policyCodeOrNull)
      Executes a matching operation with a specific request on a EBX table.
      MatchingProcess matchTable​(com.onwbp.adaptation.AdaptationTable table, java.lang.String policyCodeOrNull)
      Executes a matching operation on an entire EBX table.
      SimulationResult simulateMatch​(com.onwbp.adaptation.Adaptation record, java.lang.String policyCodeOrNull)
      Simulates a match record operation.
      SimulationResult simulateMatch​(com.onwbp.adaptation.AdaptationTable table, java.util.Map<com.orchestranetworks.schema.SchemaNode,​java.lang.Object> values, java.lang.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,
                 java.lang.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,
                           java.lang.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,
                             java.lang.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 no records are not found in the 'request' 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,
                               java.lang.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,
                               java.util.Map<com.orchestranetworks.schema.SchemaNode,​java.lang.Object> values,
                               java.lang.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,
                                 java.lang.String policyCodeOrNull)
                          throws com.orchestranetworks.addon.mame.common.InvalidParameterException,
                                 com.orchestranetworks.addon.mame.common.InvalidStateException

        Creates a comparator to compare records based on decision tree 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

      • evaluateMatching

        EvaluateMatchingResult evaluateMatching​(com.onwbp.adaptation.Adaptation record1,
                                        com.onwbp.adaptation.Adaptation record2,
                                        java.lang.String policyCodeOrNull)
        Executes an evaluate matching operation on two records.

        This operation runs a match on the given records, and provides an explanation of the result.

        Parameters:
        record1 - first record to evaluate
        record2 - second record to evaluate
        policyCodeOrNull - identifier of the matching policy. Specify null to apply the default matching policy
        Throws:
        java.lang.IllegalArgumentException - When one of the following errors occurs:
        • The policyCodeOrNull is empty
        • One or both records are excluded by the matching policy
        • The records do not belong to same table
        • The records were confirmed as a false positive match
        java.lang.IllegalStateException - When one of the following errors occurs:
        • No matching policy conforms to the input policyCodeOrNull
        • Matching on the current table is paused
        • Matching policy is found, but inactive