Author: Reto Bachmann-Gmür and Tsuyoshi Ito - clerezza.org
Contributor: Hasan - clerezza.org
3. Creating an accessible service
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.
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.
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
To build the package, execute the command:
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.
Open the URL http://localhost:8080/foaf/find and add the URL parameter mbox=mailto:john@example.org
to receive information about john
[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!