================
The Jena Toolkit
================



Introduction
============

There are a number of RDF processing implementations around. One of the most widely
known is the `Jena toolkit <http://incubator.apache.org/jena/>`_. Jena
started off as a project at the HP Labs in Bristol, and was open
source from the outset. HP ceased active development of Jena in 2009,
and in 2010 it was adopted as an incubation project by the Apache
Software Foundation.

In these notes, I will refer to the 2.6.x releases, which pre-date the
adoption by ASF.

Jena is easy to install, and `documentation <http://incubator.apache.org/jena/documentation/>`_ is also available.


Installing Jena
=================

Although Jena has been developed as a set of Java libraries, I will
focus on using it via its command-line utilities. See the `Jena API
docs <http://incubator.apache.org/jena/tutorials/rdf_api.html>`_ for a good overview of
processing RDF from within Java.

The 2.6.2 version of Jena is installed
on DICE in the following directory::

      /usr/share/java/jena/bin

To check the status of Jena on the
desktop you are using, use the :command:`ls -l` command on the above directory. The
output you get should look something like this:

.. code-block:: bash

    dice:~> ls -l /usr/share/java/jena/bin
    total 72
    -rwxr-xr-x 1 root root  164 Jun 22  2009 arq
    -rwxr-xr-x 1 root root  167 Jun 22  2009 arq_version
    -rwxr-xr-x 1 root root  143 Jun 18  2009 jena_path
    -rwxr-xr-x 1 root root 1059 Oct 15 10:48 make_classpath
    -rwxr-xr-x 1 root root  163 Jun 18  2009 n3
    -rwxr-xr-x 1 root root  165 Jun 22  2009 qexpr
    -rwxr-xr-x 1 root root  166 Jun 22  2009 qparse
    -rwxr-xr-x 1 root root  165 Jun 22  2009 qtest
    -rwxr-xr-x 1 root root  165 Jun 22  2009 query
    -rwxr-xr-x 1 root root  167 Jun 18  2009 rdfcat
    -rwxr-xr-x 1 root root  171 Jun 18  2009 rdfcompare
    -rwxr-xr-x 1 root root  168 Jun 18  2009 rdfcopy
    -rwxr-xr-x 1 root root  169 Jun 18  2009 rdfparse
    -rwxr-xr-x 1 root root  164 Jun 22  2009 rset
    -rwxr-xr-x 1 root root  170 Jun 18  2009 schemagen
    -rwxr-xr-x 1 root root  166 Jun 22  2009 sparql
    -rwxr-xr-x 1 root root  166 Jun 22  2009 update
    -rwxr-xr-x 1 root root  168 Aug 14 14:02 version


.. _dice-install:

DICE Set Up
-----------

#. From the command line, set the Jena root directory::

     dice:~> export JENAROOT=/usr/share/java/jena


#. Jena should now work. You can test it by using the :command:`--help` option to one
   of the programs, such as :file:`rdfcat`:

   .. code-block:: bash

      dice:~> /usr/share/java/jena/bin/rdfcat --help
      Usage: java jena.rdfcat (option|input)*
      Concatenates the contents of zero or more input RDF documents.
      Options: -out N3 | N-TRIPLE | RDF/XML | RDF/XML-ABBREV
	       -n  expect subsequent inputs in N3 syntax
	       -x  expect subsequent inputs in RDF/XML syntax
	       -t  expect subsequent inputs in N-TRIPLE syntax
	       -[no]include  include rdfs:seeAlso and owl:imports
      input can be filename, URL, or - for stdin
      Recognised aliases for -n are: -n3 -ttl or -N3
      Recognised aliases for -x are: -xml -rdf or -rdfxml
      Recognised aliases for -t are: -ntriple
      Output format aliases: x, xml or rdf for RDF/XML, n, n3 or ttl for N3, t or ntriple for N-TRIPLE
      See the Javadoc for jena.rdfcat for additional details.

#. You can make this all a bit more convenient by adding the following lines to your
   :file:`.brc` (bash shell configuration) file:

   .. code-block:: bash

      export JENAROOT=/usr/share/java/jena
      export PATH="${JENAROOT}/bin:${PATH}"
      
   The first line means that the environment variable :envvar:`JENAROOT` will be set
   automatically for you whenever you log in to a DICE machine. The second line means
   that you don't need to use the full pathname for Jena executables; instead of
   :command:`/usr/share/java/jena/bin/rdfcat` you can just use the short command
   :command:`rdfcat`.


Installing Jena on your own computer
------------------------------------

#. Download the latest stable version of Jena (namely, 2.6.4) from `Jena download on Sourceforge
   <http://sourceforge.net/projects/jena/files/Jena/Jena-2.6.4/jena-2.6.4.zip/download>`_. 

#. Unzip the archive, which should create a sub-directory :file:`Jena-2.6.4`
   in your home directory. Using the command line, you can do this as follows::

     : unzip jena-2.6.4.zip

#. From the command line, set the Jena root directory::

     : export JENAROOT=~/Jena-2.6.4

#. Add execute permissions to all the files in the :file:`bin` directory::

     : chmod u+x $JENAROOT/bin/*


#. Jena should now work in the same way as it does on DICE.



rdfcat
------

One of the most basic things we can do is parse an RDF file to check that it is
well-formed, and also convert it between N3 (similar to Turtle) and RDF/XML format. This can be done with
:command:`rdfcat`. As mentioned above, you can get help for this on the command line.
Slightly more detailed information can be found in the `Javadoc for rdfcat
<http://incubator.apache.org/jena/documentation/javadoc/jena/jena/rdfcat.html>`_

To give an example, let's suppose we want to process 
:download:`this RDF file in N3 format <../rdf/cafes.n3>`:

.. include:: ../rdf/cafes.n3
   :literal:

To convert the file to RDF/XML format, do the following::

   dice:~> rdfcat -out xml cafes.n3 

You can also convert in the other direction. For example, suppose that you created a FOAF
file :file:`foaf.rdf` in RDF/XML. Then the following command will convert it to N3
and save it in an appropriate file:

.. code-block:: bash

   dice:~> rdfcat -out n3 foaf.rdf > foaf.n3

We can also merge several graphs into one. Suppose we are given :

.. include:: ../rdf/knows.n3
   :literal:

Then we can merge the two graphs to form a new file :file:`merged.n3` as follows::

     rdfcat -out n3 cafes.n3 knows.n3 > merged.n3