Using .NET Business Objects as payload for Decision Services
Introduction
Microsoft .NET Classes provide applications with reusable, portable code. Classes are logical sections of an application. For instance, the call to a database and retrieval of table data is part of a data class. These classes can be used in other sections of the application, or can be used it in an entirely different software design.
Class properties that allow other areas of code to interface with the class are usually created with get and set keywords.
Corticon Server for .NET can communicate with .NET classes through a Java Object Messaging (JOM) interface. This topic shows how a client program can instantiate a .NET class and then use that object instance to communicate with Corticon Server for .NET. In other words, this enables Corticon Server for .NET to natively bind to the application’s .NET class definitions during rules execution.
Note: For information about setting up Java object mapping and inheritance, see Java object mapping in the Integration and Deployment Guide.
To use the JOM interface from any C# client application, it is necessary to create Java stubs that match the C# object model. These stubs will enable Corticon Studio Vocabulary Editor to import the class metadata for mapping purposes; in other words, to pull in the names of the get and set methods needed. The stubs are also used to generate import statements in the compiled rules.
At deployment time, the Corticon Server for .NET will dynamically transform the Rule asset from Java byte code into .NET Common Intermediate Language (CIL), the object-oriented assembly language for .NET runtime environments. When this is done, the Java code stub references inside the stub library (a .jar file) are translated into references to the actual C# class file library (a .dll file). Finally, the translated Rule asset (CIL) will directly call get/set methods on the C# object during Rule asset execution.
IKVM.NET
To create Java Stubs from .NET class files, Corticon supplies an open source utility, IKVM.NET, which is an essential component of the Corticon Server for .NET runtime architecture enabling it to seamlessly operate in .NET environments. IKVM.NET is included in your Corticon Server for .NET installation.
Note: For more information about IKVM.NET, see their web site, http://www.ikvm.net.
IKVM.NET is an implementation of Java for Mono and the Microsoft .NET Framework. It includes the following components:
A Java Virtual Machine implemented in .NET
A .NET implementation of the Java class libraries
Tools that enable Java and .NET interoperability
Running the sample Java Object Messaging (JOM) client application
The sample JOM Client uses C# objects to communicate with Corticon Server for .NET (in- process) via the object messaging interface.
Run this sample program by launching [CORTICON_HOME]\Server .NET\samples\bin\JomClient.exe)
When the application launches, the window lets you enter parameter values for executing this decision service:
Name
Age
Is this person a skydiver?
Enter values, and the click Execute to see the decision.
You might wonder how this application was created and how it works. Let’s examine its building blocks. When you understand the solution architecture, it will be easy to create your own examples and solutions.
Examining the sample
The sample JomClient.exe uses a Rulesheet. Open [CORTICON_NET_WORK_DIR]\Samples\Rule Projects\JOM\Rules\jom.RiskRating.ers:
Open the Vocabulary [CORTICON_NET_WORK_DIR]\Samples\Rule Projects\JOM\Vocab\jom.ecore. When your vocabulary has Java Object Mapping established, the Applicant Entity shows that it is bound to the Java Package cli.CorticonLibrary, and its Java Class name refers to the C_Applicant class.
Each Attribute within the Entity refers to a Java Object Get Method and a Java Object Set Method method, as shown:
So how do we get the CorticonLibrary that contains these Java classes exposed in the Corticon Vocabulary editor? Let's see.
Invoking Corticon Server for .NET
JomClient.exe is written in C#. Logic that invokes the in-process server is located for the sample at [CORTICON_NET_HOME]\samples\api-client\jom\JomClientForm.cs, as shown:
Running the sample JOM application
Now when you launch JOMClient.exe, Corticon Server for .NET will try to deploy the JOM Decision Service. As described above, the JOM .ecore has already imported the Java Stub Class Metadata. That's important for the next step. The JOM Client will first compile the [CORTICON_NET_WORK_DIR]\samples\Rule Projects\JOM\jom.erf into a deployable .eds file. For the compilation to be successful, the CorticonLibrary.jar must be in the \lib directory. During deployment of the .eds file, the IKVM loader will convert the Java byte code into CLI and also load the C# class definitions in CorticonLibrary.dll, effectively allowing JomClent.exe to use C# object instances to communicate with Corticon Server for .NET.
Preparing the C# Class files
We want the client program to instantiate C_Applicant, and then use that object instance to communicate with Corticon Server for .NET. First we’ll need a class file we are using in our application to expose all data objects. For that, we will use [CORTICON_NET_HOME]\samples\api-client\jom\CorticonLibrary.cs, as shown:
Note: Having a namespace in the CorticonLibrary.cs file is mandatory.
Compile the CorticonLibrary.cs to create the CorticonLibrary.dll. To use the JOM interface from any C# client, it is necessary to create Java stubs that match your C# object model. For the JOM Client example, we used Visual Studio to compile the C# class C_Applicant into CorticonLibrary.dll.
Save CorticonLibrary.dll to both [CORTICON_NET_HOME]\samples\gen stubs\ and [CORTICON_NET_HOME]\samples\bin\
Generating the Java Stubs
We can generate the Java stub file from CorticonLibrary.dll using the utility script [CORTICON_NET_HOME]\samples\gen stubs\GenStubs.bat:
******* @echo off SET IKVM_HOME=..\bin SET INPUT_DLL_NAME=CorticonLibrary.dll SET OUTPUT_JAR_NAME=CorticonLibrary.jar ATTRIB -R %OUTPUT_JAR_NAME% "%IKVM_HOME%\ikvmstub.exe" %INPUT_DLL_NAME% ECHO Successfully completed: C# types in %INPUT_DLL_NAME% were converted into stubs in %OUTPUT_JAR_NAME%. Pause *******
The GenStubs.bat utility will generate the JAR CorticonLibrary.jar.
Add CorticonLibrary.dll to [CORTICON_NET_HOME]\samples\bin\
Add CorticonLibrary.jar to [CORTICON_NET_HOME]\samples\lib\.
About putting the CorticonLibrary.jar in the samples\lib directory - It is important to understand where to locate the JAR file, especially when you are outside of Corticon installation directories. The JAR that the Corticon .NET Configuration (inside CorticonShared.dll) directs IKVM to load all JAR files that are located in the [CORTICON_NET_HOME]\lib directory. In the case of the JomClient.exe, the JomClient.exe defines [CORTICON_NET_HOME] equal to [CORTICON_NET_HOME]\samples. Where is this done? Each .NET Application has a .exe.config file where the user defines their Corticon Home and Work directories. For example bin\JomClient.exe has a JomClient.exe.config. Within that file is the following section:
That defines CORTICON_HOME as located up one directory level from where the .exe is currently located. Typically, the result is C:\Program Files\Progress\Corticon 5.7 .Net\Server .NET\samples. Then the CorticonConfiguration changes CORTICON_HOME by adding “\lib” which locates it in that directory where it loads all the JARs.
Supported .NET datatypes for Attributes
Corticon Attributes support .NET Business Objects with nullable datatypes. Using a trailing ? character converts the Datatype into a Nullable Datatype of the same type.
Boolean bool Boolean? bool?
Byte byte Byte? byte?
Char char Char? char?
DateTime DateTime?
Decimal decimal Decimal? decimal?
Double double Double? double?
float float?
Int16 Int16?
Int32 Int32?
Int64 Int64?
int int?
long long?
short short?
String String?
Supported .NET datatypes for Associations
Corticon Associations support .NET Business Objects.
C# Association Datatypes:
System.Collections.ArrayList System.Collections.IList <Business Object Name>[] (Array of Business Objects)
All datatypes that are supported are demonstrated in the CorticonLibrary.cs file under the ObjectA and ObjectB objects.
Using GenStubs.bat for your .NET Business Objects
To generate stubs:
1. Compile the .NET Business Objects in .cs or .vb to create a .dll file. For example, use myDotNetBo.cs or myDotNetBo.vb. to compile myDotNetBo.dll.
2. Copy the .NET Business Object .dll to the [CORTICON_NET_HOME]\samples\gen stubs\ directory.
3. Locate a text editor at [CORTICON_NET_HOME]\samples\gen stubs\ to edit GenStubs.bat.
4. Modify the following two properties to match the .dll name and the .jar name, as shown here for myDotNetBo:
SET INPUT_DLL_NAME= myDotNetBo.dll SET OUTPUT_JAR_NAME= myDotNetBo.jar
5. Save the file under an appropriate name(such as GenStubs_MyBo.bat).
6. Run your GenStubs script file to generate the Java stub JAR file.
Note: The first time you do this, you get a warning message about not finding myDotNetBo.jar: Ignore this -- it is trying to delete it first, but it isn’t there.
The Java stub JAR file you created is saved at [CORTICON_NET_HOME]\samples\gen stubs\.
7. Copy your JAR (for example, myDotNetBo.jar) to [CORTICON_NET_HOME]\samples\lib.
8. Verify the creation of the JAR file. The following example illustrates a stub class in the CorticonLibrary.jar through a Java Decompiler:
9. Open the Vocabulary in Corticon Studio, and then chose the menu command Vocabulary > Java Object Messaging > Import Java Class Metadata, as shown:
10. Browse to [CORTICON_NET_HOME]\samples\gen stubs\:
11. Select the JAR that you want imported into Corticon Studio, as well as mscorlib.jar that is also in the gen stubs directory. The mscorlib.jar needs to also be selected because the .jar file that was created through the gen stubs process depends on the classes inside the mscorlib.jar.
12. Select the packages that are associated with the Java Stub Classes that were created in the gen stubs process. In our example, the CorticonLibrary.jar contains classes under the cli.CorticonLibrary package.
Note: As noted earlier, Business Objects require a defined Namespace. If there is no defined Namespace, the Java Stub Classes will have a default package of only cli. That would force you to choose the cli checkbox, and import ALL the Java Class Metadata in the CorticonLibrary.jar and the mscorlib.jar, an unwarranted scope.
13. After import is complete, verify that the Java Object Getter/Setter Methods have been assigned to each of the Attributes and Associations. The Vocabulary tries to SmartMatch the Vocabulary Attribute and Association Names to match a Getter/Setter name in the imported Java Metadata. The SmartMatch looks for an appropriate Getter/Setter Method that begins with get or set as in get<AttributeName> or get_<AttributeName>. If this occurs, the Getter/Setter value inside the Vocabulary is colored light grey, indicating that it was determined through a SmartMatch lookup.
However, in the example above, SmartMatch is unable to match the Getter/Setter with Attribute riskRating because the appropriate Java Class Method does not conform to the SmartMatch algorithm:
Vocabulary Attribute: riskRating
Smart Match looks for: getRiskRating() or get_RiskRating()
Actual Java Method: get_StrRiskRating()
14. Since the SmartMatch failed to locate an appropriate Getter/Setter, you need to select the appropriate Getter/Setter Method from the drop-down for that Attribute or Association. Since the user defined their own mappings, the Getter/Setter method value is colored black (as illustrated).
15. After deploying the rules to IIS server, ensure that the Business Objects are picked up by copying:
myDotNetBo.jar to C:\inetpub\wwwroot\axis\lib
myDotNetBo.dll to C:\inetpub\wwwroot\axis\bin
16. When the package has been created, it will look something like this:
Testing outside IIS
If you are testing your work outside of IIS, such as in a Visual Studio Environment, you to perform some extra tasks:
1. Copy the myDotNetBO.dll to a location where it can be referenced. If running in IIS and the axis application has been deployed, the .dll needs to be moved to the c:\inetpub\wwwroot\axis\bin directory.
2. Copy the myDotNetBo.jar into the running application's [CORTICON_NET_HOME]\lib directory.
The JAR is needed during compilation of the Ruleflow (.erf) into an Enterprise Decision Service (.eds) file. The compilation step depends on the .jar file being in the [CORTICON_NET_HOME]\lib directory.
Note: About putting the JAR in the \lib directory when Business Objects are used in IIS
The CorticonConfiguration looks for CORTICON_HOME\lib. With IIS, CORTICON_HOMEcould be defined or overridden in the web.config file under [IIS]\axis.
Parameters can be set in Corticon in the <appSettings> section. Note there are no CORTICON_HOME or CORTICON_WORK_DIR settings. That means that the “current directory” is the CORTICON_HOME and CORTICON_WORK_DIR. For IIS, put the JAR file in C:\inetpub\wwwroot\axis\lib.
A Java Virtual Machine implemented in .NET
Ignore this -- it is trying to delete it first, but it isn’t there.
The Vocabulary tries to SmartMatch the Vocabulary Attribute and Association Names to match a Getter/Setter name in the imported Java Metadata. The SmartMatch looks for an appropriate Getter/Setter Method that begins with get or set as in get<AttributeName> or get_<AttributeName>. If this occurs, the Getter/Setter value inside the Vocabulary is colored light grey, indicating that it was determined through a SmartMatch lookup.