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>

   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>

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

   Alternative option:

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

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
       ...
   }

   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
       ...
   }

   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)

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
       ...
   }

   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;
   }

   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.