Running a Joseki Server

A Joseki server can be run as a standalone server, inside a web application server 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 Java logging. Unless you set the environment variable java.util.logging.config.file, the standalone server will load the file "etc/logging.properties" to control the output of log messages.

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:
ant format-webapp: just layout the
ant war-file: build a WAR file for Joseki, taking the JAR files

These target construct the directory structure in webapps.build/, you then copy the files to you own webapps area, usually webapps/.

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

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. 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.

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
relative to the web applciation 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.