How to build Semantic Turkey

Note: These instructions are valid from version 0.9.x on; 0.9.x source is currently available in the Semantic Turkey GIT repository. Build Instructions for previous versions of Semantic Turkey can be found for version 0.6 and 07 up to 0.8.0

This page provides information for building Semantic Turkey. The lenght of these instructions may make people think it is a long and difficult process to build this tool.

Actually it is not.

We only prefer to give as much information as possible to cover potential issues that may arise in the process, or doubts held by developers who are not expert with the required technologies or development environments.

We assume that the reader is at least proficient with Maven and we will thus not explain in details all the required steps to activate Maven tasks (e.g. we simply tell "install it through Maven" assuming the reader understands what we mean with that sentence). Same considerations holds for ANT.

Also, when we provide more detailed information (such as how to install some packages), we assume the reader is using Maven through command line (or that he is able to find the related options in any Maven graphic client), though we provide in the last section some useful tricks for people willing to use Eclipse plugin for Maven.

Projects Structure

To build Semantic Turkey, you need to download the main project from the SVN repository on Semantic Turkey project site. The root of the source is a Maven project (actually, the parent project of Semantic Turkey). Beside the files contained in it, the project contains seven folders:

Of the above, system-resources is just a folder containing resources which will be used during the build to create the distribution, while the other ones are modules which separate different contexts of the project. The root of the source, containing a dedicated pom.xml, represents the parent project from which all modules inherit some shared features.

Here follows a brief description of the six modules:

Maven Third Party Libraries Installation

Some libraries needed by this application are not hosted on main Maven repository (Maven Central), nor we provide a Maven repository which hosts them.
So, before you build this project, we suggest downloading the following jars from the web:

and install them on your local maven repository, through the following maven commands

mvn install:install-file -Dfile=secondstring-20060615.jar -DgroupId=com.wcohen.ss -DartifactId=secondstring -Dversion=2006.06.15 -Dpackaging=jar

ART Libraries Installation

The API for RDF management used by Semantic Turkey are also developed by our Applied Research lab. When they reach a stable version, we submit them to Maven Central, though non-stable versions of Semantic Turkey may also depend on non-stable versions of these API.

The site of OWL ART API is: http://art.uniroma2.it/owlart/

and their google code project (with SVN repository) site is: http://code.google.com/p/owlart/

So, depending on the version of Semantic Turkey which you have downloaded, you may encounter three scenarios:

  1. the dependency is on a STABLE version of these API, which has already been submitted to Maven Central, accepted and then published. No action is required from you, since the jar of the library will be automatically downloaded from Maven Central and linked by your Maven Installation
  2. the dependency is on a STABLE version of these API, though this version is not yet available from Maven Central. In this case, you may either:
    1. download the packed jar of the library from its site and then install it the same way as explained on previous sections for third party libraries (use updated library info got from its description in the POM.XML of Semantic Turkey), OR
    2. download the source, compile and install it in Maven (see next scenario). Note that we svn-tag stable versions of the library on SVN repository, so you may download the proper tagged versions from the repo.
  3. (unusual but possible) the dependency may be on a SNAPSHOT version of these API. Download them from the main trunk of the SVN repository of their google project site and install them via Maven.

Build the whole SemanticTurkey And Deploy it

Once all required libraries have been installed through Maven, Semantic Turkey is ready for being built!

A simple Maven "clean install" is enough to run the build of all the modules. Modules' builds are resolved following their order of presentation, also considering any constraint determined by dependencies among them. The distribution is built progressively by contributions put by each module inside the target/dist folder of the parent project. The last module for which the build is exectued is: st-firefox-ext. This module does not require any compilation (as it contains mostly xul and xbl pages and js code) though it manages copying all the required resources inside the distribution folder and packaging the distribution into the final xpi.

The XPI (cross platform installer) will be deployed inside the root of the parent project folder. The XPI is a totally autonomous application which can be installed inside Firefox. It includes both the client (Firefox extension) and service and data layers (which will be activated inside Firefox through a mozilla-java bridge) while the target direcotry of the project will contain the open distribution (contained inside the dist folder), which can be used to run an independent server of Semantic Turkey (which can, for instance, be queried by other dedicated clients).

Installing the XPI inside Firefox

Just drag and drop the XPI over your copy of Firefox and the job is done! (just check compatibility between the built Semantic Turkey and your version of Firefox).

Running the server as a standalone application

The independent server of Semantic Turkey, is located in the target/dist folder of the parent project, after a build has been run

To run the server, just run the ANT file server_run.xml. This can be done via command line this way:

ant -buildfile server_run.xml

  

Addenda for Developers

Maven Eclipse plugin

A nice plugin for ecplise: m2eclipse, provides seamless integration of Maven functionalities for project development inside Eclipse.

While we point the reader to the home site of the plugin for any reference on how to install and use it, we leave here just a couple of hints we found useful for newbyes using this plugin (and in the particolar context of Semantic Turkey).

Project Names

By default, when a Maven project is imported into Eclipse through the Import option (File-->Import) of Eclipse, selected on "Maven Projects" (see figure below)

Maven Import

the folder of the project just created in Eclipse Workspace takes the name of the artifact id of the imported project, no matter the name of the source folder from which it has been imported.

SNAPSHOTS and Bundles

Note: we did not encounter any more issues like the one described below, after moving the ST project after multi-module management. However, these info may come of help for people writing ST extensions, modifying the source code, or in general working with Maven under Eclipse.

M2Eclipse provides a way for disburdening developers from installing each time dependencies which are already open as source projects in Eclipse. So, when a dependency is set to an artifact which is in SNAPSHOT (whether it is installed or not, cause SNAPSHOTS are always recompiled from the live source), or, in any case, from a project version which is not installed in Maven but is available as source code, then the dependency is resolved in Eclipse as a project dependency instead of a library dependency (see figure below on owl-art dependency, where the synmbol of the source is represented instead of the one associated to installed jars).

Project Dependency in Maven

While this can be a useful feature on almost all typical cases, this causes some problems when building bundles (such as in the case of OSGi bundles for Semantic Turkey, providing new Ontology Management implementations or new services). In fact, when the bundling instructions in the POM.XML file of a bundle project instruct Maven to embed dependencies inside the bundle (that means embedding jars), the source code of the whole dependent project is embedded. Also, this bad import is made starting from the target directory of the project (the base of the produced binary in the project), while the Class-Path of the bundle is not informed of this particular structure. The result is a series of errors while packaging the bundle, like the following one:

[ERROR] Error building bundle it.uniroma2.art.semanticturkey.ontology:sesame2ontmanager:bundle:1.0.2 : Class in different directory than declared. Path from class name is it/uniroma2/art/owlart/sesame2impl/MultiIndexedMap.class but the path in the jar is lib/classes/it/uniroma2/art/owlart/sesame2impl/MultiIndexedMap.class from Jar:dot

The remedy to prevent this is simple:

Ontology Manager Implementation

OWL ART API provide a middle layer for RDF Graphs querying and management, which needs to be implemented with a concrete triple-store technology for low-level data access.

The main data management component in Semantic Turkey, called Ontology Manager, is characterized by an OSGi extension point requiring at least one triple-store technology to be plugged to the system. The Semantic Turkey project comes with a OntManager implementation for Sesame2 and Allegrograph (experimental). When a build is run over Semantic Turkey, this implementation is packaged as an OSGi bundle and deployed (under the Semantic Turkey distribution) under the:

/extensions/ontmanager

directory.

For people willing to develop Ontology Manager implementations based on different technologies: we will implement in the near future a maven archetype for developing ontmanager extensions. In the meanwhile, you may consider the st-sesame2-ontmanager module as an example of a maven project for building new ontmanager implementations. New implementations may be written to cover different technologies, but also to enable different project types, possibly based on further sesame2 configurations.

The Graph-Applet module

The graph-applet module of Semantic Turkey contains code related to the visualization of ontology data as a graph through an applet inside the Firefox browser (actually, it could work inside any browser, here we are only referring to the standard distribution of Semantic Turkey which offers a Firefox extension as the client of the application).

However, this module contains two different portions of code: a general interface for graph visualization, with a java implementation of client requests to the server and interfaces for modifying the graph structure on the applet, and the implementation for the Jung graph library. New implementations can be easily added by taking the single javaclass implementing the graph-applet interface over Jung as an example.