Mulgara

h1. Deployment

When building Mulgara for deployment you have to select one or more build targets. This page describes the various targets, and what the resulting artifacts are used for.

The standard target is simply _dist_ which builds all the major deployment targets.

h2. Targets

The artifacts created by each of the deployment targets are:

 *dist::

   All other distribution targets.

 *embedded-dist*::

   Creates mulgara-_version_.jar

 *querylang-dist*::

   Creates querylang-_version_.jar

 *driver-dist*::

   Creates driver-_version_.jar

 *descriptor-dist*::

   Creates descriptor-_version_.jar

 *mulgara-war*::

   Creates mulgara-_version_.war

 *lite-dist*::

   Creates mulgara-lite-_version_.jar

 *raw-dist*::

   Creates mulgara-raw-_version_.jar

 *core-dist*::

   Creates mulgara-core-_version_.jar

h2. JARs

The selection of which Jar to use is dependent on the deployment environment. The following is a description of each Jar.

h3. mulgara-_version_.jar

This is the general server jar. This contains the complete Mulgara system, and includes all the 3rd party libraries that Mulgara relies on. The Jar is executable, so it can be started easily with:

<pre>

<code class="sh">

 java -jar mulgara-x.y.z.jar

</code></pre>

No classpath is necessary to execute this jar, since everything is included.

If the built-in configuration is used, then Mulgara will create a database on disk, start an HTTP server with various web services, and an RMI server for Java connections. The default database will support all of the default resolvers and content handlers.

A different configuration can be set up at compile time (by editing the "conf/mulgara-config.xml":http://mulgara.org/svn/mulgara/trunk/conf/mulgara-config.xml file), or at runtime by using the *-c* command-line option. Note that the *-c* option is used to point to a URL, and not a file. So an example of using this might be:

<pre>

<code class="sh">

 java -jar mulgara-x.y.z.jar -c "file:/home/user/mulgara-config.xml"

</code></pre>

Use the *-h* option for a full set of command line options for the server program.

While useful, this jar is not suitable for use in an existing environment like Tomcat, due to the potential conflict between the environment path and the 3rd party jars that have been built in.

h3. querylang-_version_.jar

The is the general client jar. This contains everything needed to connect to a server, including a console application for issuing commands. Like _mulgara-version.jar_ this jar includes all the 3rd party libraries it needs, though this is significantly less.

The console application can be started in one of two modes. The default is a GUI console:

<pre>

<code class="sh">

 java -jar querylang-x.y.z.jar

</code></pre>

This brings up a Swing window containing a "command shell", useful for typing TQL commands, complete with command line editing and shell history. Java does not provide terminal controls by default, which made it impossible to develop this for use on the command line. However, the "Jline":http://jline.sourceforge.net/ library now makes this feasible, and consequently we expect to deprecate the Swing version soon.

It is also possible to run the client without a window, on a batch script. This uses the *-s* switch, and must specify a URL for the script. An example of running a script in a local file is:

<pre>

<code class="sh">

 java -jar querylang-x.y.z.jar -s "file:/home/user/data/myscript.tql"

</code></pre>

Use the *-h* option for a full set of command line options for this client. Also consider using the tools found in the "*tools*" directory of the sources. While these were built to demonstrate the use of the various APIs, they are often more useful than the complete client application. There are two applications here: *org.mulgara.tools.Tql* and *org.mulgara.tools.Sparql*. See the associated "README.txt":http://mulgara.org/svn/mulgara/trunk/tools/README.txt file for building and using these.

Like _mulgara-version.jar_, this jar contains more than is desirable for some environments.

h3. driver-_version_.jar

This jar contains the client API library. This is very similar to *querylang-_version_.jar*, but it does not include a command line interface, or the shell GUI.

This Jar provides the Connection API. This starts with a Connection, along with the SPARQL and TQL parsers for creating Commands to send over the Connection. For an example of using this API, see the "Tql":http://mulgara.org/svn/mulgara/trunk/tools/src/org/mulgara/tools/Tql.java and "Sparql":http://mulgara.org/svn/mulgara/trunk/tools/src/org/mulgara/tools/Sparql.java example tools.

h3. descriptor-_version_.jar

This provides a servlet for deploying Descriptors on a Java web server. Descriptors allow queries to be attached to a URL, with the results rendered through XSLT.

h3. mulgara-_version_.war

This is a WAR file (Web ARchive). It makes Mulgara available to services in a Java web server, and provides a web interface to the database.

h3. lite-_version_.jar

This version of Mulgara has fewer features than the main distribution, but not by much. This may be dropped soon.

h3. raw-_version_.jar

The full Mulgara distribution, but without embedded 3rd party libraries. You will want to use this version instead of *mulgara-_version_.jar* if need to avoid conflicts in the class path, such as deploying into Tomcat.

h3. core-_version_.jar

This contains the classes required to instantiate a *Database* object.

It contains no HTTP services, and avoids some of the optional resolvers. The remaining resolvers are:

* Store resolver: _the main database._

* File resolver: _select from RDF files._

* Lucene resolver: _full text searching._

* HTTP resolver: _select from URLs starting with !http://._

* URL resolver: _select from static RDF documents._

* Memory resolver: _store and select from temporary graphs stored in RAM._

* View resolver: _Select from graphs defined by other queries._

* Remote resolver: _Select from graphs on other Mulgara servers._

* Relational resolver: _Select from a "D2RQ":http://semanticweb.org/wiki/D2RQ transformation on a relational database._

* XSD resolver: _Provides virtual statements on literals, based on their "XSD datatypes":http://www.w3.org/TR/xmlschema-2/#built-in-datatypes._

* Prefix resolver: _Provides selection based on the start of a URI, or string literals._

* Node type resolver: _Provides selection of RDF nodes based on the 3 types: URIs/Literals/Blank._

* Null resolver: _provides the "empty" graph._

A cut down configuration file representing the reduced services is provided in this jar (_/conf/mulgara-x-config.xml_). Also, the *org.mulgara.server.!EmbeddedMulgaraServer* class is still present in this jar, meaning that it _is_ possible to start up a minimal server from the command line.

To use this jar, the following jars must be available in the classpath:

* activation-1.1.1.jar

* antlr.jar

* carol-2.0.5.jar

* castor-1.2-xml.jar

* commons-codec-1.3.jar

* commons-discovery-1.2.jar

* commons-httpclient-3.1.jar

* commons-logging-1.1.1.jar

* connector-1_5.jar

* emory-util-2.1-remote.jar

* howl-logger-0.1.11.jar

* icu4j_3_4.jar

* interruptiblermi-1.1.jar

* jargs-0.2.jar

* jena-2.5.6.jar

* joda-time-1.5.2.jar

* jotm-2.0.10.jar

* jotm_jrmp_stubs-2.0.10.jar

* jta-spec1_0_1.jar

* log4j-1.2.15.jar

* lucene-core-2.4.0.jar

* saaj-1.4.jar

* serializer-2.7.0.jar

* sesame-model-2.2.1.jar

* trove-2.0.4.jar

* xercesImpl-2.9.1.jar

This list may be reduced in future versions. It should also be clear that the _lucene_ jar is only needed by the Lucene resolver, and the _commons-httpclient_ jar is only used by the HTTP resolver. If a configuration without these resolvers is provided, then these jars can be skipped.

Despite not providing HTTP services, running the EmbeddedMulgaraServer application also requires:

* jetty-6.1.11.jar

* jetty-util-6.1.11.jar

We expect to remove the requirement for these jars in an upcoming version.