Chapter 4. Options for invoking a PMML model

Procedure

1. In your client application, add the following dependencies to the relevant classpath of your Java project:

   <!-- Required for the PMML compiler -->
   <dependency>
     <groupId>org.drools</groupId>
     <artifactId>kie-pmml</artifactId>
     <version>${rhpam.version}</version>
   </dependency>
   
   <!-- Required for the KIE public API -->
   <dependency>
     <groupId>org.kie</groupId>
     <artifactId>kie-api</artifactId>
     <version>${rhpam.version}</version>
   </dependencies>
   
   <!-- Required if not using classpath KIE container -->
   <dependency>
     <groupId>org.kie</groupId>
     <artifactId>kie-ci</artifactId>
     <version>${rhpam.version}</version>
   </dependency>

   Copy to Clipboard Toggle word wrap

   The <version> is the Maven artifact version for Red Hat Process Automation Manager currently used in your project (for example, 7.14.0.Final-redhat-00002).

   Note

   Instead of specifying a Red Hat Process Automation Manager <version> for individual dependencies, consider adding the Red Hat Business Automation bill of materials (BOM) dependency to your project pom.xml file. The Red Hat Business Automation BOM applies to both Red Hat Decision Manager and Red Hat Process Automation Manager. When you add the BOM files, the correct versions of transitive dependencies from the provided Maven repositories are included in the project.

   Example BOM dependency:

   <dependency>
     <groupId>com.redhat.ba</groupId>
     <artifactId>ba-platform-bom</artifactId>
     <version>7.2.0.GA-redhat-00002</version>
     <scope>import</scope>
     <type>pom</type>
   </dependency>

   Copy to Clipboard Toggle word wrap

   For more information about the Red Hat Business Automation BOM, see What is the mapping between RHPAM product and maven library version?.

2. Create a KIE container from classpath or ReleaseId:

   KieServices kieServices = KieServices.Factory.get();
   
   ReleaseId releaseId = kieServices.newReleaseId( "org.acme", "my-kjar", "1.0.0" );
   KieContainer kieContainer = kieServices.newKieContainer( releaseId );

   Copy to Clipboard Toggle word wrap

   Alternative option:

   KieServices kieServices = KieServices.Factory.get();
   
   KieContainer kieContainer = kieServices.getKieClasspathContainer();

   Copy to Clipboard Toggle word wrap

3. Create an instance of the PMMLRequestData class, which applies your PMML model to a set of data:

   public class PMMLRequestData {
       private String correlationId; 

   1

   
       private String modelName; 

   2

   
       private String source; 

   3

   
       private List<ParameterInfo<?>> requestParams; 

   4

   
       ...
   }

   Copy to Clipboard Toggle word wrap

   1

   Identifies data that is associated with a particular request or result

   2

   The name of the model that should be applied to the request data

   3

   Used by internally generated PMMLRequestData objects to identify the segment that generated the request

   4

   The default mechanism for sending input data points

4. Create an instance of the PMML4Result class, which holds the output information that is the result of applying the PMML-based rules to the input data:

   public class PMML4Result {
       private String correlationId;
       private String segmentationId; 

   1

   
       private String segmentId; 

   2

   
       private int segmentIndex; 

   3

   
       private String resultCode; 

   4

   
       private Map<String, Object> resultVariables; 

   5

   
       ...
   }

   Copy to Clipboard Toggle word wrap

   1

   Used when the model type is MiningModel. The segmentationId is used to differentiate between multiple segmentations.

   2

   Used in conjunction with the segmentationId to identify which segment generated the results.

   3

   Used to maintain the order of segments.

   4

   Used to determine whether the model was successfully applied, where OK indicates success.

   5

   Contains the name of a resultant variable and its associated value.

   In addition to the normal getter methods, the PMML4Result class also supports the following methods for directly retrieving the values for result variables:

   public <T> Optional<T> getResultValue(String objName, String objField, Class<T> clazz, Object...params)
   
   public Object getResultValue(String objName, String objField, Object...params)

   Copy to Clipboard Toggle word wrap

5. Create an instance of the ParameterInfo class, which serves as a wrapper for basic data type objects used as part of the PMMLRequestData class:

   public class ParameterInfo<T> { 

   1

   
       private String correlationId;
       private String name; 

   2

   
       private String capitalizedName;
       private Class<T> type; 

   3

   
       private T value; 

   4

   
       ...
   }

   Copy to Clipboard Toggle word wrap

   1

   The parameterized class to handle many different types

   2

   The name of the variable that is expected as input for the model

   3

   The class that is the actual type of the variable

   4

   The actual value of the variable

6. Execute the PMML model based on the required PMML class instances that you have created:

   public void executeModel(KieBase kbase,
                            Map<String,Object> variables,
                            String modelName,
                            String correlationId,
                            String modelPkgName) {
       RuleUnitExecutor executor = RuleUnitExecutor.create().bind(kbase);
       PMMLRequestData request = new PMMLRequestData(correlationId, modelName);
       PMML4Result resultHolder = new PMML4Result(correlationId);
       variables.entrySet().forEach( es -> {
           request.addRequestParam(es.getKey(), es.getValue());
       });
   
       DataSource<PMMLRequestData> requestData = executor.newDataSource("request");
       DataSource<PMML4Result> resultData = executor.newDataSource("results");
       DataSource<PMMLData> internalData = executor.newDataSource("pmmlData");
   
       requestData.insert(request);
       resultData.insert(resultHolder);
   
       List<String> possiblePackageNames = calculatePossiblePackageNames(modelName,
                                                                       modelPkgName);
       Class<? extends RuleUnit> ruleUnitClass = getStartingRuleUnit("RuleUnitIndicator",
                                                                   (InternalKnowledgeBase)kbase,
                                                                   possiblePackageNames);
   
       if (ruleUnitClass != null) {
           executor.run(ruleUnitClass);
           if ( "OK".equals(resultHolder.getResultCode()) ) {
             // extract result variables here
           }
       }
   }
   
   protected Class<? extends RuleUnit> getStartingRuleUnit(String startingRule, InternalKnowledgeBase ikb, List<String> possiblePackages) {
       RuleUnitRegistry unitRegistry = ikb.getRuleUnitRegistry();
       Map<String,InternalKnowledgePackage> pkgs = ikb.getPackagesMap();
       RuleImpl ruleImpl = null;
       for (String pkgName: possiblePackages) {
         if (pkgs.containsKey(pkgName)) {
             InternalKnowledgePackage pkg = pkgs.get(pkgName);
             ruleImpl = pkg.getRule(startingRule);
             if (ruleImpl != null) {
                 RuleUnitDescr descr = unitRegistry.getRuleUnitFor(ruleImpl).orElse(null);
                 if (descr != null) {
                     return descr.getRuleUnitClass();
                 }
             }
         }
       }
       return null;
   }
   
   protected List<String> calculatePossiblePackageNames(String modelId, String...knownPackageNames) {
       List<String> packageNames = new ArrayList<>();
       String javaModelId = modelId.replaceAll("\\s","");
       if (knownPackageNames != null && knownPackageNames.length > 0) {
           for (String knownPkgName: knownPackageNames) {
               packageNames.add(knownPkgName + "." + javaModelId);
           }
       }
       String basePkgName = PMML4UnitImpl.DEFAULT_ROOT_PACKAGE+"."+javaModelId;
       packageNames.add(basePkgName);
       return packageNames;
   }

   Copy to Clipboard Toggle word wrap

   Rules are executed by the RuleUnitExecutor class. The RuleUnitExecutor class creates KIE sessions and adds the required DataSource objects to those sessions, and then executes the rules based on the RuleUnit that is passed as a parameter to the run() method. The calculatePossiblePackageNames and the getStartingRuleUnit methods determine the fully qualified name of the RuleUnit class that is passed to the run() method.