Eclipse Plug-in for WSO2 Business Rules Server
- Denuwanthi De Silva
- Associate Tech Lead - WSO2
Introduction
Previously WSO2 BRS artifacts (aar/car) were created using the web UI rule wizard or creating the artifact by combining several artifacts. With the new WSO2 Developer Studio plug-in for rule services, one can easily create a complete deployable BRS artifact using the Eclipse IDE. Developers can easily create WSO2 BRS artifacts using this tool, and deploy it in the WSO2 Business Rules Server.
When creating WSO2 BRS artifacts using this tool, there are several approaches to insert the rule file(.drl). These approaches include creating a rule file using JBoss drools plug-in, adding a rule file that already exists in a registry or creating a rule file in the WSO2 Developer Studio Registry Resource Project and adding it.
This tutorial provides a guide on how to properly create a WSO2 BRS artifact using Eclipse IDE, and then deploying it to the WSO2 BRS.
Applies To
WSO2 BRS | 2.0.0 |
WSO2 Developer Studio | 2.2.0 |
Table of Contents
Creating a rule service project
In this section, we discuss how to create a rule service project in WSO2 Developer Studio. The rule service project created using this tool should contain POJO classes that describe the facts for the rule configuration and the rule configuration file (.rsl). It should also contain a rule file with the extension .drl, which can be created using JBoss Drools plug-in or imported from the file system.
Installing JBoss Drools plug-in
The JBoss Drools plug-in supports several functionalities, including the ability to write rule files with content assist support. The rule file is generated with basic syntax so that the developer only has to fill the conditions of the rule.
By using this Drools plug-in, we can easily create, edit, test and integrate rules to our application.
First, go to the 'Help' menu in Eclipse IDE and select the 'Install New Software' option. You will get the following window.
Now, you have to add the url of the JBoss Drools plug-in's update site. To do this , click on the 'Add' button in the above window and you will get a dialog box that is similar to the following one.
Give a name to the update site and enter the url for the update site in the 'Location' field. (update site link)
Then, the Drools plug-in will be ready to be installed.
After installing the JBoss Drools plug-in, it can be seen in the 'Resource' window. Using this resource, we can create Drools projects in the workspace.
Installing WSO2 Developer Studio
The WSO2 BRS plug-in is integrated to the WSO2 Developer Studio. Thus, we need to install WSO2 Developer Studio to the Eclipse IDE we are working on. A full guide to installing WSO2 Developer Studio can be found in this tutorial.
Creating a Maven Multi Module Project
Maven Multi Module Project is used to get the benefit of maven centric development supported by WSO2 Developer Studio. It contains a parent project with child modules that can be artifact projects, like the rule service project. Other than that, we need to have a distribution module as a child module to create deployable artifacts. In WSO2 Developer Studio, we use Carbon Application Project as the distribution module.
Using the Maven Multi Module Project, we can easily combine the necessary artifact projects and build them from the source using the command mvn clean install. When we build the Maven Multi Module Project, the deployable artifact will be created in the target folder of the Carbon Application Project.
The Maven Multi Module Project is also a plug-in provided by WSO2 Developer Studio. We can create a Maven Multi Module Project from the Developer Studio Dashboard, as shown below.
A complete tutorial on creating a WSO2 Maven Multi Module Project can be found here.
For this tutorial, we created a WSO2 BRS project, WSO2 Registry Resource Project and a WSO2 Carbon Application Project as child modules within the Maven Multi Module Project.
Creating a Rule Service Project
WSO2 BRS Rule plug-in is integrated with WSO2 Developer Studio. Thus, one can easily find the BRS rule project in the WSO2 Developer Studio Dashboard.
The Project Creation Wizard for BRS Rule plug-in gives you the option of creating a new Rule Service from scratch or importing a rule configuration file (.rsl) and creating a deployable artifact out of it.
This tutorial will demonstrate creating a simple Greeting Service Project. The next page of the Project Creation Wizard asks for the Project name, Rule service name, and target name space.
After filling those fields and clicking the 'Finish' button on the wizard, a new Rule Service Project is created within the Maven Multi Module Project. The rule configuration file is displayed as a multi-page editor with Graphical view editor and source view editor as shown in the following image. The 'Service Name' and 'Target Namespace' fields get their values from the values entered to the Project Creation Wizard at the beginning.
Basic components of the project:
- Java classes - included under the java subfolder
- Rule configuration file – included in the META-INF folder, which is under the ruleservice subfolder
- Rule file – included in the conf folder
Initially, only the rule configuration file is generated within the project hierarchy.
Adding a Rule file
A Rule file contains the rules defined for the particular scenario. In this plug-in, we can enter Rule details to the 'Rules' table. When you click on the 'Add' button of the 'Rules' table, you get a Dialog where you can enter the Rule details. The 'Description' field is not mandatory. The user can select 'Resource Type' from the drop-down menu, where the default value is set to 'regular'. The 'Source Type' field is used to provide the Rule file(.drl). There are four options to enter the rule file in the 'Source Type' field: the first is to provide the rule file 'inline' - the user can easily copy the content of a rule file and paste it in the 'inline' section; the next way is to provide the url of the rule file in the 'URI' section; the next two methods are to enter the rule file from 'registry' and by browsing the rule file from the file system. In this tutorial, we discuss the last two methods, as they are the ones that are widely used.
Creating Rule File using drools plug-in
A user can create a rule file using JBoss drools plug-in and give that file as the rule definition for the rule configuration file. If you have already installed JBoss drools plug-in in eclipse, as mentioned at the beginning of this tutorial, you can now create a new rule file for the Rule Service Project.
The Rule files (.drl) are stored in the 'conf' folder. Thus, the rule file from the JBoss drools plug-in should be created inside the 'conf' folder. Select the 'Rule Resource' option to create the Rule file.
Give any name to the Rule file name and give a package name too as shown below.
The generated Rule file will look as follows. The essential structure of a general rule file is already created by the JBoss drools plug-in that makes it easier for a developer to work on the IDE. A developer only has to fill the conditions and actions for each rule.
To write the rule file, we need to create Facts classes, which define the Facts and Results. Facts classes are normal java classes and added to the 'java' folder in the 'GreetingServiceProject'. For this project, we need two Facts classes; they are User.java and GreetingMessage.java.
Now, we can complete the rule file by importing the necessary Facts classes.
Now, to add this rule file to the rule configuration file, we can click on the 'Add' button of the 'Rules' table of the graphical editor and the below 'Dialog' will appear. In the 'file' tab, we have a drop-down menu to select the rule files added to the 'conf' folder. In this scenario, the 'greeting_rules.drl' file is displayed in the drop-down menu. We can select it and click on 'Finish' to send them to the table.
After adding the rule file, the table in the graphical editor will be updated as follows:
The source editor will be updated as follows:
Adding a Rule file that already exists in a registry
Instead of using the JBoss drools plug-in and creating the rule file and adding it, we can upload the rulefile to an existing WSO2 configuration or Governance registry and access that rule file from our Business Rules Service Project in eclipse and refer it in the rule configuration file.
In this scenario, the rule file will be uploaded to the Config registry. To do that, log in to the latest WSO2 Business Rules Server and in the 'Registry' section, select 'Browse' and select the 'config' option.
After uploading the rule file (.drl) to the config registry, it will be displayed as follows.
Now, to add that rule file as an entry in rule configuration file generated by the Business Rules Service plug-in, select the 'registry' tab of the 'Input Dialog' that appears when clicking on the 'Add' button of the 'Rules' table. Here, you can use the 'Registry Browser' button to navigate through the 'Config' or 'Governance' registry to get the rule file.
When you click on the 'Registry Browser' button, a small window, as shown below, will be displayed. It is the default registry browser window used throughout many WSO2 Developer Studio products.
When you select the 'registry' link on that window, the following window will appear.
Since the rule file was uploaded to the configuration registry in the WSO2 Business Rules Server, we can add a new registry connection to the 'Config' registry as follows.
Then a tree view of the 'config' registry will be visible, where we can see the rule file (greeting.drl) we uploaded to the configuration registry in an earlier step.
After selecting the rule file from the 'config' registry, it is added to the 'Resource URI' field as follows:
Adding Rule file as a Registry Resource
Unlike the earlier method, we can create a new WSO2 Registry Resource Project within the Maven Muli Module Project, and add the rule file as a resource in there. Thereafter, we should create a Carbon Application archive containing both the Registry Resource Project and Business Rules Service Project. Thus, we eliminate the need to upload a rule file to a registry in the WSO2 server. When the .car file is deployed, the rule file in the Registry Resource Project will be added to the registry.
Create a new Registry Resource Project within the Maven Multi Module Project.
Once the Registry Resource Project is created, add a new Registry Resource to it.
Add a rule file (greeting.drl) as a registry resource. Then an editor will be opened as in the following image. Here, the 'Resource Deploy Path' is set to default '/_system/custom', but it should be changed as '/_system/config' or '/_system/governance' .
Thereafter, to add this rule file as an entry in the rule configuration file, select the 'workspace' link in the Registry Browser Dialog box. Then, it will show the rule file as a registry resource in the Registry Resource Project.
Adding Operations
To add 'Operations' to the rule configuration file via the graphical editor, another table is used. It is labeled the 'Operations' table. To add an operation, we can click on the 'Add' button near the table, and then a dialog box will appear as shown in the image below. We can add the necessary details to the fields in the dialog box.
To enter 'Facts' details, another table is used inside the 'Operation' dialog box. It provides the facility to select the 'Fact Type' from a drop-down menu, which are the java classes created in an earlier step.
After entering data for input and output facts, those details will be updated to the 'Operations' table. This is the final view of the graphical editor after entering all the necessary details that should come in the rule configuration file.
The source view of the rule configuration file generated by the input given by graphical editor is as follows:
Deploying the BRS artifact
To create a deployable artifact that is, a .aar file of the Business Rules Service Project, we have to first create a Carbon Application Project, where we can include all the necessary projects we have created so far within the Maven Multi Module Project. Thereafter, we can build the Maven Multi Module Project using the mvn clean install command. Then, the .car file will be created inside the target folder of the Carbon Application Project. Finally, we can upload that file to the WSO2 Business Rules Server and invoke the intended service.
Deploying Business Rules Service projects, where rule file was created from drools plug-in or rule file was taken from a registry
Create a new Carbon Application Project within the Maven Multi Module Project.
Under 'Dependencies' select the Business Rules Service Project you created.
The Carbon Application Project will be created within the Maven Multi Module Project. Make sure to select the server role as 'Business Rules Server'. Then, create the .car archive by clicking on the 'Create Archive' button in the Capp project.
Next, go to the Maven Multi Module plug-in from the terminal, and build it using the 'mvn clean install' command. Thereafter, the .car file will be created in the target folder of Carbon Application Project.
Now, go to the WSO2 Business Rules Server instance you are running, and go to 'Carbon Applications' and select 'Add'. Then, you will get a user interface where you can upload the .car file created earlier.
After uploading the .car file it will be displayed under the Carbon Application list.
Then in 'Services' go to the 'list'. The service you created will be displayed. Now, you can try the service.
Deploying Business Rules Service projects where rule file is a Registry Resource
As in the earlier section, Create a Carbon Application Project. In dependencies, select the Business Rules Service project as well as the Registry Resource Project.
When the Carbon Application Project is created, make sure to make the server role as 'Business Rules Server' for both Business Rules Service Project and the Registry Resource (rule file) inside the Registry Resource Project.
Conclusion
This article provides a step-by-step description on how to create a WSO2 Business Rules Service Project in the WSO2 Developer Studio and then describes how to deploy generated artifacts in different scenarios.
References/Resources
- [1]https://dist.wso2.org/products/developer-studio/2.1.0/docs/install_guide.html
- [2]https://wso2.org/project/developer-studio/docs/devs_maven_support.html
- [3]https://download.jboss.org/drools/release/5.4.0.Final/org.drools.updatesite/
Author
Denuwanthi De Silva, Trainee Software Engineer, WSO2 Inc