mulgara - semantic store

skip navigation


Installation Guide

Mulgara is shipped in two forms, Mulgara Lite is shipped as binary files only or the full version as a source code download. If you have downloaded the binary files mulgara-1.1.0.jar and itql-1.1.0.jar please proceed with Installing Java and then skip to Running a Mulgara server. If you have obtained source code, you will need to build the binary files from a build environment by completing all sections in this document. All users should take note of the hints given in the latest set of Release Notes.

Note - Throughout this document, $MULGARA_HOME is used to refer to the directory containing either the server or iTQLTM shell binary JAR file, or the directory containing the source code. Where examples refer to $MULGARA_HOME below, you should substitute in this location.


Installing Java

Download a J2SETM 1.5.x for your platform from, and install it (Java 6 support is not yet available). Installation instructions are available for 32 bit and 64 bit versions of Windows®, Linux® and Solaris®. You should then check that the installation added the java commands to your path by typing:

$ java -version

You should get something like the following:

java version "1.5.0_07"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_07-164)
Java HotSpot(TM) Client VM (build 1.5.0_07-87, mixed mode, sharing)

If your shell reports that it cannot find the command, add <JAVA_HOME>/bin (where JAVA_HOME is the location where you installed J2SE to) to your path in the appropriate way for your shell.

Note. You must use a J2SE 1.5 for compiling and running Mulgara. Less than J2SE 1.5.0, or greater than J@SE 1.6.0 will not work


Checkout Setup

After you've obtained a checkout of the Mulgara Semantic Store project, you'll need Add a JAVA_HOME environment variable pointing to the place that you have java installed to get your checkout working.

From a Windows command line:

$ set JAVA_HOME=C:\jdk1.5.0

The installation program should have set this setting automatically.

Under bash:

$ export JAVA_HOME=/usr/local/java

Note. $MULGARA_HOME refers to the place where you checked out the Mulgara module from CVS. The version of the junit JAR file listed above may be different from the version included with your checkout.

Note - Under a Windows operating system you could set these environment variables in Control Panel -> System -> Advanced -> Environment Variables instead of in each shell. On most other versions of Windows you'll probably want to add these to your autoexec.bat file.


Build Targets

To get a list of the available targets in the build script, do the following:

  1. Change to the Mulgara home directory:

    $ cd $MULGARA_HOME

  2. To list the targets on a system running a UNIX® operating system:

    $ ./ -projecthelp

    To list the targets on a system running a Windows® operating system:

    $ build -projecthelp

You can chain targets together instead of invoking ant multiple times. This saves the JVM startup time associated with each ant run. So for example, suppose that you made a change to the source, and wanted a clean build. You may want to bring the build back to an original state (no generated files), and generate all distributable files. Instead of two commands, you could type:

$ ./ clean dist

Or, for systems running a Windows operating system:

$ build.bat clean dist


Eclipse Integration

Eclipse requires a number of generated files to be prosent before it can correctly perform dynamic compilation. The required classes are made available available by a target called ideSupport. The Eclipse files present in the checkout already refer to these classes, so all that is required to build the target from the command line, and then refresh the Eclipse project.

To create the required libraries use the following on a command line from the project's working directory:

$ ./ ideSupport

Or, for systems running a Windows operating system:

$ build.bat ideSupport

Once the target is built, refresh the project by selecting "Refresh" from the Project menu, or by pressing F5 on the keyboard.


Generating Mulgara javadoc

To generate the Mulgara javadoc you'll need to perform the following steps:

  1. Change to the Mulgara home directory:

    $ cd $MULGARA_HOME

  2. Run the javadoc target.

    For systems running a UNIX operating system:

    $ ./ javadoc

    For systems running a Windows operating system:

    $ build javadoc

You should then be able to view the Mulgara javadoc.


Generating the Server and the iTQL Shell

To generate the server and iTQL Shell you'll need to perform the following steps:

  1. Change to the Mulgara home directory:

    $ cd $MULGARA_HOME

  2. The logging files are located in $MULGARA_HOME/conf and are named log4j-<component>.xml. To configure the logging system, you'll need to set the path to which logging information is sent. For example the default configuration for the iTQL component is:

    <!-- Log to a file -->
    <appender name="LOGFILE" class="org.apache.log4j.FileAppender">
    <param name="File" value="./itql.log"/>
    <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="%d %-5p [%t] %C{2} - %m%n"/>

    Which sends logging information to a log file named ./itql.log, which will create a logging file in the directory from where you run the interpreter. This may not be appropriate for your environment, so you may need to change this to a more sensible path.

  3. Run the dist target.

    For systems running a UNIX operating system:

    $ ./ dist

    For systems running a Windows operating system:

    $ build dist

    This creates the two binary files called itql-1.1.0.jar and mulgara-1.1.0.jar in $MULGARA_HOME/dist directory.

  4. Run the executable (the version number for your installation may be different):

    $ java -jar dist/itql-1.1.0.jar

If the iTQL Shell starts correctly, you get a prompt back. Enter the quit command at the prompt to exit the interpreter.

ITQL> quit ;


Running a Mulgara Server

Executing an executable JAR file runs the server. To start Mulgara you'll need to do the following:

  1. Change to the directory (folder) into which you downloaded Mulgara:

    $ cd $MULGARA_HOME

  2. Start the executable JAR:

    $ java -jar mulgara-1.1.0.jar.jar

    You should see the following line when the server is starting, identifying the build number:

    1 [main] INFO EmbeddedMulgaraServer - Mulgara Semantic Store version 1.0 Build (v1.1.0)

    Once you see a line similar to the following display in the console the server is ready to be used.

    INFO EmbeddedMulgaraServer - Successfully started Mulgara server at
    rmi://localhost/server1 in directory /usr/local/mulgara/server1

    However, if the following message displays then the HTTP port is already occupied by another process. See the Command Line Options section for more information on how to change this.

    ERROR EmbeddedMulgaraServer - Address already in use

    If you see the following message, you may not have started the RMI registry correctly. As stated previously, see the Command Line Options section for more information on how to change this..

    ERROR EmbeddedMulgaraServer - javax.naming.ServiceUnavailableException
    [Root exception is java.rmi.ConnectException:
    Connection refused to host: localhost; nested exception is: Connection refused]

  3. To verify your installation is working correctly open your web browser and enter the following URL:


    Note - Your HTTP port may be different if you have supplied a -p option.

    Follow the links to the user documentation to learn more about using Mulgara.


Mulgara Configuration File

A default XML configuration file, packaged within the Mulgara executable JAR file, configures how Mulgara runs. This file is shown below.

<?xml version="1.0" encoding="UTF-8"?>

Mulgara Semantic Store configuration file.


<!-- Paths to external component configuration, relative to JAR file -->

The hostname to bind Mulgara to

Note. Not setting will cause Mulgara to bind to the canonical local machine name

Configuration for the Jetty servlet container

Note. Not setting the "Host" parameter will cause Jetty to listen on
all interfaces

<!-- The name of the server, used for RMI binding -->

<!-- RMI registry port -->

The path to persist data to, one of:
+ . - current directory (directory from which Mulgara JAR was run)
+ temp - default system temporary directory
+ <path> - user defined (OS dependant) path

Database implementation to use, one of:
(Metaphasic transactional triple store)

Implementations of the persistent and temporary string and node pools to use,
as well as the resolver class to use as the System Resolver.
(NOT available in the TKS 2.1 beta 1 testing period.)

Implementations of the ContentHandler interface to use for resolving mime
types. (NOT available in the TKS 2.1 beta 1 testing period.)

The factories to use for generating resolver objects.
(NOT available in the TKS 2.1 beta 1 testing period.)

<!-- iTQL script to run on startup -->
<!-- smtp server for email notifications



Mulgara Command Line Options

You can override the default configuration file with individual command line options or with an external configuration file (specified via a command line option).

The individual command line options you can specify are as follows:


If you specify an external configuration file or individual command line options, they are evaluated in the following order:

  1. Default configuration file
  2. External configuration file
  3. Command line options

Java System Properties

In addition to the command line options when starting Mulgara, there are also JavaTM system properties that control how Mulgara runs. These are the -D and -X options specified when you run the Mulgara executable jar file.

Note - The -D and -X options must appear before -jar option.

The Java system properties are as follows:


Running the Test Cases

This section is only applicable if you have been supplied the build environment for Mulgara.

To run the Mulgara test cases you'll need to perform the following steps:

  1. Change to the Mulgara home directory:

    $ cd $MULGARA_HOME/

  2. Run the test target.

    For systems running a UNIX operating system:

    $ ./ test

    For systems running a Windows operating system:

    $ build test

Test output is sent to the $MULGARA_HOME/test/ directory. You can view the files in this directory to obtain more information on test runs.

Note - Individual test cases will usually load up logging configuration from the copy of the template logging configuration file written to $MULGARA_HOME/log4j-conf.xml. If you want to change the logging settings for tests, edit this file.

Valid XHTML 1.0 TransitionalValid CSS 3.0!