Building Rules Applications in the Database using JDeveloper

Module Objectives

Purpose

This module describes how to use Oracle JDeveloper, Oracle Database 10g Release 2, and the Rules Manager feature to build an Event-Condition-Action Rules application.

Objectives

This module will teach you how to use the Rules Manager Wizards to:

	Create Event Structures in the database and also create the corresponding Java source files in the current JDeveloper project.
	Create a Rule Class in the database and also create the corresponding Java source file in the current JDeveloper project.
	Add rules to an existing Rule Class.

Prerequisites

Before starting this module, you should

	Have reviewed the reference material below, if necessary, to gain a basic understanding of the Oracle Rules Manager feature.
	Have access to an Oracle Database 10g Release 2 in which to create the rules application.
	Have access to Oracle JDeveloper 10g, version 9.0.5.2 or greater.
	Have downloaded the JDeveloper extensions for Rules Manager from the Oracle JDeveloper 10g - Extensions Exchange on OTN.

Reference Material

The following reference material provides detailed information about the topics in this module:

Documentation: Oracle Database Application Developer's Guide - Rules Manager and Expression Filter, 10g Release 2 (10.2), hereafter referred to as the Application Developer's Guide

Installation Instructions

Extract the contents of the downloaded zip file, rlm4j.zip, into the [jdev-root]\jdev\lib\ext directory.
Start JDeveloper.
The Rules Manager Wizards can be invoked from the Gallery (File | New | Business Tier | Rules Manager).

Overview

The Rules Manager Wizards are add-ins for JDeveloper10g that provide a user interface for creating rules applications in the database. In addition to creating the database objects for the rules application, these wizards create Java source code that can be included in any Java application needing to process the rules. Within the Java application, the rules are processed for the events that are captured as instances of some Java classes.

Building a rules application using Rules Manager Wizards

In order to create a rules application, you must perform the following steps:

1.	Create a JDeveloper Project
2.	Create Event Structures using the Event Structure Creation Wizard
3.	Create a Rule Class using the Rule Class Creation Wizard
4.	Create Rules using the Rule Creation Wizard
5.	Complete the Rules Application

Create a JDeveloper Project

Back to List

You need to create a workspace and project in JDeveloper before you can create your application. Perform the following steps:

1.	Open JDeveloper.
2.	Select File > New. Click the General category and select Workspaces under this category and Workspace under Items. Then click OK.
3.	Enter dbrules as the Workspace Name and Directory Name. Make sure Add a New Empty Project is checked and click OK.
4.	Enter TravelPromos as the Project Name and Directory Name and click OK.
5.	Once the project is created, you will see it in the System Navigator.

Create Event Structures using the Event Structure Creation Wizard

Back to List

The initial step to use Oracle Database Rules Manager is to create event structures. The Rules Manager Event Structure Creation Wizard will create event structures in the database as well as generate correponding Java source code to capture the event information in a Java application. (See Section Rules Manager Concepts in the Application Developer's Guide for information on Primitive and Composite events).

To create multiple primitive event structures and a composite event structure, perform the following steps:

1.	Select File > New. Click the Business Tier category and select Rules Manager under this category and Event Structure under Items.Then click OK.
2.	When the Welcome window appears, click Next.
3.	Select a database connection and click Next. The database connection chosen should be to an Oracle 10g Release 2 database with Rules Manager installed. Consult the JDeveloper help files to create new database connections. Click Next.
4.	Using the Event Structure Designer, you will create the AddFlight primitive event structure with a set of attributes to capture the flight reservation information. In the Event Structure Designer wizard, enter the name for the primitive event structure to be created in the database, the name of the Java package under which the Java class should be created, and the name of the Java class. Note that the SQL object type created in Oracle Database for this particular event structure is discussed in the Oracle Database Application Developer's Guide - Rules Manager and Expression Filter, 10g Release 2, under the section "Creating a Rules Application that Uses Composite Events". P>
4.	Under Attribute List specify the list of attributes for the AddFlight event structure and choose the appropriate SQL type and the Java Class (or Type) for each attribute. At this time any user-defined functions, packages, or types required to form the rule conditions on this event structure can be added to the event structure using the Associated User-Defined Objects portion of the Event Structure Designer. Once all the necessary information is filled in, click Finish to create the event structure.
5.	The event structure creation step, in addition to creating the event structure in the database, also creates a Java class with the specified name. The source for this class is generated to include the list of attributes specified for the event structure, along with a set of methods to set/get the attribute values, and a few other methods to facilitate processing rules using instances of this class. Review the generated source code and save the workspace.
6.	For the rules application involving composite events, follow the steps described previously (steps 1 through 6) to create another primitive event structure, AddRentalCar with a set of attributes that capture a rental car reservation.
7.	Now create the composite event structure by following the same set of steps. A composite event structure differs from a primitive event structure in that all of its attributes are configured with primitive event structure types. For example, create the composite event structure TSCompEvent by choosing the corresponding primitive event structures (AddFlight and AddRentalCar) as its attribute types. After selecting the attribute names and the Java classes that represent the corresponding primitive event types, click Finish to create the composite event structure. Review the Java code that was generated for the event structures and save your workspace.

Create a Rule Class using the Rule Class Creation Wizard

Back to List

Use the composite event structure, TSCompEvent, created in the previous section, to create a rule class to store the rules defined on this event structure. Perform the following steps to create the rule class:

1.	Select File > New. Click the Business Tier category and select Rules Manager under this category and Rule Class under Items. Then click OK.
2.	Click through the Welcome screen and select a database connection to display the Rule Class designer. Specify the values for the following fields: Rule Class Name: Specify a name for the rule class in the database. Event Structure Name: The name of an event structure associated with the rule class. The list of event structures in the current JDeveloper project is displayed in a pull-down menu. In order to specify rules involving AddFlight as well as AddRentalCar events, select the TSCompEvent composite event structure. Action Callback procedure name: The name of the action callback procedure that is used to implement rule actions in the database. The implementation for this procedure can be added by choosing the appropriate database connection using the Connection-Navigator, then the Procedures list, and the specific procedure. Package Name: Name of the Java package in which the rule class Java source is created. Java Class for Rule Class: Name of the Java class that represents the rule class in the Java application. Action Categories: User-specified list of action preference categories and their data types. The action preference categories, also called the action categories, hold the values that determine the approriate action for each rule, implemented as user-defined application logic in the Action Callback Procedure or the user's application. Rule Class Description: Description for the rule class. After specifying the values for the above fields, select the type of the rule class to be created, and click the Rule Class Properties button to customize the rule class for the specific application.
3.	The Composite Rule class Property Editor allows specification of Event Management policies for the rules application (See Section Event Management Policies in the Application Developer's Guide for information). The Execution Ordering specifies the order in which actions for matching rules are executed. For instance, when the Execution ordering for the current application is set to FLT.DEPART, CAR.CHECKOUT, multiple flight and car event instances matching a set rules are sorted based on the values for the flight departure and the car checkout dates. Use the Execution Ordering menu to choose an event attribute or a rule action preference category and click Add button. One or more attributes and action categories can be specified for the Execution Ordering by clicking Add button after each selection. The Equal property for the rule class identifies the equality join predicates that relate multiple primitive events within each composite events. Use the Equal menu to choose an attribute from each event structure and click Add after each selection to specify the Equal property. Choose appropriate Event Duration and Auto Commit properties for the rule class. To specify certain properties for one type of primitive event structure, select the event structure name under Member Events and click Edit to invoke the Rule Class Member Object property editor.
4.	In the Rule Class Member Object Property editor, specify the Consumption policy for the AddFlight event structure and click OK. After reviewing the resulting Composite Rule class Properties in the editor, click OK. Now click Finish on the Rule class Designer window to create the rule class in the database and generate the Java source in the current project.
5.	Review and optionally edit the Java class, CompTravelPromo, created in the current JDeveloper project. This Java class is created with a set of methods to process the rules for the corresponding primitive events (instances of AddFlight and AddRentalCar classes) in two ways: Rule Action execution in the database with invocation of static methods processRules. Session oriented rule evaluation of rules, where the results from adding a set of events using member methods addEvent are returned back to the application as a SQL ResultSet with a getMatchedRules method call. In this scenario, a new session is started when an instance of the CompTravelPromo class is created, and it can be reset with a resetSession method call. The previous screen shot shows the structure of the Java class created for the CompTravelPromo rule class. The following screen shot shows the source code for the same Java class. Note that the details about the database instance in which the Event Structure and the Rule Class are created is captured in the connect string (jdbc:oracle:thin:@stacm34:1521:rlm8) embedded in the generated source code. At runtime, the password for the database schema in which the rule class is created can be set using the setDBPassword method.

Create Rules using the Rule Creation Wizard

Back to List

Now you can add one or more rules to the rule class created in the previous step. The rules can be added to the rule class, one at a time, using the Rules Create Wizard. Perform the following steps to create a rule in the CompTravelPromo rule class. The rule created with these steps is for a composite event involving conjunction (AND) of two events, Flt and Car (instances of AddFlight and AddRentalCar event structures respectively).

1.	Select File > New. Click the Business Tier category and select Rules Manager under this category and Rule under Items. Then click OK.
2.	Click through the Welcome screen and select a database connection to display the Rule Designer. Choose the rule class CompTravelPromo from the pull-down menu and specify a unique identifier for the rule being created in this rule class. Also, provide an english description for the rule in the Rule Description field. The equivalent SQL and XML based rule condition can be typed into the Rule Condition field or it can be constructed graphically using the Rule condition editor. Click the Build button to lauch the Rule condition editor.
3.	Using the right-click menus for the condition node visible in the rule editor, choose Add AND of primitive events to start with a conjunction of primitive events.
4.	From the right-click menu of the AND of Primitive Events, choose Add Primitive Event and then add the events, FLT and CAR, to the rule condition.
5.	Using the right-click menus for the FLT and CAR primitive events, specify the conditional logic with the event attributes.
6.	From the right-click menu of the AND of Primitive Events node, select Add attributes and then Add EQUAL Attribute to specify the EQUAL attribute for the rule condition.
7.	After reviewing the rule condition, click OK to close the Composite Rule Condition Editor and return to the Rule Designer.
8.	Review the SQL and XML based rule condition generated by the rule editor and click the Rule Action Preferences to specify the action preference values for the rule.
9.	Specify the values for the action preferences required by the action callback procedure as defined in steps 2 and 3 under "Create a Rule Class using the Rule Class Creation Wizard". Click OK on the Advanced Rule Builder and click Finish on the Rule Designer to create the rule in the rule class.

Repeat these steps to create more rules in the rule class.

Complete the Rules Application

Back to List

Complete the rules application by creating events and processing the rules for these events. For testing purposes you can create a Java class that creates one or more instances of the AddFlight and AddRentalCar classes and invokes the methods in the CompTravelPromo class to obtain the results from processing the rules in the rule class for these instances (events).

A sample application making use of the Java classes generated in the previous steps is shown below. The implementation in the screen shot creates two events as instances of corresponding Java classes and evaluates the rules defined in the CompTravelPromo rule class. This implementation uses session-based evaluation of rules, where the events are added to an instance of CompTravelPromo class and a SQLResultSet for the matched rules is returned with the getMatchedRules method.

Once you have successfully tested this rules application with Java, the generated source code for the Event Structures and the Rule Class can be included in any Java application needing to process the rules for the instances of AddFlight and AddRentalCar Java classes.

Module Summary

In this module, you learned how to:

	Invoke the Rules Manager Wizards to create a Rules application in the database.
	Use the source code generated by JDeveloper to build a Java application with rules functionality.

Close Window