11 Working with Decision Components in SOA Applications

This chapter discusses the Decision Components that support Oracle Business Rules. It also covers how to use a Decision Component as a mechanism for publishing rules and rulesets as a reusable service that can be invoked from multiple business processes.

A Decision Component is an SCA component that can be used within a composite and wired to a BPEL component. Apart from that, Decision Components are used for the dynamic routing capability of Mediator and Advanced Routing Rules in Human Workflow.

This chapter includes the following sections:

11.1 Introduction to Decision Components

A Decision Component is a web service that wraps a rule session to the underlying decision function.

A Decision Component consists of the following:

Rules or Decision Tables that are evaluated using the Rules Engine. These are defined using Rules Designer and stored in a business rules dictionary.
Metadata that describes facts required for specific rules to be evaluated. Rulesets that contain rules or Decision Tables are exposed as a service with facts that are input and output. These facts must be exposed through XSD definitions.

For example, a credit rating ruleset may expect a customer ID and previous loan history as facts, but a pension payment ruleset may expect a value with the years of employee service, salary, and age as facts.

For more information, see Working with Decision Component Metadata.
A web service wraps the input, output, and the call to the underlying rule engine.

This service lets business processes assert and retract facts as part of the process. In some cases, all facts can be asserted from the business process as one unit. In other cases, the business process can incrementally assert facts and eventually consult the rule engine for inferences. Therefore, the service has to support both stateless and stateful interactions.

You can create a variety of such business rules service components.

For more information, see Developing SOA Applications with Oracle SOA Suite.

11.2 Working with a Decision Component

Using Oracle JDeveloper with Rules Designer these tools automatically generate all required metadata and WSDL operations.

The Decision Component can be integrated into a SOA composite application in the following ways:

Create a Decision Component as a standalone component in the SOA Composite Editor. In this scenario, the Decision Service is exposed on the composite level and thus can be invoked from any web service client.

For more information, see Getting Started with Oracle Business Rules in Developing SOA Applications with Oracle SOA Suite.
Create a Decision Component in the SOA Composite Editor that you later associate with a BPEL process. In this scenario the Decision Service is not exposed on the composite level. However it can be wired to any other component within the composite, such as BPEL, Oracle Mediator, and Oracle Human Workflow.

For more information, see Getting Started with Oracle Business Rules in Developing SOA Applications with Oracle SOA Suite.
Create a Decision Component within the Human Task editor of a human task component.

This integration provides the following benefits:

Dynamic processing: provides for intelligent routing, validation of policies within a process, and constraint checks.
Integration with ad hoc human tasks: provides policy-based task assignment, various escalation policies, and load balancing of tasks.

11.2.1 Working with Decision Component Metadata

A Decision Component is defined by the following files:

Decision Service Metadata (.decs) File
SCA Component Type (.componentType) File
Decision Component Entry in composite.xml

Typically, Oracle JDeveloper generates and maintains these files.

Decision Service Metadata (.decs) File

Every Decision Component within a composite comprises one business rule metadata file. The business rule metadata file provides information about the location of the component business rule dictionary and the Decision Services exposed by the Decision Component.

One Decision Component might expose one or more Decision Services. For example, a CreditRating Decision Component might expose two services, CheckEligibility and CalculateCreditRating.Oracle Fusion Middleware 11g Release 1 (11.1.1) onwards, the Decision Service metadata comprises of the decision function name that is exposed as a web service. For projects that are migrated from older releases of Oracle SOA Suite, the Decision Service metadata typically has more information depending on the interaction pattern used in 10.1.3.x.

The business rule metadata file (business_rule_name.decs) defines the contract between the components involved in the interaction of the business rule with the design time and back-end Oracle Rules Engine.

This file is in the SOA Content area of the Application Navigator in Oracle JDeveloper for your SOA composite application. Table 11-1 describes the top-level elements in the Decision service .decs file.

Table 11-1 Decision Metadata File (.decs) Top-level Elements

Element Description

Element	Description
`ruleEngineProvider`	The `business_rule_name.decs` file `ruleEngineProvider` element includes details about the rule dictionary to use: <ruleEngineProvider name="OracleRulesSDK" provider="Oracle_11.0.0.0.0"> <repository type="SCA-Archive"> <path>AutoLoanComposite/oracle/rules/AutoLoanRules.rules</path> </repository> </ruleEngineProvider> The repository type is set to `SCA-Archive` for Decision Components. This indicates that the rule dictionary is located in the service component architecture archive. The path is relative and interpreted differently by the following: Design time — The path is prefixed with `Oramds:/`. Metadata service (MDS) APIs open the rule dictionary. Therefore, the full path to the dictionary is as follows: Oramds:/AutoLoanComposite/oracle/rules/AutoLoanRules.rules Runtime (business rule service engine) — The business rule service engine uses the Oracle Business Rules SDK `RuleRepository` API to open the rule dictionary located in MDS. The composite name prefix, for example (`AutoLoanComposite`) is removed from the path and the metadata manager assumes the existence of `oracle/rules/AutoLoanRules.rules` relative to the composite home directory.
`decisionService`	A Decision service is a web service (or SOA) enabler of business rules. It is a service in the sense of a web service, thus opening the world of business rules to service-oriented architectures (SOA). In 12c (12.2.1), a Decision service consists of metadata and a WSDL contract for the service. The `business_rule_name.decs` file `decisionService` element defines the metadata that describes business rules exposed as a web service. In general, a Decision service includes the following elements: Target namespace Reference to the back-end Oracle Rules Engine (this is the link to the rule dictionary). Note that `OracleRulesSDK` is the reference name that matches the name of the Oracle Rules Engine provider in `ruleEngineProvider` element. Name (`CreditRatingService` in the following example) Additional information about the dictionary name and ruleset to use List of supported operations (patterns) Apart from the operations (patterns), the parameter types (or fact types) of operations are specified (and validated later at runtime). Therefore, every Decision service exposes a strongly-typed contract.

ruleEngineProvider

The business_rule_name.decs file ruleEngineProvider element includes details about the rule dictionary to use:

<ruleEngineProvider name="OracleRulesSDK" provider="Oracle_11.0.0.0.0">
    <repository type="SCA-Archive">
        <path>AutoLoanComposite/oracle/rules/AutoLoanRules.rules</path>
    </repository>
</ruleEngineProvider>

The repository type is set to SCA-Archive for Decision Components. This indicates that the rule dictionary is located in the service component architecture archive. The path is relative and interpreted differently by the following:

Design time — The path is prefixed with Oramds:/. Metadata service (MDS) APIs open the rule dictionary. Therefore, the full path to the dictionary is as follows:
```
Oramds:/AutoLoanComposite/oracle/rules/AutoLoanRules.rules
```
Runtime (business rule service engine) — The business rule service engine uses the Oracle Business Rules SDK RuleRepository API to open the rule dictionary located in MDS. The composite name prefix, for example (AutoLoanComposite) is removed from the path and the metadata manager assumes the existence of oracle/rules/AutoLoanRules.rules relative to the composite home directory.

decisionService

A Decision service is a web service (or SOA) enabler of business rules. It is a service in the sense of a web service, thus opening the world of business rules to service-oriented architectures (SOA). In 12c (12.2.1), a Decision service consists of metadata and a WSDL contract for the service.

The business_rule_name.decs file decisionService element defines the metadata that describes business rules exposed as a web service.

In general, a Decision service includes the following elements:

Target namespace
Reference to the back-end Oracle Rules Engine (this is the link to the rule dictionary). Note that OracleRulesSDK is the reference name that matches the name of the Oracle Rules Engine provider in ruleEngineProvider element.
Name (CreditRatingService in the following example)
Additional information about the dictionary name and ruleset to use
List of supported operations (patterns)

Apart from the operations (patterns), the parameter types (or fact types) of operations are specified (and validated later at runtime). Therefore, every Decision service exposes a strongly-typed contract.

SCA Component Type (.componentType) File

An SCA business_rule_name.componentType file is included with each Decision Component. This file lists the services exposed by the business rules service component. In the following sample, two services are exposed: CreditRatingService and LoanAdvisorService.

<?xml version="1.0" encoding="UTF-8" ?>
<!-- Generated by Oracle SOA Modeler version 1.0 at [5/24/07 9:27 AM]. -->
<componentType xmlns="http://xmlns.oracle.com/sca/1.0">
  <service name="CreditRatingService">
    <interface.wsdl
interface="http://xmlns.oracle.com/creditrating/Rating#wsdl.interface(IDecisionSer
vice)"/>
  </service>
  <service name="LoanAdvisorService">
    <interface.wsdl
interface="http://xmlns.oracle.com/loanoffer/Advisor#wsdl.interface(IDecisionServi
ce)"/>
  </service>
</componentType>

Decision Component Entry in composite.xml

An entry in composite.xml is created for a Decision Component. For example,
```
<component name="OracleRules1">
     <implementation.decision src="OracleRules1.decs"/>
</component>
```
The business rules service engine uses the information from this implementation type to process requests for the Service Engine. From an SCA perspective, a Decision Component is a new "implementation type".

11.2.2 Working with Decision Components that Expose a Decision Function

You can use a decision service to expose an Oracle Business Rules Decision Function as a service. A Decision Function is a function you use to call rules from a Java EE application or from another component.

The code example below shows a business_rule_name.decs file decisionServices element that defines the metadata for an Oracle Business Rules Decision Function exposed as a service.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<decisionServices xmlns="http://xmlns.oracle.com/bpel/rules" name="PurchaseItems">
    <ruleEngineProvider name="OracleRulesSDK" provider="Oracle_11.0.0.0.0">
        <repository type="SCA-Archive">
            <path>PurchasingSampleProject/oracle/rules/com/example/PurchaseItems.rules</path>
        </repository>
    </ruleEngineProvider>
    <decisionService targetNamespace="http://xmlns.oracle.com/PurchaseItems/PurchaseItems_DecisionService_ValidatePurchasesDF" 
ruleEngineProviderReference="OracleRulesSDK" name="PurchaseItems_DecisionService_ValidatePurchasesDF">
        <catalog>PurchaseItems</catalog>
        <pattern name="CallFunctionStateless">
            <arguments>
                <call>com.example.PurchaseItems.ValidatePurchasesDF</call>
            </arguments>
        </pattern>
        <pattern name="CallFunctionStateful">
            <arguments>
                <call>com.example.PurchaseItems.ValidatePurchasesDF</call>
            </arguments>
        </pattern>
    </decisionService>
</decisionServices>

In this case, the decision function ValidatePurchasesDF itself is specified entirely in the PurchaseItems.rules file.

For more information, see Working with Decision Functions.

11.2.3 Using Stateful Interactions with a Decision Component

To provide a stateful decision service you create a decision function and specify that the decision function is not stateless. To do so, clear the Stateless check box in a decision function.

Note the following details about stateful interactions with a Decision Component (also see Figure 11-2):

Rule sessions from the cache and those from the pool are mutually exclusive:
- The rule session pool is for simple, stateless interactions only.
- The rule session cache keeps the state of a rule session across Decision service requests.

11.2.4 What You Need to Know About Stateful Interactions with Decision Components

A Decision Component running in a Business Rules service engine supports either stateful or stateless operation. The Reset Session (stateless) check box in the Create Business Rules dialog provides support for these two modes of operation.

When the Reset Session (stateless) check box selected, this indicates stateless operation.

When Reset Session (stateless) check box is cleared, the underlying Oracle Business Rules object is kept in memory of the Business Rules service engine at a separate location (so that it is not given back to the Rule Session Pool when the operation is finished). Only use stateful operation if you know you need this option (some errors can occur at runtime when using stateful operation and these errors could use a significant amount of service engine memory).

When Reset Session (stateless) check box is cleared, a subsequent use of the Decision Component reuses the cached RuleSession object, with all its state information from the callFunctionStateful invocation, and then releases it back to the Rule Session pool after the callFunctionStateless operation is finished.

11.3 Decision Service Architecture

A Decision service consists only of the service description. All other artifacts are shared within a Decision Component.

This is shown in Figure 11-1:

Figure 11-1 Decision Service Architecture

Description of "Figure 11-1 Decision Service Architecture"

The heart of runtime is the decision service cache, which is organized in a tree structure. Every Decision Component owns a subtree of that cache (depending on the composite distinguished name (DN), component, and service name). In this regard, decision services of a Decision Component share the following data:

Metadata of the Decision Component
- Fact type metadata.
- Function metadata.
- Ruleset metadata.
Rule session pool
- One rule session pool is created per Decision Component.
- The rule sessions in the pool are pre-initialized with the data model Oracle RL and the ruleset Oracle RL already executed.
- New rule sessions are created on demand.
- Rule sessions can be reused for a configurable number of times.
- The initial size of the rule session pool is configurable.
Stateful rule session cache
- A special cache is maintained for stateful rule sessions.
  
  For more information, see Using Stateful Interactions with a Decision Component.
Deployment artifacts
- Decision Component deployment can end up in class generation for JAXB fact types. The classes can be shared across the composite.

Figure 11-2 shows how both stateless and stateful rule sessions interact with the rule session pool and how stateful rule sessions interact with the stateful rule session cache during a decision service request.

Figure 11-2 Stateless and Stateful Rule Session Usage for a Decision Service Request

Description of "Figure 11-2 Stateless and Stateful Rule Session Usage for a Decision Service Request"