Chapter 2. Installing Sesame
Sesame can deployed in several ways. The two most common scenarios
include deployment as a java library, or deployment as a server. In
this chapter, both installation scenarios are explained.
2.1. Library installation
To use Sesame as a library in a java application, one needs the
Sesame jar files. These are:
- sesame.jar. The Sesame core classes.
- rio.jar. Rio (RDF I/O) is a set of parsers
and writers for different RDF serialization formats (RDF/XML,
Turtle, N-Triples).
- openrdf-model.jar. Shared interfaces and
classes for the RDF model.
- openrdf-util.jar. Shared utility classes.
These files can be found in the lib directory
of the binary download. Simply including them in your classpath will
allow you to use the functionality of Sesame in your own Java
application.
Sesame requires Java 2, version 1.4 or newer, to function properly.
If you intend to use client/server communication over HTTP, then you will additionally
need the following third-party libraries:
These third-party libraries can be found in the ext/ directory of the
source distribution of Sesame, and are also included in the library directory
of the Sesame Web Archive (sesame.war). More information about these libraries, including
license information, can be found in the file doc/thirdparty.txt.
For more information on how to use Sesame as a library, see
Chapter 7, The Sesame API
The Sesame server requires the following software:
- Sesame itself
- A Java servlet container (running Java 2, version 1.4
or newer) for running the Sesame servlets
Sesame should be able to run on any Java servlet container that
supports the Servlet 2.2 and JSP 1.1 specifications, or newer.
So far, it has been tested with Tomcat and, in the case of
Oracle, with OC4J. It has also been reported to work without
problems on BEA WebLogic 8.1 SP2 and Jetty. Please post any
reports about compatibility with other servlet containers to our
forums.
Sesame has several options for storage of RDF data: it can store
data in main-memory (optionally with a dump to file for
persistence), it can store data on disk in a dedicated file
structure, or it can store data in a relational database. See
section More on the RDBMS for more
info about the last option.
2.2.2. Installation under Tomcat 4 or 5
The following steps describe the easiest procedure to install
Sesame on Tomcat 4.x or 5.x. The described procedure doesn't
require any reconfiguration of Tomcat itself, but it might not
be the best option for you. Please see the documentation that
came with your copy of Tomcat if you want more fine-grained
control over where and how Sesame should be installed.
-
Install Tomcat. This usually consists of downloading the
binary Tomcat distribution from
http://jakarta.apache.org/tomcat
and installing it in an appropriate location on your disk
(we will refer to this location as
[TOMCAT_DIR] here). Please see the
Tomcat documentation for more information on how to get it
up and running.
-
Go to the web applications directory
([TOMCAT_DIR]/webapps/ by default) and
create a directory 'sesame' there.
-
Extract the sesame.war file (which can
be found in the lib directory of the
binary Sesame distribution) to the newly created 'sesame'
directory. You can do this on the command line by changing
directories to the new 'sesame' directory and executing the
command jar -xf [PATH/TO/]sesame.war. You
can also use a program like WinZip or unzip to extract the
archive. We will refer to the directory where you have
extracted the sesame.war file as
[SESAME_DIR] in the rest of this
document.
-
In case you are planning to use a database with Sesame, copy
the appropriate JDBC-driver file(s) to the directory
[SESAME_DIR]/WEB-INF/lib/.
-
Copy the file
[SESAME_DIR]/WEB-INF/system.conf.example
to [SESAME_DIR]/WEB-INF/system.conf.
NOTE: only do this for a fresh install of Sesame, if you are
upgrading you will already have a config file, and copying
the example over it will destroy your existing
configuration. The example file contains some repository
entries for different Sails and databases, and one user
account. The file may require some modifications in order to
work on your machine. Please check out
Server administration if you want to learn
how to do this.
-
(Re)start your Tomcat server and Sesame should now be up and
running. You can access the Sesame web interface at
http://[MACHINE_NAME]:8080/sesame.
2.2.3. Installation under Tomcat 3
Installation of Sesame under Tomcat 3 is almost identical to the
procedure described above. It requires one additional step:
-
Perform the steps described in
Installation under Tomcat 4 or 5.
-
Copy the file
[SESAME_DIR]/WEB-INF/lib/web.xml-2.2
over the existing web.xml file and
(re)start your Tomcat server.
2.2.4. Installation under Oracle Container for Java (OC4J)
Sesame has been tested with OC4J v9.0.3.0. The installed
procedure differs from the standard installation procedure.
2.3. Testing Your Installation
If you have followed the installation instruction described in the
previous section, the Sesame server should now be up-and-running.
Pointing a browser to the location where you have installed Sesame
(e.g. http://[MACHINE_NAME]:8080/sesame/ if you
have installed Sesame under Tomcat as described in this document)
should now display the Sesame web interface.
You should also test whether the Sesame servlets are running
correctly, and whether Sesame can talk to the RDBMS (if applicable).
Select one of the repositories that you have configured and press
'Go>>'. Click on the 'Add (www)' link in the toolbar at the
top of the window, and try to upload the
test.rdf file from Sesame's admin directory
(e.g. http://[MACHINE_NAME]:8080/sesame/admin/test.rdf).
You can do this by typing this URL in the first text field and
by clicking on the 'Add data' button after that.
If the data-upload was successful, you should also be able to
extract the uploaded data. Click on the 'Extract' link in the
toolbar and press the 'Extract' button. This should yield an RDF
document describing all classes and properties in the repository.
Sesame has been successfully installed if all of this works. You
can remove or reconfigure the test user account and repository
if you want. If you haven't done so already, you can take a look
at the next chapter for information on how to add and remove
user accounts and repositories to/from Sesame.
Sesame has an RDBMS-Sail that uses an RDBMS for storing RDF data.
Currently, this Sail supports
PostgreSQL,
MySQL,
Microsoft SQL
Server and
Oracle
databases. The first two RDBMS's are open source and are freely
available on the Internet. Please check the documentation delivered
with these databases for any questions on how to get them installed.
Sesame's RDBMS Sail has been extensively tested in combination with
MySQL and PostgreSQL. The RDBMS Sail used to perform much better in
combination with MySQL than with PostgreSQL, but recent versions of
PostgreSQL have shown major performance increases. These two
RDBMS's now have comparable performance, with PostgreSQL having an
edge over MySQL where it concerns the evaluation of complex queries.
The SQL Server- and Oracle support are third-party contribution and
we have no comparitive data on their performance.
2.4.1. Notes on PostgreSQL
-
Recent versions of PostgreSQL are a lot faster than the 7.1
version that Sesame was originally developed against. The
most recents tests have been done using version 8.1.4. If
possibly, you should use the newest possible (stable)
version of PostgreSQL that is available.
-
JDBC-drivers for PostgreSQL can be found at
http://jdbc.postgresql.org, but these also
come bundled with (some of) the PostgreSQL installation
packages.
-
Make sure that the PostgreSQL server is running with the
TCP/IP connections enabled. If TCP/IP is not enabled, the
JDBC-driver will not be able to talk to the server.
- pgAdmin is an
excellent tool to administer a PostgreSQL server (for those
who don't mind using GUIs).
-
The RDBMS Sail will need an (empty) database on the
PostgreSQL server, as well as a user account that has access
to (or owns) that database. You need to create these
manually, for example by using the pgAdmin tool mentioned
above. In most cases, the encoding of the new database
should be set to 'UTF8'. The RDBMS Sail will take care of
creating the required tables and indexes when first run.
We'll assume that the user account is called 'sesame' in the
rest of this document.
-
Sesame tries to use the character set features that were
introduced in MySQL 4.1 to properly handle non-ASCII
characters. Sesame will automatically detect whether these
features are available and will fall back to using BLOBs
when an older version of MySQL is used. In that case, Sesame
will not be able to properly handle non-ASCII characters in
literals and namespace names.
-
Sesame's RDBMS Sail makes extensive use of the TRUNCATE
command. Unfortunately, this command
is
mapped to the much slower DELETE command for
InnoDB tables in pre-MySQL 5.0.3 releases. To achieve
reasonable performance one should use MySQL 5.0.3 or newer,
or configure MySQL to use the older MyISAM tables instead of
InnoDB tables.
-
Several people have reported problems with 4.x and early
5.0.x version of MySQL, especially with versions that came
pre-installed with Linux distributions. So far, all these
problems were resolved by installing the most recent
stable version of MySQL and its
JDBC-driver. Please try this before reporting problems when
using unstable/beta releases.
- MySQL
Administrator is an great tool to administer a
MySQL server (for those who don't mind using GUIs).
-
The RDBMS Sail will need an (empty) database on the
MySQL server, as well as a user account that has access to
that database. You need to create these manually, for
example by using the MySQL Administrator tool mentioned
above. In most cases, the encoding of the new database
should be set to 'UTF8'. The RDBMS Sail will take care of
creating the required tables and indexes when first run.
We'll assume that the user account is called 'sesame' in the
rest of this document.
Note: We do not have first-hand experience with using the RDBMS
Sail on Oracle. The comments below are based on feedback that we
have received from users.
-
The RDBMS Sail has been tested with Oracle 9i and newer,
Oracle 8i does not work due to lack of support for left
(outer) joins. Oracle 9.2.0.1.0 has a bug affecting
ANSI-style left (outer) joins which makes it
incompatible with Sesame. This bug has been fixed in version
9.2.0.4.0.
-
The Oracle JDBC driver can be found at
[ORACLE_HOME]/jdbc/lib/classes12.jar or
at http://otn.oracle.com/.
-
You will have to create a user with appropriate rights
(resource + connect).
-
If ORA-0150 (maximum key length (...) exceeded) is raised
during creation of your DB-Schema the reason might be in
your DB configuration. You have got the following options:
-
Increase db_block_size in your init.ora and create a
new database to allow larger index columns (refer to
Oracle Note:136158.1).
-
Edit Oracle.java in package
org.openrdf.sesame.sailimpl.rdbms
and alter the size of the Datatype NAME and LABEL.
The new size can be calculated from the error
message, e.g.: "ORA-01450 maximum key length (3166)
exceeded at varchar(3157)" (length-9 for block
overhead).