about and contact arti cl es proj ects research bl og

home
articles index
This work is
licensed under a
Creative Commons
Attribution-
ShareAlike 2.0
License.


ian dickinson ephemerian
A complete beginner's guide to starting a Jena project in Eclipse
I fairly often get email of the following form:
Dear Mr/Dr/Professor Dickinson
I am Jena newbie. I can't attach the jena to eclipse. could you please give me help to resolve
this problem.
I'm not a prof, by the way, but it's attering to be promoted! So this article is for all those who are new
to Jena and Eclipse. This article is not:
A Java programming tutorial
Instructions for installing Eclipse
A comprehensive Jena tutorial
Instead, my goals for this article are to show you how get the most basic possible Jena program set
up in Eclipse. In other words, the Jena equivalent of hello world.
Preamble
Jena is a programmer's API (application programming interface) for Java semantic web applications.
It isn't a program or tool that you run - if that is what you are looking for, I would suggest perhaps
TopBraid Composer as a good option. So the primary use of Jena is to help you write Java code that handles RDF and
OWL documents and descriptions. I use Eclipse as my Java development of choice, other environments are available,
but I don't use them and so the experience I can pass along is based on Eclipse.
Prerequisites
You will need to:
1. Download and install eclipse. This article was written with Eclipse 3.3.1, but the exact version number should not
matter as the main Eclipse user interface has been stable for a while.
2. Download and unzip Jena. At the time of writing, the current version of Jena is 2.5.5, but again it won't matter if
you use a different version.
I'm going to use Windows for this tutorial, but the same steps apply to Linux and, I presume, MacOS. In fact, on my
Windows machine I use a directory structure similar to Linux: rather than c:\Documents and Settings\ijd as the
base directory, I use c:\home\ijd. This is a personal choice that makes it easier to write scripts that run on Linux and
Cygwin on Windows, but there's no special reason for you to do the same. However, it is often a good idea to avoid path
names with spaces in them if you can. So my Jena installation is in c:\home\ijd\projects\jena2. Wherever you
see this path in the notes below, substitute the location where you have installed your own copy of Jena.
Step-by-step guide
This tutorial really is aimed at Eclipse newcomers, so I'm going to take it a step at a time. Feel free to skip ahead if you
have some experience with Eclipse already.
Step 1 create a Java project
Eclipse organizes les into projects, so we need a project for this tutorial. Depending on the plugins installed, Eclipse
may show a large number of different types of project. A plain Java project is ne for a basic Jena application. If you
want to, for example, develop a Java servlet that uses Jena, then choose a suitable project type.
For clarity, I'm starting with an empty Eclipse workspace:
I need to create a new Java project:
Next I need to set up the internal structure of the project. There are many schools of thought on this. I usually use a
basic structure that is taken from Maven. Source code is in src/main, with Java code in src/main/java, ontologies
in src/main/owl, etc. Compiled Java class les go into target/classes. So when I create a new project, I edit the
defaults to reect these preferences. However, if the defaults suit you, or you don't know enough to care about those
details yet, just accept the default settings. Alternatively, if your project or educational institution has suggested
guidelines, then go with those.
Step 2: create the hello world class
Java code is stored in les that correspond to the declaration of a Java class, so I need to create a class for my hello
world example. In the project explorer pane (which is on the left by default, but you can move it around in Eclipse), I
select the project's Java source folder and right-click to get the context menu to show:
Step 3: adding the Jena libraries
OK, so now let's write some Jena code. The rst thing I'll need to work with is a Model: a container for RDF statements.
The Model class is in package com.hp.hpl.jena.rdf.model, so I'll rst import that class, and then create an
instance of it.
OK, so why the red wavy lines? These are Eclipse's way of indicating a problem. If I tried to compile this code using
javac on the command line, I'd get an error saying that the package com.hp.hpl.jena.rdf.model can't be found
anywhere, and that the class Model isn't dened. On the command line, I would x this by setting the Java classpath.
Essentially, that's what I do in Eclipse too, but Eclipse makes it rather easier to do. Notice that I haven't actually said
anywhere yet that this is a Jena project. All I've said is that it's a Java project. What's the difference? Simply this: Eclipse
has to know where to nd the Jena classes I would like to refer to from my program. Eclipse calls the locations where it
can nd the supporting code I want to refer to as the build path.
There are actually a few different ways of setting the build path in Eclipse. One way I could do it is to create a lib
directory in my project top-level folder, then copy the Jena .jar les there, and then link that directory to my project's
build path. That works, but there's a better way: dening a user library. A user library is a declaration of a library
(collection of supporting code) that I can reference from any project. Once I have this set up once, I can use the same
library denition in multiple different projects. Moreover, if I subsequently update Jena to a new release, then once the
library is updated every project in my Eclipse workspace will see the new version. With the copy-les-to-the-lib-folder
method, I have to re-copy to every project that uses Jena. Here's how I create the Jena user library, starting from the
Preferences menu:
Click new to create a new user-library:
Now I click on add jars to add the .jar les from Jena. .jar les contain the compiled Java libraries that Jena uses,
together with the Jena code itself in jena.jar. The JAR selection dialogue that pops up allows me to select which
.jar les are in my user-library. I have selected all of the .jar les in the lib/ directory of my Jena install directory:
Result:
That's actually enough to allow me to use Jena in Eclipse, but there's a couple of additional optional steps that make
programming a bit easier. I can tell Eclipse where to nd the source code and the javadoc for the Jena classes (I'll show
how that's helpful later on). Next to the jena.jar entry in the user library, there's a little + icon. Clicking that expands
the details of the .jar entry:
I can tell Eclipse that the source code is in the src/ folder of my Jena install directory. I click on the Source attachment
line, then the Edit... button. In the source attachment conguration dialogue, I click the External folder button and then
browse to the right location:
Similarly, I can notify Eclipse of the location of the Javadoc by rst selecting the Javadoc location line of the library entry,
then following a similar process. Notice here that the location path is a URL (it starts file:). This is because the
location can also be a Javadoc web site, though I'm not using that capability here.
With the Jena user library congured, I click OK to close the library conguration dialogue.
Step 4: Finishing the hello world program
Now I can go back to my project, and congure the Java build path to use the library I just created. To start, I right-click
on the project node in the explorer window to bring up the project properties menu, navigate to the build path menu
option and add the library:
Having updated the build path, Eclipse will automatically rebuild the project (i.e. recompile the Java code). With that,
some of the errors will go away, since the import statement can now nd the class to be imported, and so the Model
class name is meaningful to the compiler.
However, there is still a remaining error because ModelFactory is not dened. What is needed is a suitable import
statement. This is easily xed in Eclipse, either by clicking on the error symbol (the red 'x' on the left margin), or by
positioning the cursor just after the ModelFactory class name, and pressing ctrl-space, which triggers Eclipse to
show the possible completions for the name:
When I select the rst of the presented options (i.e. ModelFactory rather than ModelFactoryBase), Eclipse will ll in
the import statement automatically:
Look, ma, no errors!
Eclipse's auto-complete feature is also useful when adding code. For example, if I type Resou followed by ctrl-space I
get the possible completions that match that name:
Notice the Javadoc comment in yellow on the candidate completion (Resource in this case). This extra information
comes from having added the source code and javadoc locations when I specied the library in step 2, above. If you
miss out specifying the source code and javadoc, Eclipse can't be so helpful in describing possible auto-completions. It
also will affect the debugging view, though I'm not discussing that in this article.
Here is the completed hello world program:
Step 5: running the hello world program
To run this program within Eclipse, I use the run menu, accessed from the button showing a white triangle on a green
circle. Since I haven't run any code yet, I have to tell Eclipse what program to run. Click on the drop-down menu to the
right of the run button, and tell Eclipse to run HelloRDFWorld as a Java application:
Which gives the following output in the Eclipse console:
And that's it: from empty Eclipse to a working RDF hello-world application. Obviously there is lot's more to learn (see the
tutorial links at the top for some jumping-off points), but hopefully you can now have fun developing new semantic web
applications!