How to build Semantic Turkey

Note: These instructions are valid from version 0.10.x on. Build Instructions for previous versions of Semantic Turkey can be found for version 0.6, 07 up to 0.8.0 and for 0.9.x

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.

Basically, if you know what the following line means, and if you are building a stable release, it suffices to do a plain:

mvn clean install

However, we 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 GIT 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 several folders, representing separate Maven modules:

ART Libraries Installation

The API for RDF management used by Semantic Turkey - OWLART - 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 project site, with GIT repository and downloads, is: https://bitbucket.org/art-uniroma2/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 tag stable versions of the library on the GIT 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 GIT repository of their project site and install them via Maven.

From version 0.10 on, Semantic Turkey also depends on CODA, a platform for knowledge acquisition. Same considerations above hold for CODA as well, so check its site for the source code in case the ST version you are using is not depending on a stable version of this framework.

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

Just use the batches (for Windows and Unix systems) in the bin directory of the server.  

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

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

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.