IBM Streams 4.2.1

Operator ODMRulesetExecutor

SPL standard and specialized toolkits > com.ibm.streams.rules 2.1.0 > com.ibm.streams.rules.odm > ODMRulesetExecutor

Primitive operator image not displayed. Problem loading file: ../../image/tk$com.ibm.streams.rules/op$com.ibm.streams.rules.odm$ODMRulesetExecutor.svg

The ODMRulesetExecutor operator creates input ruleset parameters from IBM InfoSphere Streams tuples and converts the output ruleset parameters that are generated by the ODM Rules Execution Server to tuples.

ODM rules applications contain one or more rulesets that contain rules and other artifacts that can be executed by the ODM Rules Execution Server. Ruleset parameters define the type of data that can be sent and received from the ODM Rules Execution Server. You can deploy the rules applications to a shared file system that is accessible to IBM InfoSphere Streams or to a database. If the rules application are deployed to a database, the rulesets are deployed as tables in the database.

The ODMRulesetExecutor operator converts tuples that are received on the input port to input ruleset parameters. The operator uses the Java SE APIs to make run time calls to the ODM Rules Execution Server. The ODM Rules Execution Server uses the input ruleset parameters to execute the rules and sends the evaluated results in the output ruleset parameters. The ODMRulesetExecutor operator converts the output ruleset parameters to tuples and submits the tuples to the output port. If an error occurs and the optional output error port is configured, the operator submits a tuple on the error port for each failed tuple.

By default, the ODMRulesetExecutor operator maps tuples to ruleset parameters, or vice versa for parameters that support primitive Java data types. If the ruleset parameters support user-defined Java data types, you must implement the classes in the RulesExecutionHandler Java interface to provide custom mapping between tuples and ruleset parameters.

By default, for each input tuple, the ODMRulesetExecutor operator submits a tuple to the first output port. If the optional error port is configured, the operator submits a tuple on the error port for each error. You can optionally configure the operator to submit the result of the ruleset execution to multiple output ports by customizing the classes in the RulesExecutionHandler interface. You can also customize how the operator handles errors by overriding the default implementation that is provided in the RulesExecutionHandler interface. For details about the RulesExecutionHandler interface, see the Javadoc that is in the STREAMS_INSTALL/toolkits/com.ibm.streams.rules/doc directory.

If the rulesets in the deployed rules applications are updated, the operator provides the capability to execute the updated rules without restarting or recompiling the application or refreshing the InfoSphere Streams instance. To receive notifications about the updated rules, you must configure a TCP/IP connection to the ODM Management Console by specifying the host name and the port where the ODM Management Console is hosted.

Behavior in a consistent region

  • The ODMRulesetExecutor operator is stateless and can participate in a consistent region.
  • The operator cannot be at the start of a consistent region.
  • If client's implementation of RulesetExecutionHandler has states that need to be persisted and reset, the client must implement the com.ibm.streams.operator.state.StateHandle in the RulesetExecutionHandler implementation. When the operator is called to drain, checkpoint, and reset, the operator delegates the calls to the ruleset execution handler.
  • Rules set can be updated while the application is running. The operator does not checkpoint and reset rulesets and it always runs with the latest ruleset deployed.

Exceptions

The following list describes the common types of exceptions that can occur:
  • Run time error that halts the operator execution.
    • The ODMRulesetExecutor operator throws an exception and terminate in the following cases. The trace and log information is logged in the console logs and also output to the optional error output port if the application is configured to use the optional port. The optional error output has at the most two attributes, which contain the input tuple and error message. If only one attribute is specified, the attribute must be of type rstring.
      • The ruleset name is unknown.
      • The required JAR files are missing.
      • The value specified by the rulesetPath, xomLibrary, rulesetExecutionHandlerLibrary is not valid.
  • Compile-time errors.
    • The ODMRulesetExecutor operator throws an exception and terminate in the following cases. The trace and log information is logged in the console logs.
      • The operator is configured to receive notifications about the updated rulesets, but the managementConsoleHost or managementConsolePort parameter is not specified.
      • The rules application is deployed to a database, but the driverName, driverPath, databaseUrl, userName, or userPassword parameter is not specified.
Examples

Summary

Ports
This operator has 1 or more input ports and 1 or more output ports.
Windowing
This operator does not accept any windowing configurations.
Parameters
This operator supports 15 parameters.

Required: rulesetPath

Optional: configParameter, databaseUrl, driverName, driverPath, managedXomDeployedOnDb, managementConsoleHost, managementConsolePort, ruleAppDirectory, rulesetExecutionHandlerClassName, rulesetExecutionHandlerLibrary, skipRulesForTesting, userName, userPassword, xomLibrary

Metrics
This operator does not report any metrics.

Properties

Implementation
Java

Input Ports

Ports (0)

The ODMRulesetExecutor operator has one required input port. The input port is non-mutating and its punctuation mode is Preserving. In a typical implementation, tuples from this input port are mapped to the ruleset input parameters and sent the rules engine.

Properties
Ports (1...)

Incoming data stream to be sent to the Rule Execution operator

Properties

Output Ports

Assignments
Java operators do not support output assignments.
Ports (0)

The ODMRulesetExecutor has one required output port. The required output port is non-mutating and its punctuation mode is Preserving. You can optionally configure the operator to have multiple output ports so that the operator can send the result of the ruleset execution to multiple ports. By default, for each input tuple, the operator submits a tuple, which contains the evaluated result on its output port. You can also customize this behavior. You can control the behavior of the operator by customizing the classes in the RulesetExecutionHandler Java interface.

Properties

Ports (1...)

The ODMRulesetExecutor operator supports multiple output ports. Typically, there are two output ports. The first output port is used for the result of the ruleset execution. The second output port is used as an error port. By providing a custom RulesetExecutionHandler, however, you can have more than two output ports.

Properties

Parameters

This operator supports 15 parameters.

Required: rulesetPath

Optional: configParameter, databaseUrl, driverName, driverPath, managedXomDeployedOnDb, managementConsoleHost, managementConsolePort, ruleAppDirectory, rulesetExecutionHandlerClassName, rulesetExecutionHandlerLibrary, skipRulesForTesting, userName, userPassword, xomLibrary

configParameter

This optional parameter specifies the information that you can pass to the RulesetExecutionHandler implementation.

Properties
databaseUrl

This optional parameter specifies the URL of the database if the rules application and the ruleset are deployed to a database. The URL specifies the host name, port, and the database name. For example, "jdbc:db2://hostname:port/db_name" where hostname is the name of the machine where the database is hosted, port specifies the port that you can connect to, and database name is the name of the database where the rules application is deployed.

Properties
driverName
This optional parameter specifies the name of the database driver if the rules application and the ruleset are deployed to a database. The following database drivers are supported:
  • com.ibm.db2.jcc.DB2Driver
  • COM.ibm.db2.jdbc.app.DB2Driver
  • com.ibm.db2j.jdbc.DB2jDriver
  • com.microsoft.jdbc.sqlserver.SQLServerDriver
  • com.mysql.jdbc.Driver
  • com.pointbase.jdbc.jdbcUniversalDriver
  • com.sybase.jdbc2.jdbc.SybDriver
  • oracle.jdbc.driver.OracleDriver
  • oracle.jdbc.OracleDriver
  • org.apache.derby.jdbc.EmbeddedDriver
  • org.hsqldb.jdbcDriver
  • org.postgresql.Driver
  • weblogic.jdbc.sqlserver.SQLServerDriver
  • weblogic.jdbc.sybase.SybaseDriver
Properties
driverPath

This optional parameter specifies the location of JAR file that contains the driver if the rules application and the ruleset are deployed to a database. For example, /odm/dbDriver/db2jcc.jar. You can specify an absolute path or a path relative SPL application directory.

Properties
managedXomDeployedOnDb

This optional parameter specifies whether a managed XOM is deployed to the database. The default value is false.

Properties
managementConsoleHost

This optional parameter specifies the host name where the ODM Management console is deployed.

Properties
managementConsolePort

This optional parameter specifies the TCP/IP port that you can connect to retrieve the updated rulesets.

Properties
ruleAppDirectory

This optional parameter specifies the directory on the shared file system where the rules application and the ruleset are deployed. You can specify an absolute path or a path relative to the directory of the SPL application. By default, the rules applications and rulesets are deployed to the res_data directory, which is in the ODM-install-directory. For example, /odm/JavaseRuntimeproject/res_data.

Properties
rulesetExecutionHandlerClassName

This optional parameter specifies the name of the execution handler class, which implements the TupleRulesetParameterMapping Interface.

If this parameter is not specified, the operator expects only primitive Java data types for ruleset parameters. Additionally, the operator expects the first output port to be a data port where it submits a tuple and an optional second output port that is an error port.

Properties
rulesetExecutionHandlerLibrary

This optional parameter specifies the location of the JAR file that contains the execution handler class file for user-defined Java types. You can specify multiple JAR files that are separated by commas if the execution handler class file has dependencies on other JAR files. You can specify an absolute path or a path relative to SPL application directory. If this parameter is not defined, the operator expects the xomLibrary parameter to contain the execution handler class information.

Properties
rulesetPath

This mandatory parameter specifies the path to the ruleset that is used by the ODM Rule Execution Server to locate the deployed rules application and the rulesets. The format of the canonical path is /{RuleApp name}[/{version}]/{ruleset name}[/{version}] where RuleApp name and ruleset name are mandatory.

Use the following guidelines when you specify the path:
  • The path cannot begin with a number [0-9].
  • The path can contain alphanumeric characters and underscores. No other special characters are allowed.
  • If the version is not specified, the latest activated version of the rules application or the ruleset is used. The version has the following format: {number}.{number}. For example, /rule8_8app/1.0/6_ruleset_6/1.0, /Rule8_8app/1.0/6_ruleset_6, /rule8_8app/6_ruleset_6.
Properties
skipRulesForTesting

When this optional parameter is true, calls to the rules engine are skipped for all but the first tuple. This can be a useful option to measure the performance of the operator without the rules call.

Properties
userName

This optional parameter specifies the user name that you can use to connect to the database if the rules application and the ruleset are deployed to a database.

Properties
userPassword

This optional parameter specifies the password that you can use to connect to the database if the rules application and the ruleset are deployed to a database.

Properties
xomLibrary

This optional parameter specifies the location of the Java XOM if the ruleset contains Java user-defined data types for ruleset parameters. The XOM points to the JAR files that you can deploy to the ODM Rules Execution Server. You can specify an absolute path or a path relative to the SPL application directory. For example, /homes/hny2/user/ODM/bankloanXom.jar. To specify multiple JAR files, use comma as a delimiter.

Properties

Code Templates

ODMRulesetExecutor_file
stream<${schema}> ${outputStream} =
						ODMRulesetExecutor(${inputStream}) {
						param
						rulesetPath: ${rulesetPath};
						ruleAppDirectory: ${ruleAppDirectory};
						rulesetExecutionHandlerLibrary: ${rulesetExecutionHandlerLibrary};
						xomLibrary: ${xomLibrary};
						rulesetExecutionHandlerClassName: ${rulesetExecutionHandlerClassName};
						}

ODMRulesetExecutor_odbc
stream<${schema}> ${outputStream} =
						ODMRulesetExecutor(${inputStream}) {
						param
						rulesetPath: ${rulesetPath};
						driverName: ${driverName};
						driverPath: ${driverPath};
						databaseUrl: ${databaseUrl};
						userName: ${userName};
						userPassword: ${userPassword};
						rulesetExecutionHandlerLibrary: ${rulesetExecutionHandlerLibrary};
						xomLibrary: ${xomLibrary};
						rulesetExecutionHandlerClassName: ${rulesetExecutionHandlerClassName};
						}

ODMRulesetExecutor_RuleRefresh
stream<${schema}> ${outputStream} =
						ODMRulesetExecutor(${inputStream}) {
						param
						rulesetPath: ${rulesetPath};
						ruleAppDirectory: ${ruleAppDirectory};
						rulesetExecutionHandlerLibrary: ${rulesetExecutionHandlerLibrary};
						xomLibrary: ${xomLibrary};
						rulesetExecutionHandlerClassName: ${rulesetExecutionHandlerClassName};
						managementConsoleHost: ${managementConsoleHost};
						managementConsolePort: ${managementConsolePort};
						}

Libraries

Java operator code
Library Path: ../../impl/bin, ../../lib/com.ibm.streams.rules.jar
ODMRulesetExecutor
Library Path: @ODM_HOME@/executionserver/lib/*