SweetRules V2.1 README

SweetRules Documentation

(for release version 2.1)

•  Introduction

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).

•  Getting started with SweetRules

•  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

•  Detailed Installation instructions

•  Overview of Sweet Installation

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

•  Detailed Steps for installing SWEET

•  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

•  Installing 3rd party software explicitly

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\

•  Running SweetRules

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 overview

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

•  Extending SweetRules with plug-ins (translators or inference engines)

•  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 helper scripts

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

•  Release notes, known issues and suggested workarounds

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