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 http://java.sun.com/j2se/, 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:
- Change to the Mulgara home directory:
$ cd $MULGARA_HOME
- To list the targets on a system running a UNIX® operating system:
$ ./build.sh -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:
$ ./build.sh 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:
$ ./build.sh 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:
- Change to the Mulgara home directory:
$ cd $MULGARA_HOME
- Run the javadoc target.
For systems running a UNIX operating system:
$ ./build.sh 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:
- Change to the Mulgara home directory:
$ cd $MULGARA_HOME
- 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"/>
</layout>
</appender>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. - Run the dist target.
For systems running a UNIX operating system:
$ ./build.sh dist
For systems running a Windows operating system:
$ build dist
This creates the two binary files called
itql-1.1.0.jar
andmulgara-1.1.0.jar
in$MULGARA_HOME/dist
directory. - 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:
- Change to the directory (folder) into which you downloaded Mulgara:
$ cd $MULGARA_HOME
- Start the executable JAR:
$ java -jar
mulgara-1.1.0.jar
.jarYou 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 (v
1.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/server1However, 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 - java.net.BindException: 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:
java.net.ConnectException: Connection refused] - To verify your installation is working correctly open your web browser and enter the following URL:
http://localhost:8080
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.
-->
<MulgaraConfig>
<!-- Paths to external component configuration, relative to JAR file -->
<ExternalConfigPaths>
<MulgaraLogging>conf/log4j-tks.xml</MulgaraLogging>
<WebDefault>conf/webdefault.xml</WebDefault>
</ExternalConfigPaths>
<!--
The hostname to bind Mulgara to
Note. Not setting will cause Mulgara to bind to the canonical local machine name
-->
<!--<MulgaraHost>localhost</MulgaraHost>-->
<!--
Configuration for the Jetty servlet container
Note. Not setting the "Host" parameter will cause Jetty to listen on
all interfaces
-->
<Jetty>
<Listener>
<!--<Host>localhost</Host>-->
<Port>8080</Port>
<MinThreads>5</MinThreads>
<MaxThreads>255</MaxThreads>
<MaxIdleTimeMs>60000</MaxIdleTimeMs>
<MaxReadTimeMs>60000</MaxReadTimeMs>
<LowResourcePersistTimeMs>5000</LowResourcePersistTimeMs>
</Listener>
</Jetty>
<!-- The name of the server, used for RMI binding -->
<ServerName>server1</ServerName>
<!-- RMI registry port -->
<RMIPort>1099</RMIPort>
<!--
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
-->
<PersistancePath>.</PersistancePath>
<!--
Database implementation to use, one of:
org.mulgara.store.xa.XADatabaseImpl
(Metaphasic transactional triple store)
-->
<TripleStoreImplementation>org.mulgara.store.xa.XADatabaseImpl</TripleStoreImplementation>
<!--
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.)
-->
<PersistentNodePoolClass>org.mulgara.store.nodepool.xa.XANodePoolFactory
</PersistentNodePoolClass>
<TemporaryNodePoolClass>org.mulgara.store.nodepool.memory.MemoryNodePoolFactory
</TemporaryNodePoolClass>
<PersistentStringPoolClass>org.mulgara.store.stringpool.xa.XAStringPoolFactory
</PersistentStringPoolClass>
<TemporaryStringPoolClass>org.mulgara.store.stringpool.memory.MemoryStringPoolFactory
</TemporaryStringPoolClass>
<SystemResolverClass>org.mulgara.resolver.store.StatementStoreResolverFactory
</SystemResolverClass>
<!--
Implementations of the ContentHandler interface to use for resolving mime
types. (NOT available in the TKS 2.1 beta 1 testing period.)
-->
<ContentHandlerClass>org.mulgara.content.rdfxml.RDFXMLContentHandler</ContentHandlerClass>
<ContentHandlerClass>org.mulgara.content.mp3.MP3ContentHandler</ContentHandlerClass>
<!--
The factories to use for generating resolver objects.
(NOT available in the TKS 2.1 beta 1 testing period.)
-->
<!--ResolverFactoryClass>org.mulgara.resolver.file.FileResolverFactory</ResolverFactoryClass-->
<ResolverFactoryClass>org.mulgara.resolver.lucene.LuceneResolverFactory</ResolverFactoryClass>
<!--ResolverFactoryClass>org.mulgara.resolver.http.HttpResolverFactory</ResolverFactoryClass-->
<ResolverFactoryClass>org.mulgara.resolver.url.URLResolverFactory</ResolverFactoryClass>
<ResolverFactoryClass>org.mulgara.resolver.view.ViewResolverFactory</ResolverFactoryClass>
<!-- iTQL script to run on startup -->
<StartupScript>foo.itql</StartupScript>
<!-- smtp server for email notifications
mail.xyz.com
-->
<Smtp></Smtp>
</MulgaraConfig>
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:
-h
or--help
Display a list of the command line options available.
For example,
java -jar mulgara-1.1.0.jar --help
, displays the following:
-h, --help display this help screen
-n, --normi disable automatic starting of the RMI registry
-x, --shutdown shutdown the local running server
-l, --logconfig use an external logging configuration file
-c, --serverconfig use an external server configuration file
-k, --serverhost the hostname to bind the server to
-o, --httphost the hostname for HTTP requests
-p, --port the port for HTTP requests
-r, --rmiport the RMI registry port
-s, --servername the (RMI) name of the server
-a, --path the path server data will persist to, specifying
'.' or 'temp' will use the current working directory
or the system temporary directory respectively
-m, --smtp the SMTP server for email notification
-n
or--normi
Do not start an RMI server when you start Mulgara.
By default, Mulgara automatically starts an RMI server, if one does not already exist, on port 1099, or the port specified by the
--rmiport
option. In situations where you expect an RMI server to exist already (that is, you are running another Mulgara server on the same host) and you do not want to automatically start another RMI server, use this option.When running multiple Mulgara servers on the same host, it is recommended that you:
- Start an RMI server separately, via the command line using the
rmiregistry
program supplied by the Java SDK. - Start each Mulgara server with the
--normi
option.
- Start an RMI server separately, via the command line using the
-x
or--shutdown
Shutdown the running Mulgara server.
For example,
java -jar mulgara-1.1.0.jar --shutdown
.
-l
or--logconfig
Specify a log4j configuration file to enable fine grain control on logging.
For example,
java -jar mulgara-1.1.0.jar --logconfig file:<installation directory>/Resources/log4j-template.xml
.See the Logging section for more information on the
--logconfig
option.
-c
or--serverconfig
Specify an external configuration file to override the default configuration file.
For example,
java -jar mulgara-1.1.0.jar --serverconfig file:<installation directory>/Resources/Mulgara-config.xml
.
-k
or--serverhost
Specify the fully qualified host name for the embedded RMI server used for incoming iTQL queries. The default is the host name of your machine, automatically determined by your operating system's name resolution order.
See the
--httphost
option for more information.
-o
or--httphost
Specify the host name for the embedded HTTP server used for web services, the MulgaraViewer and Descriptors. The default is the host name of your machine (the same as the RMI server).
You can find the host name bound to Mulgara from the:
- Console output at startup
- Mulgara Viewer (the server URI)
- TMC (the server URI)
ipconfig -all
command (for systems running a Windows operating system)/sbin/ifconfig
command (for systems running a Linux or UNIX operating system)/etc/hosts
file (for systems running a Linux or UNIX operating system)If you are unsure as to what your fully qualified host name is, consult your network administrator.
Note - Machines with multiple host names can have problems with the RMI and HTTP servers binding to the wrong host name. If your machine has multiple host names, or fails to detect the correct host name during host name resolution, you can force binding to a specific host by using the --serverhost and --httphost options, either individually or together.
For example,java -jar mulgara-1.1.0.jar --serverhost localhost --httphost localhost
.
-p
or--port
Specify the port number for the embedded HTTP server. The default is 8080. A conflict occurs if this port is in use (by another application or another Mulgara server).
For example,
java -jar mulgara-1.1.0.jar --port 8081
.
-r
or--rmiport
Specify the port number for the embedded RMI server. The default is 1099. A conflict occurs if this port is in use (by another application or another Mulgara server).
For example,
java -jar mulgara-1.1.0.jar --rmiport 1299
.
-s
or--servername
Specify the RMI server name. The default is server1 (that is,
rmi://mysite.com/server1
). If you are running multiple servers on the same host, you must specify a new server name.For example,
java -jar mulgara-1.1.0.jar --servername server2
.
-a
or--path
Specify the location where Mulgara database files are stored. The default is the
server1
directory (or the name specified using the--servername
option) of your Mulgara installation.For example,
java -jar mulgara-1.1.0.jar --path /usr/local/mulgara
. For systems running a Windows operating system,java -jar mulgara-1.1.0.jar --path c:\mulgara
.Note - The directory you specify is the directory containing the
server1
directory (or the name specified using the--servername
option). Do not specify theserver1
portion of the directory name, as Mulgara appends this automatically to the directory you specify.
-m
or--smtp
Specify an SMTP server to which e-mail notifications are sent.
For example,
java -jar mulgara-1.1.0.jar --smtp mail-mysite.com
.
If you specify an external configuration file or individual command line options, they are evaluated in the following order:
- Default configuration file
- External configuration file
- 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:
mulgara.xa.useByteOrder
mulgara.xa.defaultIOType
mulgara.xa.forceIOType
The above properties control file input and output in the Mulgara data store. See the Controlling File Input and Output in Mulgara section for more information on these properties.
itql.command.log
Specifies the log file that iTQLTM commands are written to by the client application interacting with the ItqlInterpreterBean.
For example,
java -Ditql.command.log=/tmp/itql.log -jar mulgara-1.1.0.jar
shutdownhook.port
Specifies the port listening for a shutdown. If not specified, the default is 6789. Specifying this property is useful when running multiple Mulgara servers on the same machine and you don't want to risk shutting down the wrong one.
For example,
java -Dshutdownhook.port=6790 -jar mulgara-1.1.0.jar
starts Mulgara with a shutdown port of 6790.While
java -Dshutdownhook.port=6790 -jar mulgara-1.1.0.jar --shutdown
performs a shutdown of this Mulgara server.mulgara.rmi.prefetchsize
mulgara.rmi.pagetimeout
The above properties control how the server returns query results to a client.
The server returns query result rows in groups, known as pages, in order to reduce network traffic. The
mulgara.rmi.prefetchsize
property sets the size of a page. That is, the number of rows in a page. The default page size is 1000.If this were the only mechanism in place, each new page fetch would result in a delay as the rows that make up the page are gathered. Reducing the page size reduces the delay, but increases the network traffic. To overcome this, a background thread fetches the next page before it is required.
When the next page is requested:
- The system checks if the next page has already been requested on the background thread. If it has, and it is available, it is returned immediately. That is, there is no delay.
- If the next page has already been requested, but it is not yet available, the system waits for a specified number of milliseconds before it decides the page cannot be returned, and the query times out.
The
mulgara.rmi.pagetimeout
property specifies the time the system waits for the next page before timing out. The default is 60000 milliseconds (60 seconds). - If the next page has not yet been requested on the background thread, it is requested.
mulgara.sp.cachesize
Internally, the system maintains resources as numbers in order to optimize joins and storage space. For example, 1293969 could represent the URI
http://purl.org/dc/elements/1.1/title
. However, when the system needs to order or stream resources to the client, the system performs a lookup to convert the numbers to resources. In most situations a collection of statements have repeating subjects or predicates, and to reduce the amount of duplicate I/O requests, cache memory is used.The
mulgara.sp.cachesize
property sets this cache size. The default is 1000 entries.mulgara.rmi.compression
When a query result returns to the client, the content can be compressed in order to reduce bandwidth consumption. The acceptable values for this system property range from 0 to 9, where 0 is no compression and 9 is maximum compression. The higher the compression, the greater the load on the CPU to perform the compression. The default value is 1, which gives maximum performance at about 70% compression.
Xms
andXmx
The above two properties are Java Virtual Machine (JVM) specific settings that specify the minimum and maximum amount of memory allocate to the JVM, respectively.
Increasing the value of the
mulgara.sp.cachesize
ormulgara.rmi.prefetchsize
properties, or if you have a large number of concurrent users, you can exceed the amount of memory allocated to the JVM (the default maximum is 64 MB) and an out of memory exception occurs. You then need to increase the amount of memory allocated to the JVM.For example, the following sets the minimum memory allocated to 64 MB and the maximum to 128 MB.
java -Xms64m -Xmx128m -jar mulgara-1.1.0.jar -d
Note - Do not over allocate memory to the JVM (using too high a value for
Xmx
). Mulgara uses memory mapped files that are managed by the operating system. Over allocating memory to the JVM reduces the available memory available for the operating system, thus reducing its ability to map files efficiently.
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:
- Change to the Mulgara home directory:
$ cd $MULGARA_HOME/
- Run the test target.
For systems running a UNIX operating system:
$ ./build.sh 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.