From SMW+ A Semantic Web Enterprise Wiki

This article guides you through the installation of the TripleStore 1.6.0 incl. Jena (without using the installer)

User manual information
Applies to version: Help:TripleStore Basic 1.6.0,
Note: Use the tree-view on the right hand side to navigate in the documentation

Contents 1 Requirements 2 How to installing the TripleStore from source 3 Wiki Configuration 3.1 Start options 4 Triple Store during boot process on linux 5 TSC Configuration 6 Migration 6.1 From TSC 1.5.2 or earlier 6.2 From TSC 1.5.3 6.3 From 1.5.6 7 Triple store as Windows Service 8 Datamodel 8.1 Prerequisites 8.2 Switching datamodel 9 Testing the Installation 10 Stopping the Connector 11 Querying the Triple store connector (Jena) 12 String Encoding 13 Additional namespaces 13.1 Debugging 13.2 Logging 14 Troubleshooting

Requirements

• Apache HTTP Server
• MySQL higher than 4.0.14 (Recommended MySQL 5.x)
• PHP 5.2.x or PHP 5.3.x
• PHP cURL extension (How to find out if cURL extension is installed)
• Java Runtime Environment 1.6 (tested with JRE 1.6.0_14)
• MediaWiki 1.17.x (see installation guide)
• Semantic MediaWiki 1.6.x (See installation guide)
• SMW+ 1.6.0 OR Halo extension 1.6.0

How to installing the TripleStore from source

1. Download and unzip the TripleStore Basic (Jena) to an arbitrary directory.
2. Download the MySQL Connector/J
3. Unzip the file mysql-connector-java-5.1.x.zip and copy the file mysql-connector-java-x.x.x-bin.jar into the lib folder of your TSC installation (Default directory: C:\TSC\lib Otherwise the TSC is not able to access the MySQL database.
4. Open a commandline interface in Admin mode and go to the directory where you have unpacked the files, e.g. cd C:\ts-connector-jena-1.6.0
5. Execute the start script:
   

   start-triplestore jena console (on Windows)
   ./start-triplestore.sh jena console (on Linux-remember to make the script executable before this)

     Note:

   If you have a Windows installation, we now offer an exe-Wrapper. It takes the same options as the batch version with one exception: If you want to specify a driver you have to write driver=jena for example. It has reasonable default, so you can run it without any extra options.

   Result: This will start a Triple store connector listening on localhost:8080. It will have started properly if you see a command prompt waiting for commands. To test, enter 'help'.

6. You can enter additional options for the Java virtual machine using the following command (only with exe-wrapper):

   -vmargs ....

   Example:

   -vmargs -Xmx1024M

7. You can run the Triple store connector as a service in Windows. To do this, execute the following command: InstallAsService.bat auto
8. Once the service is installed, you can manage it by launching Windows Control Panel > Administrative Tools > Services

   or

   by typing "Services.msc" in the Run command on Start menu.
  Note:
If you're using the Windows installer, the configuration data of TSC is stored in %APPDATA%/Ontoprise/TSC. The TSC log file is also located at this directory.

Wiki Configuration

You have to configure your wiki's LocalSettings.php installation.

1. Add the variable:

   $smwgHaloWebserviceEndpoint = "localhost:8080";

   In this step, we presume that your SPARQL-endpoint, which is always part of TripleStoreConnector runs on localhost.
2. If you have a webserver access restriction set (e.g. .htaccess), you must add a pair of valid credentials:
   

    $smwgHaloWebserviceUser = "username";
    $smwgHaloWebservicePassword = "password";

3. Add the graphs below the line with 'enableSMWHalo':

   $smwgHaloTripleStoreGraph='<your wiki graph URI>';

   The parameter is an arbitrary URI which works as an identifier for the wiki in the TSC, it is optional. If it is omitted, 'http://mywiki' is used. Any URL may be used as long as it does not contain hash characters (#).
4. Configure your wiki URL in config/tsc.properties that can be found in your user directory C:\Users\<YOURNAME>\AppData\Roaming\Ontoprise\TSC\config. This assures that the TSC can automatically import the wiki data and the additional namespaces configured by the wiki. If this option is set, the former SPARUL scripts are NOT needed anymore. Please remove the run-option including a script unless it does more than pure sync.

   TSC.WikiURL=http://localhost/mediawiki 

   If you need HTTP authentication, use TSC.WikiUser and TSC.WikiPassword.

5. Optionally: Activate Quad mode with:

   $smwgHaloQuadMode=true;

6. Optionally change the DB_PORT that is the port for the database used by Jena to store its data:
   
   1. Open %APPDATA%/Ontoprise/TSC/config/jena.properties
   2. Set DB_PORT=3306
7. (Re-)Start the triple store with the following command:
   

   start-triplestore jena console

   OR

   tsc.exe console

   (On Windows)

   ./start-triplestore.sh jena console 

   (On Linux)

   The TSC will automatically sync with the wiki.

8. Open a browser and go to your wiki installation
9. Type Special:TSA into the search field and check on this special page if your wiki is properly connected with the triplestore

Start options

Required arguments

• driver (may be 'jena', 'jena-quad', 'jena-tdb', 'ontobroker', 'ontobroker-quad' or a full classname. If missing, the TSC won't come up.

Following options can be applied when starting the TSC via 'start-triplestore'

• user: User for MessageBroker. May use default
• password: Password for MessageBroker. May use default
• host: Host of MessageBroker. Default is localhost
• clientID: Identifies the triple store. May use default if you are using only one.
• msgbroker: possible values:
  • dedicated: Use a dedicated messagbroker. In this case, 'host' must be set.
  • embedded: Use an embedded broker ('host' MUST be localhost in this case)
  • none: Does not use a messagebroker but an update webservice (less robust, synchronous). Make sure to unset $smwgMessageBroker in LocalSettings.php
• wsport=Port for webservices: SPARQL, SPARUL, Rules, Explanations, Management (default is 8080)
• wshost=<host or IP>: Host for webservices: SPARQL, Rules, Explanations, Management (default is localhost)
• reasoner: Use the given reasoner (rdfs, owl)
• stop=<client ID>: Terminates the given instance (clientID).
• console: activates command console
• remoteconsole=<host or IP>: Activates the remote console listening on the given IP. If no host or IP is given, it tries to get an IP. (see logging)

Warning: security lack, no authorization required. Use only for debugging purposes.

• run=<file>: Reads a SPARUL script file and executes the commands in it asynchronously.

Advanced options (only relevant if the client is not a wiki)

• cleansemantics: Removes wiki specific semantics on SPARUL commands and ASK/SPARQL queries
• loadcommand=<fully qual. classname>: Loads this class as user-specific load command. Class must register itself via LoadCommand.addLoadCommand(..) in a static section. Several classes may be specified comma separated.

Triple Store during boot process on linux

Put the script tsc.sh in the folder /etc/init.d, make it executable and change the TSC_DIR variable in the script to your TSC directory.

Then it is started automatically on startup and stopped on shutdown. You can also use it manually:

/etc/init.d/tsc start|stop|restart

TSC Configuration

see Changing the configuration of TripleStore Basic

Migration

From TSC 1.5.2 or earlier

Most important change is that synchronization with the wiki is done automatically if the option TSC.WikiURL is set in config/tsc.properties. That means the start script included by the run-option is not necessary anymore.

Example:

TSC.WikiURL=http://localhost/mediawiki 

This option already exists in TSC 1.52 but it was only used to get additional namespaces. So it might be that you already configured this. In this case, just remove the start script.

From TSC 1.5.3

1. Remove the 'reasoner' startup option. The 'reasoner' startup option is deprecated and should not be used anymore for the Jena driver. The default reasoner 'rule' of the Jena driver now defines automatically some default axioms for:

• • subcategory/subproperty reasoning
  • transitive/symetrical properties
  • inverse properties
  • It also allows user defined rules.

1. Re-initialize SMWHalo, therefor run the script SMWHalo/maintenance/SMW_Setup.php. There is a new table which need to be created.

From 1.5.6

1. Remove the arguments of enableSMWHalo(..) in LocalSettings.php
2. If you defined a wiki graph previously (3rd argument), then add instead

    $smwgHaloTripleStoreGraph='<your wiki graph URI>';

3. If you used the quad mode (SMWTripleStoreQuad instead of SMWTripleStore), add

   $smwgHaloQuadMode=true;

   BE CAREFUL: QuadMode is usually NOT used. Use this only if you know what you do.

Triple store as Windows Service

Installing the Triple store connector as Windows service is logical if you wish to use the TSC productively. If you are just testing, you would better start it manually because you will get debug messages on the console.

If you did not install the TSC as service during the installation, you can do this now using the TSC Administration Console:

1. Start tsc-console.exe
2. Click Install as service

Datamodel

The default settings use the Jena RAM datamodel. The RAM datamodel provides higher scalability, depending on your RAM storage. One triple needs approximately 100 byte.

Prerequisites

• A MySQL database installation
• Your database user needs to have permission to create databases manually.

Switching datamodel

1. If you want to use a MySQL backend for Jena, open config/jena.properties
2. Set DB_TYPE=MySQL
3. Change the hostname, the database and your DB credentials in this file accordingly.

Testing the Installation

This will only work if you activate the console.

You may check if your wiki got imported properly by executing these commands on the command console:

 SHOW GRAPHS					; you should see the URL you specified
 SET GRAPH [http://mywiki]                      ; or whatever URL you used
 SHOW ALL -noinf

You should see all the triples of your wiki (without the inferred ones). You may terminate now by entering 'quit' and restart without the console option.

Stopping the Connector

To terminate the connector safely, type

on Windows

 stop-triplestore.bat MyStore 

on Linux

./stop-triplestore.sh MyStore

Querying the Triple store connector (Jena)

We provide two sample projects which show how to access the TSC from 3rd-party applications.

• Java Client
• PHP Client

More information about the interfaces of the TSC

String Encoding

The wiki supports the following string encoding options:

• $smwgSPARQLResultEncoding: Wiki decoding of SPARQL-XML
• $smwgSPARULUpdateEncoding: Wiki encoding of SPARUL commands.

In most cases you get corrupt characters displayed if there are encoding problems. In some cases it may lead to empty SPARQL results or even fatal PHP errors during SPARQL queries. If you experience such problems, try to adjust these options.

It is also possible to overwrite the default charset encoding when communicating with the MySQL store. You can add options to the MySQL connection string via the LOAD command. Example:

LOAD smw://root:m8nix@localhost:3306/testdb?smwstore=SMWHaloStore2&lang=en&ignoreSchema=true&smwnsindex=100&mysql_charsetEncoding=UTF-8# INTO <http://halowiki/ob>

Any option starting with 'mysql_' is redirected. (without the prefix of course)

Additional namespaces

The TSC can read additional namespaces of other extensions other than SMW from the wiki. It is strongly recommaneded to configure TSC.WikiURL so that the TSC can import them at startup. Furthermore, this options allows an automatic sync with the wiki.

Debugging

The Triple store connector has a debugging console. It can be activated by using the 'console' option at startup.

start-triplestore jena console

You have a bunch of commands for creating graphs, inserting facts and doing queries (SPARQL+ASK). For a complete overview of the available commands, enter 'help' on the console prompt.

Logging

By default, the Triple store connector (≥ 0.31) writes a log file (tsc.log). If you experience problems, please look at this. The default log level is 'INFO' but you may change this to 'DEBUG' in the log4j.properties file.

Troubleshooting

• Database Timeout. MySQL sets the default timeout for inactive connections to eight hours. This has the effect that the TSC crashes internally if there has been no access to it for a period longer than eight hours. You may increase this value by executing the following command on the mysql console:

SET wait_timeout=<time in seconds>;

Command prompt> telnet localhost 8080
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.

Here are some errors you might encounter and their possible causes:

• Connection refused- the Triple store connector is not running.
• The Jena driver will not work in persistent mode - the database credentials are not valid or the user is not allowed to create databases or tables. Change the user or grant privileges.
• You get a blank screen when you do a SPARQL query or a PHP error - you probably have string encoding problems. Refer to 'String encloding' section.
• Fatal error: Call to undefined function curl_init() in C:\Projekt SMW+\xampp\htdocs\mediawiki\extensions\SMWHalo\includes\storage\SMW_RESTWebserviceConnector.php - You have to install the PHP cURL extension. Check your php.ini file for 'php_curl' (How to find out if cURL extension is installed)
• Error message on specialpage TSA: "[...] exception 'Exception' with message 'Could not connect to a broker' [...]" - Remove the line $smwgMessageBroker = "..."; from your LocalSettings.php. Otherwise the wiki assumes a messagebroker is installed. The TSC starts by default without a messagebroker.

• One advanced scenario that grants you more robustness is starting the messagebroker on the wiki machine and connecting via the Triple store connector from a separate triple store machine. You may use EmbeddedMessageBroker class for this or you may setup your own ApacheMQ server. A detailed description of how this may be implemented may be availed in the near future but it is not a part of this package right now.

Copyright © 2012 (see terms of use for ownership)

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the article "GNU Free Documentation License".