Automate the
Configuration
- User's Guide
This document is essentially a tutorial to
add a configuration rule for a JASMINe
diagram. It explains too how to use these rules.
Automate the Configuration - User's Guide
Guillaume SOLDERA
Published May 6, 2008
Abstract
This document is essentially a tutorial to add a configuration rule for a JASMINe diagram. It explains
too how to use these rules.
Table of Contents
1. The rules engine .................................................................................................... 1
1.1. The RulesEngine plugin ............................................................................... 1
1.1.1. The RuleView ................................................................................... 1
1.1.2. The extension point .......................................................................... 1
1.2. Add a rule ................................................................................................... 2
1.2.1. Required elements ............................................................................ 2
1.2.2. Create an Eclipse plugin ................................................................... 3
1.2.3. Classpath ......................................................................................... 6
1.2.4. Add a drools file ............................................................................... 6
1.2.5. Complete the "plugin.xml" file ............................................................ 8
1.2.6. Notes for rule writing ....................................................................... 10
1.2.7. Export your plugin ........................................................................... 14
1.3. The Rule View .......................................................................................... 16
iii
Chapter 1. The rules engine
1.1. The RulesEngine plugin
1.1.1. The RuleView
A rules engine has been added to the JASMINe's interface. With this rules engine, the user
can automate the configuration of all middlewares designed. The rules engine has been
plugged to the JASMINe's interface.
So a new view is available. This view is accessible by Window → ShowView → Other... →
Rules Egine → RuleView .
This view presents the several available rules. The rules are grouped by "Rule Set". If the
"Rule Set" contains variables, these variables can be assigned with the "Configure Rule"
button.
You have an example in this section
1.1.2. The extension point
This plugin defined an extension point too. This extension point allow an user to add a rule to
the rules engine. A Rule Set is defined by an ID, a name (which is printed in the Rule View)
and the file name (which contains the rules).
A Rule Set can contain variables. A variable is defined by a label, a type (which match with
the variable's type), an id, and a description.
1
The rules engine
So, to add a rule to the rules engine, the user must create a plugin which extends this
extension point.
1.2. Add a rule
1.2.1. Required elements
1. Eclipse IDE
To begin, you must have Eclipse IDE and the plugins allowing the plugin development. If
ou don't have it, you can download "Eclipse for RCP/Plugins developers" at the following
adress : http://www.eclipse.org/downloads/
Then, unzip the archive file to install Eclipse IDE.
2. Drools Plugin
To be able to write a correct drools file (file where are defined rules), you have to download
the drools plugin for Eclipse. You can download this plugin at the following adress : http://
www.jboss.org/drools/downloads.html
Unzip the archive file and add this plugin to the others Eclipse plugin in your Eclipse
installation directory.
3. To correctly write a drools rule
The syntax and the keywords to correctly write a drools rule are explained at the following
adress : http://downloads.jboss.com/drools/docs/4.0.7.19894.GA/html_single/index.html
2
The rules engine
1.2.2. Create an Eclipse plugin
Launch the Eclipse IDE.
Then click on File → New → Project and choose Plug-in project in Plug-in Development
directory
Click "Next" then enter your project Name. This name must begin by "org.ow2.jasmine.rule".
Then click on Next. Let the default parameters and click again on Next. Now you have
differents templates. Choose "Rule Wizard" and click on Next. Enter a Rule ID and a Rule
Name. Then click on "Finish".
3
The rules engine
4
The rules engine
5
The rules engine
1.2.3. Classpath
Your rule plugin will be compiled after that JASMINe application started. So you must add
a library.
In "Runtime" tab of "plugin.xml", in "Classpath" section, click on "New" button and enter "."
as new library name (if only this library isn't in the classpath) and click on "Ok".
1.2.4. Add a drools file
Now, you must create a drools file. So, you can use the drools wizard which allow you to
create a drools file.
Click on "New Rule resource" to create a "drl" file. You must create this file in the main
directory :
6
The rules engine
To see syntax errors in your drl file, you must convert your project in a Drools project in spite
of the fact that normally, it should be work without this step...
So right click on project name and choose "Convert to Drools Project" :
7
The rules engine
Now, if you do a syntax error in your drl, Eclipse IDE will show it.
A new entry "Drools Library" is now available in the package explorer of your plugin. You can
remove it from build path and the dynamcal compilation will always work (bug in drools ?)
1.2.5. Complete the "plugin.xml" file
You must complete the extension in "plugin.xml" file. You must specified the drools file name.
In "Extension" tab of "plugin.xml" file, enter the drools file name in "file" properties of "ruleset" element and the Java class name which will contain actions to execute.
The Java class must be created in the main package (org.ow2.jasmine.rules.XXX). Click
on "class*" to create the Java class.
8
The rules engine
If your rule needs parameters, you can defined its. Right click on "Rule set" element and
choose variable.
Then enter the good informations for this variable.
9
The rules engine
1.2.6. Notes for rule writing
1.2.6.1. Variables
If your rule needs parameters, you must define a global variable in your drools file. The
variable's name must be the same name that you entered in "label" properties of your defined
variable.
1.2.6.2. Call your Java method
In your drools file, you can call your Java method.
In the class created , you must override a method named "configure()". In this method, just
write the Java code which will modify JASMINe objects.
package org.ow2.jasmine.rules.jonasportsrule;
import org.objectweb.jasmine.ui.jasminemodel.IRMIRegistry;
import org.objectweb.jasmine.ui.jasminemodel.datatype.Port;
import org.ow2.jasmine.rulesengine.ExecuteTransaction;
public class JOnASPortsRule extends ExecuteTransaction{
private IRMIRegistry registry;
private int newValue;
...
@Override
public void configure() {
registry.setPort(new Port(newValue));
}
But you must initialize the used attributes. So write a Java method which will give values to
the attributes and which will launch the change. It's this method that you must call in your
drools file.
In your drools file, call your rule in this way :
new JOnASPortsRule().rmiPortEnd(registry, portEnd);
To launch the change, don't forget the call to "execute()" method. This method is in
"ExecuteTransaction" class.
package org.ow2.jasmine.rules.jonasportsrule;
import org.objectweb.jasmine.ui.jasminemodel.IRMIRegistry;
import org.objectweb.jasmine.ui.jasminemodel.datatype.Port;
10
The rules engine
import org.ow2.jasmine.rulesengine.ExecuteTransaction;
public class JOnASPortsRule extends ExecuteTransaction{
private IRMIRegistry registry;
private int newValue;
public void rmiPortEnd(IRMIRegistry registre, Integer portEnd) {
registry = registre;
int actualValue = registry.getPort().intValue();
newValue = actualValue - (actualValue % 10)+ portEnd.intValue();
execute();
}
...
If you have an error case in your rule, you can print an error message.
To do this, use the "printErrorMessage(String message)" method.
printErrorMessage("The "+jonas.getInstanceName()+" instance haven't a 'JasmineNode'");
You can print this message in 'Problem' tab and on the diagram too.
To do this, use the "createMarkers(String message, Object target, Object containerTarget)"
method.
This method will create a 'Marker' in 'Problem' tab, the "target" parameter will be what is will
be printed in 'Location' column of 'Problem' tab.
This method will create a 'Decorator' on the diagram too. The "containerTarget" parameter
matches with the midlleware where the error has been detected.
11
The rules engine
createMarkers("The "+jonas.getInstanceName()+" instance haven't a
'JasmineNode'",jonas.getName(), jonas);
You must import the package in the drools file to be able to access to methods that you
have written. Then write your rule.
In the WorkingMemory, it's the "Domain" object which is inserted. So write your rule
accordingly.
#created on: 30 avr. 2008
package JOnASPortsRule
#list any import classes here.
import org.objectweb.jasmine.ui.jasminemodel.JOnAS;
import org.ow2.jasmine.rules.jonasportsrule.*;
global Integer portEnd;
rule "rmi ports"
agenda-group "rmi Port"
when
domain : Domain()
jonas : IMiddlewareComponent() from domain.getMiddlewareComponents()
then
if (jonas instanceof JOnAS)
{
for (int i=0; i<((JOnAS)jonas).getRmiRegistries().size(); i++)
{
new JOnASPortsRule().rmiPortEnd(((JOnAS)jonas).getRmiRegistries().get(i), portEnd);
}
}
end
Then, you must add this package to section "Exported Package" of "plugin.xml" file. For this,
click on "Add" button and enter the package name, then click "Ok".
12
The rules engine
1.2.6.3. Print your rule in the Rule View
To be printed in the Rule View, your rule must be have an "agenda-group". If a rule hasn't
"agenda-group", this rule won't be printed in the Rule View and this rule won't be executed.
rule "rmi ports"
agenda-group "rmi Port"
when
...
then
...
end
1.2.6.4. Complete example
The drl file :
#created on: 30 avr. 2008
package JOnASPortsRule
#list any import classes here.
import org.objectweb.jasmine.ui.jasminemodel.JOnAS;
import org.ow2.jasmine.rules.jonasportsrule.*;
#declare any global variables here
global Integer portEnd;
rule "rmi ports"
agenda-group "rmi Port"
when
domain : Domain()
13
The rules engine
jonas : IMiddlewareComponent() from domain.getMiddlewareComponents()
then
if (jonas instanceof JOnAS)
{
for (int i=0; i<((JOnAS)jonas).getRmiRegistries().size(); i++)
{
new JOnASPortsRule().rmiPortEnd(((JOnAS)jonas).getRmiRegistries().get(i), portEnd);
}
}
end
rule "Other Rule"
agenda-group "otherRule"
when
...
then
...
end
And the Java class code :
package org.ow2.jasmine.rules.jonasportsrule;
import org.objectweb.jasmine.ui.jasminemodel.IRMIRegistry;
import org.objectweb.jasmine.ui.jasminemodel.datatype.Port;
import org.ow2.jasmine.rulesengine.ExecuteTransaction;
public class JOnASPortsRule extends ExecuteTransaction{
private IRMIRegistry registry;
private int newValue;
public void rmiPortEnd(IRMIRegistry registre, Integer portEnd) {
registry = registre;
int actualValue = registry.getPort().intValue();
newValue = actualValue - (actualValue % 10)+ portEnd.intValue();
execute();
}
@Override
public void configure() {
registry.setPort(new Port(newValue));
}
}
1.2.7. Export your plugin
When your plugin is finished, you must export it. For this, right click on project and select
"Export".
14
The rules engine
Then choose "Deployable plug-ins and fragments" and click on "Next".
15
The rules engine
On the next screen, your plugin is normally selected. If it's not, select it. Choose the
destination and click on "Finish".
In directory destination, a named "plugins" directory has been created. It contains a jar file
matching with your plugin. So copy this jar file in "plugins" directory of "jasmine-console"
directory.
1.3. The Rule View
Launch JASMINe UI, show "Rule view" view.
16
The rules engine
The "Configure Rules" button allow to enter a priority for a rule and set possible variables :
17