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.
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.
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.
Joseki uses Jakarta Commons logging. You can choose between log4j or Java 1.4 logging. See the Joseki logging page for further information.
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.
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.
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.
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.
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.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:
ant webapp-deploy
CATALINA_BASE
to the current directory and export itJAVA_OPTS=-Dlog4j.configuration=file:etc/log4j.properties
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
.
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:
The default name is etc/joseki.n3
.
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
.
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.
See the class org.joseki.server.RDFServer
. The standalone server
application is a command line wrapper to creating an instance of this class.