OWLIM-SE Installation

Skip to end of metadata
Go to start of metadata
Search
This documentation is NOT for the latest version of GraphDB.

Latest version - GraphDB 7.1

OWLIM Documentation

Next versions

OWLIM 4.1
OWLIM 4.2
OWLIM 4.3
OWLIM 4.4
OWLIM 5.0
OWLIM 5.1
OWLIM 5.2
OWLIM 5.3
OWLIM 5.4

GraphDB 6.0 & 6.1
GraphDB 6.2
GraphDB 6.3
GraphDB 6.4
GraphDB 6.5
GraphDB 6.6
GraphDB 7.0
GraphDB 7.1

This section is for users and system administrators that are unfamiliar with the OWLIM-SE semantic repository software. The information contained in the following pages should be enough to get started with OWLIM-SE, i.e. to install and configure the software so that repository instances can be created and used.

Usage scenarios

OWLIM-SE is packaged as a Storage and Inference Layer (SAIL) for the Sesame RDF framework. OWLIM-SE can be used in two different ways:

  • Library: One approach is to integrate OWLIM in an application using it as a library. An example of doing this is given in the 'getting-started' folder of the OWLIM-SE distribution zip file. Users intending to use OWLIM-SE in this way do not need to install the Sesame Web applications (Server and Workbench) and need only set a few environment variables as detailed in the configuration section of the OWLIM-SE user guide.
  • Server: Those users wishing to use OWLIM-SE via the Sesame Server, with or without the Sesame Workbench, should proceed with one of the two approaches detailed in this section. This will cover installing Sesame and integrating OWLIM-SE in to the Sesame framework, so that OWLIM-SE can be used as a plug-in repository type. This approach involves deploying Sesame/OWLIM-SE via a servlet server, such as Tomcat. The Sesame installation comes with a useful 'workbench' Web application that can be used for many administration tasks.

The rest of this section gives detailed step by step instructions for installing and configuring Sesame and OWLIM-SE, leading up to the creation of an OWLIM-SE repository using the Sesame console (a command line script). For more information please check the "doc" folder of the OWLIM-SE distribution zip file.

Upgrading

In most cases, upgrading OWLIM-SE can be achieved simply by replacing the OWLIM and bundled 3rd party jar files. The required version of the Sesame framework for recent OWLIM versions is given in the following table:

OWLIM version Required Sesame version
OWLIM-SE 4.0 Sesame 2.4
BigOWLIM 3.5 Sesame 2.3
BigOWLIM 3.4 Sesame 2.3
BigOWLIM 3.3 Sesame 2.3
BigOWLIM 3.2 Sesame 2.3
BigOWLIM 3.1 Sesame 2.2

Typically, the binary format of the storage files for different versions of BigOWLIM/OWLIM-SE are not compatible. However, storage files created with version 3.1 and upwards will be automatically upgraded when using a later version of OWLIM. However, this is a one-way process and no downgrade facility is provided.

When upgrading to a later version of OWLIM it is vitally important to make a back-up of your storage files before running the new software, because it will be impossible to revert to a previous version of OWLIM otherwise.

Easy install

OWLIM will normally be built against the latest version of the Aduna OpenRDF Sesame framework. If using OWLIM with this version then the easiest way to deploy an OWLIM server instance is to copy the re-packaged Sesame Web applications (.war files) in to the Tomcat webapps directory. These can be found in the sesame_owlim directory in the OWLIM distribution ZIP file. These Web applications have been modified as follows:

  • openrdf-sesame.war: The Sesame server application. All OWLIM-SE and 3rd party jar files have been added to this package, so that it can be used immediately after deployment.
  • openrdf-workbench.war: The OWLIM-SE jar, XSLT configuration code and an OWLIM-SE Turtle configuration file have been added, so that new OWLIM-SE instances can be created using the Workbench without the need to run the command line console application.

After deployment, an OWLIM-SE instance can be created using the workbench application as follows:

  • Start a browser and go to the Workbench Web application using a URL of this form: http://localhost:8080/openrdf-workbench/ - substituting localhost and the 8080 port number as appropriate.
  • Click 'change server' if necessary to select a Sesame server instance if it is running on a different machine. The server URL will be of this form: http://localhost:8080/openrdf-sesame
  • After selecting a server, click 'New repository'
  • Select 'OWLIM-SE' from the drop-down and enter the repository ID and description. Then click 'next'.
  • Fill in the fields as required (referring to the owlim-configurator spreadsheet as necessary) and click 'create' - if you have an OWLIM-SE license file, its location should be specified in the license field.
  • A message should be displayed that gives details of the new repository and this should also appear in the repository list (click 'repositories' to see this).

Longer install

This longer install process should be used when a different or modified version of Sesame is being used. In this case, all the OWLIM-SE files need to be installed alongside Sesame in a step-by-step process as follows.

Preparation

A suitable application server must be installed. The examples in this guide assume Apache Tomcat version 6.x is used. Importantly, the user must have sufficient privileges to write to the Tomcat webapps directory and to stop and start the Tomcat daemon.
An OWLIM-SE distribution is required. This is published as a zip file and includes the Lucene (core) full-text search utility jar file. The examples in this guide use version 4.0.
If desired, the core version of Lucene can be replaced with the full Lucene jar that is available for download from the Lucene website.
The Aduna OpenRDF Sesame framework version 2.4 is required for the longer installation. The examples in this guide use version 2.4.0.

Another application server can be used instead of Tomcat. However, the rest of this guide will describe the installation of OWLIM-SE with this software.

No part of this guide is intended to supersede the documentation published with these 3rd party software components and the reader is strongly advised to familiarise himself/herself with these.

Installation

Assuming that an instance of Tomcat is available, the installation proceeds as follows:

  • Install and deploy Sesame
  • Install OWLIM-SE and deploy OWLIM-SE and other 3rd party jar files (including Lucene-core)
  • Add the OWLIM-SE repository template file to the Sesame console configuration
  • Use the Sesame console to create a new repository.
  • Set up a license file if you have one.

Step by step (vanilla)

  • Locate the Tomcat webapps directory, hereafter called [WEBAPPS].
  • Unzip the Sesame 2 distribution zip file. The Sesame 'root' directory will be called [SESAME].
  • Unzip the OWLIM-SE distribution. The top level unzipped directory will be called [OWLIMSE].
  • Deploy the Sesame Web applications by copying the war files in [SESAME]/war to [WEBAPPS].
Alternatively, use the Tomcat manager interface at http://localhost:8080/manager/html to deploy the Web applications. If this approach is used then ensure that a manager user account exists. The following lines should be added to: [tomcat-directory]/conf/tomcat-users.xml substituting your own password:
  • Copy the SLJ4J logger libraries from the Sesame Server to the Sesame Workbench application, i.e. from [WEBAPPS]/openrdf-sesame/WEB-INF/lib/logback-* to [WEBAPPS]/openrdf-workbench/WEB-INF/lib
  • Restart Tomcat
  • Run the Sesame console once to create its configuration directory by executing [SESAME]/bin/console.sh (.bat) and then type quit . at the command prompt.
  • Locate the data directory here:
    $HOME/.aduna/openrdf-sesame-console* (linux/unix)
    "%APPDATA%\Aduna\OpenRDF Sesame console" (Windows)
    
  • Create the templates folder here and copy the OWLIM-SE repository template to it. This file is found here: [OWLIMSE]/templates/owlim-se.ttl
  • Copy the OWLIM-SE jar file to the Sesame console and Sesame server, i.e. from [OWLIMSE]/lib to [SESAME]/lib and [WEBAPPS]/openrdf-sesame/WEB-INF/lib
  • Copy the Lucene and other 3rd party jars to the Sesame server, i.e, from [OWLIMSE]/ext to [WEBAPPS]/openrdf-sesame/WEB-INF/lib
  • Restart Tomcat
  • Run the Sesame console [SESAME]/bin/console.sh (.bat)
  • Connect to the local Sesame server with: connect http://localhost:8080/openrdf-sesame .
  • Create a new repository: create owlim-se.
  • Accept all the default values and then exit the console: quit.

The status of the new repository can be checked using the Sesame workbench. Type the following URL in to a browser:

http://localhost:8080/openrdf-workbench

Step by step (Fedora linux)

  • Login as root and ensure that tomcat is running:
    service tomcat6 status
  • Unzip the Sesame 2 installation:
    unzip openrdf-sesame-2.*-sdk.zip
  • Deploy the Sesame Web applications (Sesame server and workbench):
    cp openrdf-sesame-2.*/war/*.war /var/lib/tomcat6/webapps/
  • Copy the logback logging libraries:
    cp /var/lib/tomcat6/webapps/openrdf-sesame/WEB-INF/lib/logback-* /var/lib/tomcat6/webapps/openrdf-workbench/WEB-INF/lib/
  • Restart Tomcat:
    service tomcat6 restart
  • Run the Sesame console once to create the data/configuration directory:
    openrdf-sesame-2.*/bin/console.sh
  • And exit:
    quit .
  • Create the Sesame console's templates directory:
    mkdir $HOME/.aduna/openrdf-sesame-console/templates
  • Unzip the OWLIM-SE distribution:
    unzip owlim-se-4.*.zip
  • Copy the OWLIM-SE repository template file to the Sesame console templates directory:
    cp owlim-se-4*/templates/owlim-se.ttl $HOME/.aduna/openrdf-sesame-console/templates/
  • Copy the OWLIM-SE jar file to the Sesame console lib directory:
    cp owlim-se-4*/lib/owlim-se*.jar openrdf-sesame-2.*/lib/
  • Copy the OWLIM-SE jar file to the Sesame server lib directory:
    cp owlim-se-4*/lib/owlim-se*.jar /var/lib/tomcat6/webapps/openrdf-sesame/WEB-INF/lib/
  • Copy the Lucene jar file the other 3rd party jar files to the Sesame server Web application:
    cp owlim-se-4*/ext/lucene*.jar /var/lib/tomcat6/webapps/openrdf-sesame/WEB-INF/lib/
    cp owlim-se-4*/ext/jsi*.jar /var/lib/tomcat6/webapps/openrdf-sesame/WEB-INF/lib/
    cp owlim-se-4*/ext/onto-crypto*.jar /var/lib/tomcat6/webapps/openrdf-sesame/WEB-INF/lib/
    cp owlim-se-4*/ext/sil*.jar /var/lib/tomcat6/webapps/openrdf-sesame/WEB-INF/lib/
    cp owlim-se-4*/ext/trove4j*.jar /var/lib/tomcat6/webapps/openrdf-sesame/WEB-INF/lib/
    
  • Restart Tomcat:
    service tomcat6 restart
  • Run the Sesame console to create a new repository:
    openrdf-sesame-2.*/bin/console.sh
  • Connect to the Sesame server:
    connect http://localhost:8080/openrdf-sesame .
  • Create a new repository:
    create owlim-se .
  • At this point values for a number of parameters are asked for, but all the defaults can be accepted by pressing <return> for each question. When finished, the message 'Repository created' should be displayed.
  • Exit the console:
    quit.
  • The status of the new repository can be checked using the Sesame workbench. Type the following URL in to a browser:
    http://localhost:8080/openrdf-workbench
  • Alternatively, execute a test query against the Sesame Server's SPARQL endpoint:
    curl 'http://localhost:8080/openrdf-sesame/repositories/owlim-se-test?
    infer=false&queryLn=sparql&query=SELECT+*+WHERE+%7B?s+?p+?o%7D+LIMIT+100'
    

Step by step (Windows)

  • Unzip the Sesame 2 installation (note that this might require WinZIP, WinRAR or some other utility):
    unzip openrdf-sesame-2.4.0-sdk.zip
  • Deploy the Sesame Web applications (Sesame server and workbench):
    copy openrdf-sesame-2.4.0\war\*.war "C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps"
  • Restart Tomcat using the Tomcat monitor icon in the system tray or from the Start menu
  • Run the Sesame console once to create the data/configuration directory:
    openrdf-sesame-2.4.0\bin\console.bat
  • Then exit immediately:
    quit .
  • Create the Sesame console's templates directory:
    mkdir "%APPDATA%\Aduna\OpenRDF Sesame console\templates"
  • Unzip the OWLIM-SE distribution:
    unzip owlim-se-4*.zip
  • Copy the OWLIM-SE repository template file to the Sesame console templates directory:
    copy owlim-se-4.0.3536\templates\owlim-se.ttl "%APPDATA%\Aduna\OpenRDF Sesame console\templates"
  • Copy the OWLIM-SE jar file to the Sesame console and Sesame server lib directories:
    copy owlim-se-4.0.3536\lib\owlim-se-4*.jar openrdf-sesame-2.4.0\lib
    copy owlim-se-4.0.3536\lib\owlim-se-4*.jar "C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\openrdf-sesame\WEB-INF\lib"
    
  • Copy the Lucene and other 3rd party jar files to the Sesame server Web application:
    copy owlim-lite-4.0.3536\ext\lucene*.jar "C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\openrdf-sesame\WEB-INF\lib"
    copy owlim-lite-4.0.3536\ext\jsi*.jar "C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\openrdf-sesame\WEB-INF\lib"
    copy owlim-lite-4.0.3536\ext\onto-crypto*.jar "C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\openrdf-sesame\WEB-INF\lib"
    copy owlim-lite-4.0.3536\ext\sil*.jar "C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\openrdf-sesame\WEB-INF\lib"
    copy owlim-lite-4.0.3536\ext\trove*.jar "C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\openrdf-sesame\WEB-INF\lib"
    
  • Restart Tomcat using the Tomcat monitor icon in the system tray or from the Start menu
  • Run the Sesame console to create a new repository:
    openrdf-sesame-2.4.0\bin\console.bat
  • Connect to the Sesame server:
    connect http://localhost:8080/openrdf-sesame.
  • Create a new repository:
    create owlim-se.
  • At this point values for a number of parameters are asked for, but all the defaults can be accepted pressing <return> for each question. When finished, the message 'Repository created' should be displayed, so exit the console:
    quit.
  • The status of the new repository can be checked using the Sesame workbench. Type the following URL in to a browser:
    http://localhost:8080/openrdf-workbench/

Useful information

Tomcat

When running on Fedora linux, Tomcat uses the following directories:

Contents Directory
Log files /var/log/tomcat6/
Web applications /var/lib/tomcat6/webapps
Sesame configuration and repository data files /usr/share/tomcat6/.aduna

On a machine running Windows, Tomcat uses the following directories:

Contents Directory
Log files C:\Program Files\Apache Software Foundation\Tomcat 6.0\logs
Web applications C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps
Sesame configuration and repository data files C:\Users\<username>\AppData\Roaming\Aduna

Sesame

The Sesame framework is published as a zip file that is installed simply by unzipping it in to the target directory. This directory is called [SESAME_INSTALL] in this guide.
When running, Sesame stores configuration and repository data in the following directory:

$HOME/.aduna/ On linux/unix operating systems.
%APPDATA%\Aduna On Windows machines. Note that if Sesame is running as a service then the full path will be:
C:\Documents and Settings\LocalService\Application Data\Aduna

This directory is called [ADUNA_DATA] elsewhere in this guide. It can be overridden by setting a Java system property. When using Tomcat, this can be achieved by setting the JAVA_OPTS environment variable, for example (linux and Windows respectively):

export JAVA_OPTS='-Dinfo.aduna.platform.appdata.basedir=/other/dir/'
set JAVA_OPTS=-Dinfo.aduna.platform.appdata.basedir=\other\dir\

Note that setting this environment variable must be done by the same user that runs the Tomcat server. This may not be the case when using 'sudo' to set up/start Tomcat, for instance when using port numbers below 1024 when it is necessary to run Tomcat with root privileges.
The Sesame 2 framework uses a special SYSTEM repository to store its configuration data. Do not store anything else in this repository.
The workbench Web application can be used for many administrative tasks, but it is still experimental. The easiest method to create new repositories is to use the Sesame Console script, which can be found in the bin directory: [SESAME_INSTALL]/bin/console.bat (.sh for linux/unix)

All commands entered using the console must end in a dot '.', e.g. 'help.'

Logging

The Sesame server and workbench use logback for logging. The Sesame server logs to:

[ADUNA_DATA]/openrdf-sesame/logs/main.log

And the Workbench logs to:

[ADUNA_DATA]/openrdf-workbench/logs/main.log

The default log level is INFO, but this can be adjusted after the first run by editing:

[ADUNA_DATA]/openrdf-sesame/conf/logback.xml

There is a note in the Sesame documentation that the simple logging framework for java (slf4j) is used, which implies that a bridge jar for the logging framework OWLIM uses is also required, e.g. SLF4J-to-log4j.jar

Common Problems

Can not copy OWLIM-SE jar file to the Sesame WEB-INF/lib directory.

This directory will not exist until the Sesame war files have been deployed to the [WEBAPPS] directory AND Tomcat is running. If the war files have been deployed, but the directory does not exist, try restarting Tomcat.

Can not connect the Sesame console to the local Sesame server at http://localhost:8080/openrdf-sesame

Make sure that the Sesame war files have been deployed and that Tomcat is running. Restart Tomcat if necessary.

Can not create a OWLIM-SE repository using the Sesame console

Make sure that the repository template file [OWLIMSE]/templates/owlim-se.ttl has been copied to the 'templates' subdirectory of the Sesame console's data directory.

Can not create an OWLIM-SE repository, the Sesame console says unknown Sail type – owlim:Sail

The Sesame console can not find the OWLIM-SE jar file. Make sure it was copied from [OWLIMSE]/lib to the Sesame installation folder here: [SESAME]/lib

A long error message/Java exception is given when trying to query a new repository instance.

The Lucene jar file must be copied from the OWLIM-SE distribution to the Sesame server's WEB-INF/lib directory. Restart Tomcat if necessary.

Cannot use my custom rule file (pie file), an exception occurred

The tools.jar file from the Java Development Kit (JDK) must be on the classpath or alternatively copied to Sesame server's WEB-INF/lib directory.

Sesame Workbench starts, but gives memory error on the 'explore' and 'query' menus.

The maximum heap space must be increased, i.e. Tomcat's Java virtual machine must be allowed to allocate more memory. This can be done by setting the environment variable 'CATALINA_OPTS' to include the desired value, e.g. -Xmx1024m

Installing OWLIM-SE with Jena

This section is for users and system administrators that are unfamiliar with the OWLIM-SE Jena adapter. The information contained in the following pages should be enough to get started with this software, i.e. to install and configure an OWLIM-SE repository and access it via the Jena API or Jena compatible tools.

The Jena adapter allows OWLIM-SE to be used with local repositories, NOT those shared via the Sesame HTTP server. If you want to use OWLIM-SE remotely, consider using the Joseki server as described below.

Required software

This guide covers installing and configuring the Jena adapter for OWLIM-SE. Required software for this comprises:

  • Jena version 2.6 (tested with version 2.6.3)
  • ARQ (tested with version 2.8.6)
  • OWLIM-SE v3.5

No part of this guide is intended to supersede the documentation published with these software components and the reader is strongly advised to familiarise himself/herself with these.

Description of the OWLIM-SE Jena adapter

The OWLIM-SE Jena adapter is essentially an implementation of the Jena DatasetGraph interface that provides access to individual triples managed by an OWLIM-SE repository through the Sesame API interfaces.
It is not a general purpose Sesame adapter and cannot be used to access any Sesame compatible repository, because it utilises an internal OWLIM-SE API to provide more efficient methods for processing RDF data and evaluating queries.
The adapter comes with its own implementation of a Jena 'assembler' factory to make it easier to instantiate and use with those related parts of the Jena framework, although one can instantiate an adapter directly by providing an instance of a Sesame SailRepository (an OWLIM-SE OWLIMRepository implementation). Query evaluation is controlled by the ARQ engine, but specific parts of a Query (mostly batches of statement patterns) are evaluated natively through a modified StageGenerator plugged into the Jena runtime framework for efficiency. This also avoids unnecessary cross-api data transformations during query evaluation.

Instantiate Jena adapter using a SailRepository

In this approach, an OWLIM-SE repository is first created and wrapped in a Sesame SailRespository. Then a connection to it is used to instantiate the adapter class SesameDataset. The following example helps to clarify:

From now on the SesameDataset object can be used through the Jena API as regular Dataset, e.g. to add some data into it one could something like the following:
and can also be used to evaluate queries through the ARQ engine:

Instantiate OWLIM-SE adapter using the provided Assembler

Another approach is to use the Jena assemblers infrastructure to instantiate an OWLIM-SE Jena adapter. For this purpose the required configuration must be stored in some valid RDF serialization format and its contents read into a Jena model. Then the assembler can be invoked to get an instance of the Jena adapter. The following example specifies an adapter instance in N3 format.

@prefix rdf:    <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs:   <http://www.w3.org/2000/01/rdf-schema#> .
@prefix ja:     <http://jena.hpl.hp.com/2005/11/Assembler#> .
@prefix otjena: <http://www.ontotext.com/jena/> .

@prefix :       <#> .

[] ja:loadClass "com.ontotext.jena.SesameVocab" .
otjena:SesameDataset rdfs:subClassOf ja:Object .
otjena:SesameDataset ja:assembler "com.ontotext.jena.SesameAssembler" .
<#dataset>  rdf:type otjena:SesameDataset ;
            otjena:datasetParam "./location" .

The ja:loadClass* statements ensure that the OWLIM-SE Jena adapter factory class file(s) are initialized and plugged into the Jena framework prior to be being invoked. Then #dataset description tells the Jena framework to expect instances of otjena:SesameDataset to be created by this factory. The following example uses such a description stored in the file owlimbridge.n3 to get an instance of the Jena adapter:

After this, the adapter is ready to be used, for example to evaluate some query through the ARQ engine using the same approach described a few paragraphs above.

Using OWLIM-SE with the Joseki server

In order to use a OWLIM-SE repository with the Joseki server one needs only to configure it as a dataset so that the Jena assembler framework is able to instantiate it. An example Joseki configuration file that makes use of such a dataset description could looks like the following. First we describe a service that hosts the dataset:

<#service1>
    rdf:type            joseki:Service ;
    rdfs:label          "service point" ;
    joseki:dataset      otjena:bridge ;
    joseki:serviceRef   "sparql" ;
    joseki:processor    joseki:ProcessorSPARQL ;
    .

Then we describe that dataset:

[] ja:loadClass "com.ontotext.jena.SesameVocab" .
otjena:DatasetSesame  rdfs:subClassOf  ja:RDFDataset .
otjena:bridge  rdf:type otjena:DatasetSesame ;
    rdfs:label "OWLIM-SE repository" ;
    otjena:datasetParam "./location" .
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.