| The OpenRulesTM Tutorials Home |
|
User's Guide |
Data and Object Modeling
How Rules and Forms Define Data Types And Test Data
Data Types Independence [T]
Excel-based Datatype and Data Tables
How Datatype Tables Are Organized
How Data Tables Are Organized
Predefined Datatypes
Accessing Excel Data from Java - Dynamic Objects
Finding Data Elements Using Their IDs [T]
Cross-References Between Data Tables [TT]
How Rules and Forms Define Data Types And Test Data ►top
OpenRules framework helps to create two critical components of complex Web applications:
- Rules for business logic
- Forms for presentation logic.
In spite of the importance of these components they are just components of a larger system, and such, they should be pluggable into any application development environments. But how about the data that rules and forms are dealing with?
We assume that in many cases the Information Modeling has been already done. It means that all major concepts, objects, attributes, domains, relationships have already been specified using the classical OOA/OOD techniques , UML and/or MDA approach. In the Java world, the results of data/object modeling usually presented in Java classes and related XML files. To be pluggable into the existing environment, business rules and forms should be able to understand the existing datatypes. And as we describe below, this is a very important differentiating feature of OpenRules.
However, OpenRules also includes an ability to define new data/object types and create the objects of these types directly in Excel. It allows business analysts to do Rule Harvesting by defining business terms and facts without worrying about their implementation in Java, C#, or XML. It also provides an ability to test (!) the business rules in a pre-integrated mode. To do standalone rule testing, a designer of rules and forms specifies his/her own data/object types as Excel tables and create instances of objects of these types passing them to rule tables. We describe how to do it in the sections below.
There is one more important reason why a business or even a technical specialist may need data modeling abilities without knowing complex software development techniques. In accordance with the SOA principle of loosely couple services, rule services have to specify what they actually need from the objects defined in the external environments. For example, if an object "Insured" includes attributes related to a person's military services it does not mean that all business rules that deal with the insured are interested in these attributes. Such encapsulation of the only essential information in the Excel-based data types together with live process modeling, allows OpenRules to complete rules modeling cycle without leaving Excel.
Data Object Types Independence [T] ►top
OpenRules provides the means that make business rules and forms independent from a concrete implementation of such concepts. The business logic expressed in the decision tables should not depend on the implementation of the objects these rules are dealing with. For example, if the rules says: “If driver's age is less than 17 then reject the application” the only thing this business rule should "know" about the object “driver” is the fact that it has a property “age” and this property has a type that support a comparison operator “<” with an integer. It is a question of configuration if the Driver is a Java class or an XML file or a DB table from a legacy system. Similarly, if a form has an input field "Driver's Age", the form should be able to accept a user's input into this field and automatically convert it into the proper object associated with this field independently of the fact how this object was implemented.
Thus, OpenRules supports data source independent business rules (decision tables) and web forms. Your business rules can work with an object of type Customer independently of the fact that this type is defined as a Java class, as an XML file or as an Excel table. You can see how it can be done using examples HelloJava, HelloXML, and HelloRules from the OpenRules's standard installation. It is a good practice to start with Excel-based data types. Even if later on you switch to Java classes of other data types, you always would be able to reuse Excel-based types for a standalone testing of your rules-based applications.
Excel-based Datatypes and Data Tables ►top
OpenRules allows a non-technical user to represent different data types directly in Excel and define objects of these types to be used as test data. Actually, it provides an ability to create in Excel Intelligent Business Glossaries that define problem specific business terms and facts. At the same time, a business glossary can include data types specified outside Excel, for example in Java classes or in XML files. Here is an example of a simple data type "PersonalInfo":
Now we can create several objects of this type "PersonalInfo" using the following data table:
We can reference to these objects inside rules or forms like in the following snippets:
out(personalInformation["He"].lastName);
if (personalInformation["She"].state.equals("NJ")) ...You may use one datatype (such as PersonalInfo) to define a more complex aggregate datatype like TaxReturn in this example:
You may even create an object of the new composite type "TaxReturn" using references to the the objects "He" and "She" like in this example:
Now we can reference to these objects inside rules or forms like in the following snippet:
out(taxReturn[0].taxPayer.lastName);
The above tables may remind you traditional database tables just presented in Excel. While these examples gives you an intuitive understanding of OpenRules Datatype and Data tables, the next sections will provide their formal descriptions.
Starting with the OpenRules 5.0 you may use a new type of tables "Variable". These tables are similar to the Data tables but instead of arrays of variables they allow you to create separate instances of objects directly in Excel files. Here is a simple example:
Variable Customer mary name age gender maritalStatus Name Age Gender Marital Status Mary Brown 5 Female Single The variable "mary" has type Customer and can be used inside rules or passed back from an OpenRulesEngine to a Java program as a regular Java object. As usual, the object type Customer can be defined as a Java class, an Excel Datatype, or an xml structure.
How Datatype Tables Are Organized ►top
Every Datatype table has the following structure:
Datatype tableName
AttributeType1 AttrubuteName1 AttributeType2 AttrubuteName2 .. .. .. .. The first "signature" row consists of two merged cells and starts with the keyword "Datatype". The "tableName" could be any one word valid identificator of the table (a combination of letters and numbers). The rows below consist of two cells with an attribute type and an attribute name. Attribute types can be the basic Java types:
- boolean
- char
- int
- double
- long
- String (java.lang.String)
- Date (java.util.Date)
You may also use data types defined:
- in other Excel Datatype tables
- in any Java class with a public constructor with a single parameter of the type String
- as one-dimensional arrays of the above types.
The datatype "PersonalInfo" gives an example of a very simple datatype. We can define another datatype for a social security number (SSN):
and add a new attribute of this type to the datatype "PersonalInfo":
It is interesting that these changes would not effect already existing data objects defined above (like personalInformation["He"]) - their SSNs just will not be defined.
Implementation Restriction. Make sure that the very first attribute in the Datatype table has type String or your own type (but not a basic Java type like int).
The following example demonstrates how to create a Data table for a Datatype that includes one-dimensional arrays:
Datatype Order String number String[] selectedItems String[] offeredItems double totalAmount String status Here is an example of the proper Data table:
Data Order orders number selectedItems totalAmount status Number Selected Items Total Amount Status 6P-U01 INTRS-PGS394 3700 In Progress INTRS-PGS456 Paste-ARMC-2150 You may also present the same data in the following way:
Data Order orders number selectedItems totalAmount Number Selected Items Total Amount Item 1 Item 2 Item 3 6P-U01 INTRS-PGS394 INTRS-PGS456 Paste-ARMC-2150 3700
How Data Tables Are Organized ►top
Every Datatype table has a vertical or horizontal format. The typical vertical Data table has the following structure:
Data datatypeName tableName
AttributeName1 from "datatypeName" AttributeName2 from "datatypeName" AttributeName3 from "datatypeName" ... Display value of the AttributeName1 Display value of the AttributeName2 Display value of the AttributeName3 ... data data data ... data data data ... ... ... ... ... The first "signature" row consists of two merged cells and starts with the keyword "Data". The next word should correspond to a known datatype: it can be an already defined Excel Datatype table or a known Java class or an XML file. The "tableName" is any one word valid identificator of the table (a combination of letters and numbers).
The second row can consists of cells that corresponds to attribute names in the data type "datatypeName". It is not necessary to define all attributes but at least one should be defined. An order of columns is not important.
The third row contains for each attribute its display name (you may use an unlimited natural language).
All following rows contain data values with types that correspond to the types of the column attributes.
Here is an example of the Data table for the datatype "PersonalInfo" defined in the previous section (with added SSN):
The table name is "personalInformation" and it defines an array of objects of the type PersonalInfo. The array of the picture consists only of two elements personalInformation[0] for John and personalInformation[1] for Mary. You may add as many data rows as necessary.
The attributes after the SSN attribute have not been defined. Please, note the the references to the aggregated data types are defined in the natural way (ssn.ssn1, ssn.ssn2, ssn.ssn3) using a dot-convention.
As you can see from this example, the vertical format maybe not very convenient when there are many attributes and not so many data rows. In this case, it could be more preferable to use a horizontal format for the data tables:
Data datatypeName tableName
AttributeName1 from "datatypeName" Display value of the AttributeName1 data data data ... AttributeName2 from "datatypeName" Display value of the AttributeName2 data data data ... AttributeName3 from "datatypeName" Display value of the AttributeName3 data data data ... ... .. ... ... ... ... Here is how our data table will look like being presented in the horizontal way:
Predefined Datatypes ►top
OpenRules provides predefined Java classes to create data tables for arrays of integers, doubles, and strings. The list of predefined arrays includes:
- ArrayInt - for arrays of integer numbers
- ArrayDouble - for arrays of real numbers
- ArrayString - for arrays of strings.
Below are examples of Excel Data tables and methods for accessing these tables:
ArrayInt ArrayDouble ArrayString
Method int[] getTerms() return ArrayInt.getValues(terms); Data ArrayInt terms value Term 36 72 108 144
Method double[] getCosts() return ArrayDouble.getValues(costs); Data ArrayDouble costs value Costs $295.50 $550.00 $1,000.00 $2,000.00 $3,295.00 $5,595.00 $8,895.00
Method String[] getRegions() return ArrayString.getValues(regions); Data ArrayString regions value Region NORTHEAST MID-ATLANTIC SOUTHERN MIDWEST MOUNTAIN PACIFIC-COAST
These arrays are available inside OpenRules table just by calling their name: getTerms(), getCosts(), getRegions(). You may also access these arrays from a Java program, e.g. using this code:
OpenRulesEngine engine = new OpenRulesEngine("file:rules/Data.xls");
int[] terms = (int[])engine.run("getTerms");
System.out.println("\nTerms:");
for(int i=0; i<terms.length; i++)
System.out.println("\t"+terms[i]);
The standard installation (starting from the release 4.0) includes a sample project "DataArrays" that shows how to deal with predefined arrays.
Accessing Excel Data from Java - Dynamic Objects [T] ►top
You can access objects created in Excel data tables from your Java program. These objects have a predefined type DynamicObject. Let's assume that you defined your own Datatype Customer and created an array of Customers in Excel:
Data Customer customers name maritalStatus gender age Customer Name Marital Status Gender Age Robinson Married Female 24 Smith Single Male 19 Method Customer[] getCustomers() return customers; In you Java program you may access these objects as follows:
OpenRulesEngine engine = new OpenRulesEngine("file:rules/Data.xls");
DynamicObject[] customers = (DynamicObject[])engine.run("getCustomers");
System.out.println("\nCustomers:");
for(int i=0; i<customers.length; i++)
System.out.println("\t"+customers[i]);
This code will print:
Customer(id=0){
name=Robinson
age=24
gender=Female
maritalStatus=Married
}
Customer(id=1){
name=Smith
age=19
gender=Male
maritalStatus=Single
}
You may use the following methods of the class DynamicObject:
Object getFieldValue(String name);public
public
void setFieldValue(String name, Object value);
For example,
String gender = (String) customers[0].getFieldValue("gender");
will return "Female", and the code
customer.setFieldValue("gender", "Male");
customer.setFieldValue("age", 40);
will change the gender of the object customers[0] to "Male" and his age to 40.
When one Datatype includes attributes of other Datatype, such datatypes usually known as aggregated datatypes. You have already seen an example of an aggregated type PersonalInfo with the subtype SSN. Similarly, you may have two datatypes Person and Address, and type Person has an attribute "address" of the type Address. You may create a data table with type Person using aggregated field names such as "address.street", "address.city", "address.state", etc. The subtype chain may have any length, for example "address.zip.first5" or "address.zip.last4". This feature is a very convenient for a compact definition of test data for complex interrelated structures.
You may think about data table as database tables. There are few things that make them different form traditional relational tables and but more friendlier and easy to use in the object-oriented environment. The very first attribute in the data table is considered as its primary key. For example, the attribute "id" is a primary key in the data table "personalInformation" above. You may use its values like "He" or "She" to refer to the proper elements of this table/array. For example, to print the full name of the person found in the array "personalInformation", you may write the following snippet:
PersonalInfo pi =
personalInformation["He"];
out(pi.fisrtName + " " + pi.middeInitial + ". " +
pi.lastName);
The primary keys of one data table could serve as foreign keys in other tables to provide a cross-reference mechanism between data tables. There is a special format for data tables to support cross-references:
|
Data datatypeName tableName |
|||
| AttributeName1 from "datatypeName" | AttributeName2 from "datatypeName" | AttributeName3 from "datatypeName" | ... |
| >referencedDataTable1 | >referencedDataTable2 | ||
| Display value of the AttributeName1 | Display value of the AttributeName2 | Display value of the AttributeName3 | ... |
| data | data | data | ... |
| data | data | data | ... |
| ... | ... | ... | ... |
This format adds one more row, in which you may add references to the other data tables where the data entered into this columns should reside. The sign ">" is a special character that defined the reference, and "referencedDataTable" is a name of another known data table. Here is the example:
Both columns "TaxPayer" and "Spouse" use the reference ">personalInformation". It means that these columns may include only primary keys fro the table "personalInformation". In our example there are only too valid keys" He or She. If you enter here something else, for example "John" instead of "He" and save your Excel file, you will receive a compile time (!) error "Index Key John not found" (it will be displayed in your Eclipse Problems windows). It is extremely important that the cross-references are automatically validated in compile time to prevent much more serious problems in run-time.
Multiple examples of complex inter-table relationships are provided in the sample rule project AutoInsurance. Here is an intuitive example of three related data tables:
See more examples in the file InsuranceData.xls.
