Tutorial 2: Developing RDF backed RESTful applications
Author: Reto Bachmann-Gmür and Tsuyoshi Ito - clerezza.org
Contributor: Hasan - clerezza.org
Table of Contents
3. Creating an accessible service
1. Introduction
REST [1] is a software architecture style applicable to the World Wide Web. With the advent of the Semantic Web this resource oriented design shows its strength. The web of documents evolves seamlessly to a web of data and knowledge.
RESTful Web applications are designed based on a set of REST principles. In this introductory tutorial you'll learn how to develop a RESTful application that delivers human readable semantic content which is stored in a triple store.
Therefore, you will learn about SCB [2] and Triaxrs [3] and how to use them to develop an RDF-backed RESTful Web application. The time it takes to go through this tutorial is around 30 minutes.
2. Setting up the project
Create a maven project with the following parent and dependencies (see the Triaxrs Tutorial 1 (Developing a RESTful Web Application for OSGi Runtime Environment) for more detail [4]):
First configure the repositories as follows:
It in not necessary to define the version parameter of each dependency because they are specified in the parents pom file.
Also set packaging to bundle
By default the maven-bundle-plugin will export the
package named <groupId>.<artifactId> and its subpackages,
so the exposed components must be defined in a package named that way.
In our example we use org.example.clerezza as
groupId and combined.tutorial as artifactId.
3. Creating an accessible service
Like in the Triaxrs Tutorial 1 [4] we create a JAX-RS class to get information about persons. To have some data to play with, we will add an RDF file encoded in the Turtle format into the resource tree of our project. Thus, we create the file src/main/resources/org/example/clerezza/combined/tutorial/data.turtle with the following content:
The JAX-RS resource class mentioned above is called in this tutorial
TutorialApp and looks as follows:
The resource class above provides two resource methods to process
GET requests specifying the path /foaf/find. The JAX-RS annotation
@Path on TutorialApp sets the path of the resource to “/foaf”,
while the JAX-RS annotation @Path on the resource methods
getPersonRdf and getPersonHtml defines
the subpath "find". Furthermore, the JAX-RS annotation @Produces
defines the list of media types that a Java type or a method
can produce. A media type corresponds with the representation of a
resource. In this tutorial getPersonRdf should produce
"application/rdf+xml", whereas getPersonHtml should
produce "application/xhtml+xml". Both methods accept a parameter,
whose value is obtained from the GET request parameter called mbox.
This is defined through the JAX-RS annotation @QueryParam.
A resource can have multiple representations. For example, a web page
can be represented as html, pdf, plain text, or other representations.
The HTTP defines a mechanism known as content negotiation to allow a
client (e.g., a web browser) to specify which representation it would
like to get from the server. Using JAX-RS we can define a
MessageBodyWriter which maps a Java type to a
representation. In this tutorial getPersonRdf returns
a Graph, whereas getPersonHtml returns a GraphNode,
which represents a node in the context of a graph. The clerezza
platform provides for either resources Graph and GraphNode a
corresponding MessageBodyWriter.
The clerezza platform's TemplatingMessageBodyWriter
produces a representation of the format "application/xhtml+xml"
from a GraphNode, whereas the GraphWriter
produces "application/rdf+xml" from a Graph.
GraphWriter is implemented in the maven project
org.clerezza.jaxrs.rdf.providers.
The TemplatingMessageBodyWriter uses a templating engine
to render a GraphNode based on a predefined template file.
In order to allow a different GraphNode to be rendered
using a different template, each GraphNode and template
is bound to a specific RDF type.
For the purpose of registering a template, a
RenderletManager service is made available. In this tutorial,
a template (obtained from the file "tutorial.xhtml") is registered
for the RDF type FOAF.Person (http://xmlns.com/foaf/0.1/Person).
This is done in the activate method using the
RenderletManager service.
In the activate method we also use the TcManager to get
the MGraph called "http://localhost.mygraph". If this
graph doesn't exist, a NoSuchEntityException is thrown.
In this latter case, we catch this exception and create an
MGraph. Afterwards we add the triples from the file
mentioned above into the graph.
The following template renders a FOAF.Person. For easier readability
namespaces can be defined. Statements which should be interpreted by
the templating engine starts with the character $.
The templating language allows loops and conditions. More examples
are available on the project website of the templating engine
(http://clerezza.org/projects/org.clerezza.templating.seedsnipe/documentation/overview.xhtml
4. Build
To build the package, execute the command:
5. Installing the bundle in the Clerezza Platform
Download the latest clerezza platform launcher from http://repo.trialox.org/snapshot/org/clerezza/org.clerezza.platform.launcher.sesame/ and start it. Go to http://localhost:8080/user/admin/control-panel (enter username: admin, password; admin) and upload your bundle.
Test your bundle
Open the URL http://localhost:8080/foaf/find and add the URL parameter mbox=mailto:john@example.org to receive information about john
References
[1] R.T. Fielding: Architectural Styles and the Design of Network-based Software Architectures; CHAPTER 5 Representational State Transfer (REST), 2000, http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
[2] Clerezza Smart Content Binding SCB http://clerezza.org/projects/org.clerezza.rdf.core/
[3] Clerezza Triaxrshttp://clerezza.org/projects/org.clerezza.triaxrs/
[4] Clerezza Triaxrs Tutorial 1http://clerezza.org/projects/org.clerezza.triaxrs/documentation/tutorial_1.xhtml
That's all folks for this time!
Copyright (c) 2008-2009 trialox.org (trialox AG, Switzerland)