Running a Joseki Server

A Joseki server can be run as a standalone server, inside a web application server such as Tomcat or Jetty , or embedded inside a larger system.

The Joseki server is a web application so you will need a web application directory structure, or just the WAR file, where your web application server expects it. Joseki comes with Jetty and configuration files for the webapps/ directory and also works with Tomcat as well.

Running Standalone

To run as a standalone server:

java -cp ... joseki.rdfserver [--port N] [configFile]

Put all the JAR files in the lib/ directory on the classpath. Run like this, the servlet that implements the protocol is running inside a Jetty web server. The appropriate JAR files for Jetty are provided in the full distribution or you can download your own.

Simple Configuration

This section is a brief description of the configuration file. It is fully described elsewhere. Examples are in the directory etc/.

@prefix joseki: <http://joseki.org/2003/07/configuration#> .

<http://server/externalURL>
    a joseki:AttachedModel ;
    joseki:attachedModel     <file:test_data.rdf> ;
    joseki:hasQueryOperation joseki:BindingRDQL ;
    joseki:hasQueryOperation joseki:BindingGET
    .

Suppose the server is run at host example.com

This example puts a single RDF model at URL http://example.com:2020/externalURL (note the http://server/ has been replaced - this keeps configuration files portable). The default port of the server is 2020 - you can change it from the command line with the --port.

The data for the model comes from a file: test_data.rdf which is assumed to be in XML syntax as the suffix is ".rdf".

The operations allowed are queries over HTTP GET: plain GET and RDQL queries. No other operations are allowed.

Logging

Joseki uses Jakarta Commons logging. You can choose between log4j or Java 1.4 logging. See the Joseki logging page for further information.

Running as a Web Application

Joseki is a single servlet which can be added as a separate web application or within some other web application. In order to limit the size of the download, Joseki does not come fully packaged as a web application but there is support for assembling the right directory layout in the ant build file.

Ant Build Targets

The following ant targets create the necessary web application, calling it "joseki".

ant webapp-deploy: Build the web application in webapps.build/joseki and copy to webapps/joseki.
ant webapp-clean: Remove the web application but leave in place the minimal configuration for the standalone server.

These ant build targets do not recompile Joseki – they take joseki.jar from the lib/ directory.

Web application servers and model URLs

Note also that the URL for your models is unlikely to be the same as for the standalone server. In the standalone case, Joseki is deployed as the root webapp so there is no webapp name in the URL; under Tomcat (unless you change the configuration in server.xml) it will be deployed as webapp "joseki", and not the root app, making the URLs look like http://host:port/joseki/model.

Web Application server: Jetty

Joseki can run inside Jetty. The standalone server uses Jetty as its embedded web application server. The Joseki and Jena JAR files just need to be included on the classpath.

Web Application server: Tomcat

Tomcat does not pass CLASSPATH information onto web applications. See the Tomcat 4.1 Class Loader How-to. You need to construct a web application using ant, or manual lay out the files. The configuration file can be put in etc/ or in the web application area under webapps/joseki/etc/. There is an example server.xml file in the conf/ directory. The default port number is 2525.

On first request, the servlet initialises. The standalone server has already constructed a dispatcher and passes it to the servlet; in a web application container, servlet initialization finds no prebuilt dispatcher and builds one itself. This happens on when you first do a query - you will not see any output during tomcat start-up.

There are some environment variables that control Tomcat (this applies to v4 and v5).

CATALINA_HOME is the root of all the files the server needs to run (e.g. jars files).
CATALINA_BASE is the current directory for the running server. If you do not set CATALINA_BASE, it defaults to CATALINA_HOME. Tomcat will look in the webapps/ directory in its own installation; finding the configuration file will be based on that directory.
Make sure CATALINA_TMPDIR names an existing, writable directory – there are strange errors if Tomcat can't use it.

A simple setup is to run in the Joseki directory with CATALINA_BASE set to the current directory. The provided configuration file is in the right place in etc/joseki.n3. The minium steps needed are:

Run ant webapp-deploy
Set CATALINA_BASE to the current directory and export it
For logging, set and export
JAVA_OPTS=-Dlog4j.configuration=file:etc/log4j.properties
Run the Tomcat provided startup.bat or startup.sh.

If you are deploying Joseki in a larger Tomcat installation, it is easier to put the configuration file in the webapp directory area itself: ???/webapps/joseki/etc/joseki.n3.

You can change the name and location of the configuration file by editting web.xml.

Finding the Joseki Configuration file

The Joseki configuration file is a file read from the local filing system. If it is a relative file name, it is searched for in the following places, in order:

relative to the current directory (for Tomcat, that is where CATALINA_BASE identifies)
relative to the web application area via the servlet context
using the classpath using the Java class loader mechanism

The default name is etc/joseki.n3.

Manual Construction

It is easier to use ant to do this but if you do not have ant installed then you can construct the web application manually. The necessary JARs files are in the lib/ directory of the distribution. Copy the JARs to webapps/joseki/WEB_INF/lib. Copy etc/webapp-web.xml to webapps/joseki/WEB_INF/web.xml

Include the JARs: antlr.jar, concurrent.jar, icu4j.jar, jakarta-oro-2.0.5.jar, jena.jar, joseki.jar, junit.jar, log4j-1.2.7.jar, rdf-api-2001-01-19.jar, xercesImpl.jar, xmlParserAPIs.jar.

Do not include org.mortbay.jetty.jar, org.mortbay.jmx.jar (the Jetty runtime), jasper-compiler.jar, jasper-runtime.jar, (the JSP engine, already part of your web application server), nor javax.servlet.jar.

Differences in the way Joseki is run

The only difference is when the configuration file is loaded. When run as a standalone server, the configuration file is read during start-up. When run as a web application it is read when the web application is initialised, usually at the time of the first request.

Running as an Embedded Server

See the class org.joseki.server.RDFServer. The standalone server application is a command line wrapper to creating an instance of this class.