SweetRules V2.1 README
SweetRules Documentation
(for release version 2.1)
SweetRules is a toolkit for semantic web rules, revolving around the RuleML (Rule Markup Language) and SWRL (Semantic Web Rule Language combining RuleML and OWL) emerging standards for semantic web rules. Its capabilities include translation between a variety of rule and ontology languages, backward and forward inferencing, and merging of rulebases/ontologies.
SweetRules V2.0 is a unifying platform supporting interoperability across different knowledge representations by providing suitable translators. It supports inferencing on XSB, CommonRules 3.3, Jess and Jena . Situated features such as sensing and effecting are also supported (sensing support is available only through Jess, while effecting can be done using either a native action launcher for ruleml case or via Jess).
Download SweetRules from SemWebCentral you need to look for the Sweetrules project, click on it and then visit the CVS area of the project.
Unzip the package to a suitable folder such as C:\SweetRules
The directory hierarchy will appear as shown below:
If top level folder is C:\SweetRules as mentioned above, it will have
-- SweetRules (repeated)
-- src
-- lib
-- scripts
-- doc
-- 3 rd party
-- classes
The src folder has the source code for SweetRules
The lib folder will have the required jar files
The scripts folder has some utility scripts specially for converting from Common Rules 2.1 to Common Rules 3.3 format (Note: refer to the readme in the scripts folder for limitations of the conversion before you attempt using it)
The doc folder has the documentation files of the project, importantly the javadoc API documentation
Configuring the environment for SweetRules
The details of this process are given in the INSTALL.txt file under the doc folder. The important things are:
Setting the classpath in the correct order as specified in the .classpath file in the src folder (this needs a lot more detailing)
After installing xsb make sure that xsb.exe is in the PATH
Configuring the SweetConfig.ini in the lib directory by setting the variables to installation specific values (Can we generate the path for ini files more automatically otherwise we'll have to do this every time we install? Perhaps we can save a copy in c:\windows?)
While executing make sure to pass the DSWEET_LIBROOT switch to jvm with proper value,
e.g. execute SweetRules using:
java DSWEET_LIBROOT=C:\SweetRules\SweetRules\lib org.semwebcentral.sweetrules.infrastructure.SweetDriver session
This will show you a prompt, type help for further assistance
Note:
-D should appear before org.semwebcentral , i.e it must be passed to java.exe
The above command must be typed in a single line at the command shell prompt
Sweet installation consists of the following phases:
Download and unzip the package
Installation of the 3 rd party software, which includes
i. InterProlog and XSB
ii. CommonRules 3.3
iii. Jwsdp (for JAXB)
iv. Jess
v. Jena
vi. log4j
vii. junit
viii. xalan
ix. OWL API from KAON-DLP
Set CLASSPATH suitably (elaborated below)
Edit the SweetConfig.ini file to configure the installation specific parameters
Unzip the package to a suitable folder
Say C:\SweetRules
Install interProlog and the accompanying XSB engine
Follow the instructions specified in
http://www.declarativa.com/InterProlog/INSTALL.htm
(Prefarably install it in C:\XSB)
Make sure:
- Install the XSB engine
- Apply the patch (if required, details are specified in the website)
- Set PATH environment variable to point to the XSB executable in
XSB\config\...... (the path should be to the folder containing xsb executable)
and NOT
XSB\bin
- Test it by executing the xsb engine
NB: THE interProlog.jar FILE IS PART OF THE 3rdParty folder in the Sweet package. So you don't need to set classpath to it explicitly
- If necessary apply the patch on XSB (required for linux/unix) and recompile XSB
Install CommonRules 3.3 (CR3.3)
(Refer to the section below on how to set the classpath for CR3.3)
Configure/Install other 3rd party components
- The other components required are:
i. log4j
ii. junit
iii. Jess
iv. Jena
v. jwsdp (for jaxb)
vi. xalan
vii. KAON\DLP owl api --> The owl api jar files are in the 3rdParty folder
Use the jar files in the 3rdParty folder
The 3rdParty folder is in:
SweetRules\SweetRules\3rdParty folder
Set classpath to all jar files in the 3rd party folder
OR
Explicitly install 3rdParty software
Refer the section on "Installing 3rd party software explicitly" below
Configure SWEET ini files
The folder
SweetRules\SweetRules\lib has 2 ini files:
i. SweetConfig.ini
Some of the important variables that must be set properly in this file are:
XSBDirPath
COMMON_RULES33_CLASSPATH
XSLT_CLASSPATH
SCRIPT_ROOT_DIR
BUT MAKE SURE to set the other variables also if required.
ii. SweetLogger.ini
The SweetLogger.ini need not be configured unless you want to change the output format of log4j
Set the class path to all the jar files in the folder
SweetRules\SweetRules\lib
Third party software that need to be installed
IBM common rules 3.3 (http://www.alphaworks.ibm.com/tech/commonrules)
- Unpack the files into say C:\tools\CommonRules33
!!! IMPORTANT !!!
Configuring CLASSPATH for CR3.3
. DO NOT SET THE CLASSPATH to include CommonRules, it should be
set in the SweetRules\lib\SweetConfig.ini file
. Open SweetConfig.ini file and set COMMON_RULES33_CLASSPATH
to point to CommonRules3.3's root folder
(There is no jar file for CR3.33, so set it to the root folder)
Apache log4j
- Unpack the files into say
C:\tools\jakarta-log4j-1.2.8\dist\lib\log4j-1.2.8.jar
- Set the classpath to
C:\tools\jakarta-log4j-1.2.8\dist\lib\log4j-1.2.8.jar
Install junit
- If you unpack it to C:\tools\junit3.8.1, then set classpath to
C:\tools\junit3.8.1\junit.jar
Install interProlog
- Follow the instructions specified in
http://www.declarativa.com/InterProlog/INSTALL.htm
(Prefarably install it in C:\XSB)
NB: YOU NEED TO INSTALL BOTH XSB AND THE BRIDGE
Install xalan
- If you install it in C:\tools\xalan, then set it to all jar files in the C:\tools\xalan\bin directory
Install KAON-DLP 3rdParty software
- The KAON-DLP code is dependent on the jars present in it's 3rdParty folder. These are redistributed in our 3rdParty folder
Install Jess (version 6.1)
(Point class path to the Jess installation folder)
Install Jena and set the classpath to all of it's jar files
Install Jwsdp-1.4 and set classpath to all the jars in
<JWSDP INSTALLATION FOLDER>\jaxb\lib\
a) Run the command
java -DSWEET_LIBROOT=<POINT TO THE LIB FOLDER CONTAINING THE INI FILES> org.semwebcentral.sweetrules.infrastructure.SweetDriver session
in the command shell
b) This should start a session
c) Type "help" and you will be shown a very primitive help message
d) Continue with either load, translate, query etc
c) You can choose not to specify the session parameter in which case the command is executed and the application exits (This also has a side effect on state preserving commands like load which are meaningless in this mode).
SweetRules API can be used to perform translation, inferencing effecting and sensing. This section describes importing the source into eclipse and the API overview.
Import SweetRules in eclipse
SweetRules can be easily imported into eclipse. The details of this are given in the file ImportInEclipse.txt.
Assume that the Sweet package is unzipped into C:\SweetRules
1) Change to C:\SweetRules\SweetRules subfolder
2) Take a back up of the .classpath file under src folder and start eclipse
3) In prompt for the path type in
C:\SweetRules\SweetRules
4) Now select the menu "New->Project"
5) In the next dialog box select "Java Project"
6) In the "New Java Project" dialog box
Type the project name as "src"
7) Click next
8) It should show a tabbed view, select "Source" tab
9) You should see:
src/main
src/tests
10) Click on the Libraries tab and add all the dependent libraries
11) Note that since CommonRules33 does not have a jar file, you need to select
"Add class folder" button and then choose "create new folder"
then type in any name like "CR33" then click "advanced" and then select
link to folder in the system checkbox and select the common rules folder
12) Click finish
API overview
Note: Before using the API make sure that the initialize method of SweetDriver class is invoked.
A good way to get familiar with SweetRules API is to observe their usage in the top level SweetDriver and the SweetCommandHandler classes. The SweetDriver has the "main" method for SweetRules and provides an idea of the sequencing of the APIs. After performing the mandatory initializations (via the initialize method) the main method invokes the SweetCommandHandler to handle commands. The SweetCommandHandler contains the implementation of various commands and is a good demonstration of the API usage. The API details are also in the javadoc documentation
Implementing a translator
1) Implement the ISweetKRDescriptor and ISweetKBDescriptor for the source and target KRs and KBs
2) Implement ISweetTranslatorDescriptor describing the translator
3) Finally implement the ISweetTranslator descriptor (for any simple translator)
NB: A simple translator can be thought of as a single translator which performs translation from the source to target format
A composite translator uses multiple translators with intermediate outputs
4) Add it to the translatorRepository via
loadKnownTranslators(ISweetComponentRepositoryManager) method in SweetDriver class
Implementing an inference engine
1) First implement ISweetIEDescriptor interface describing the inference engine
2) ISweetInferenceEngine has a method called runTask which executes an inference engine
task
3) An inference task is an instance of ISweetInferenceEngineTask which follows the command
design pattern, so implement this for all the tasks supported by the infernce engine
(Make sure they are part of the supportedTasks in the descriptor)
4) Add the inference engine to the repository via
loadKnownInferenceEngines(ISweetComponentRepositoryManager) method in SweetDriver class
SweetRules provides helper scripts to convert between CommonRules 2.1 to CommonRules 3.3 for details refer to the Readme in the folder C:\SweetRules\SweetRules\scripts
1) We do not handle the case where rdf:RDF is not the outermost enclosing tag in an input rdf/OWL file
2) We don't support translation of builtins specially for CommonRules 3.3 to Jess
3) We don't support typing in the predicates. But if you just have a number in ruleml
for e.g. < ind >4</ ind > if translated to BRML this gets translated to an IntegerTerm
which is not supported in roundtripping, so don't have such terms
4) Also don't have inds beginning with a capital letter for e.g. < ind >Constant</ ind >
will cause problems while translating to XSB
5) Sensing support in Jess is for non-builtins, the builtins are not handled