Author: ito
Date: Tue Dec 15 15:56:47 2009
New Revision: 890847
URL: http://svn.apache.org/viewvc?rev=890847&view=rev
Log:
CLEREZZA-35: x-site renaming problems fixed
Added:
incubator/clerezza/issues/CLEREZZA-35/
incubator/clerezza/issues/CLEREZZA-35/org.apache.clerezza.rdf.core/
- copied from r890755,
incubator/clerezza/trunk/org.apache.clerezza.parent/org.apache.clerezza.rdf.core/
Modified:
incubator/clerezza/issues/CLEREZZA-35/org.apache.clerezza.rdf.core/src/site/xsite/content/scb-triaxrs-tutorial.xhtml
incubator/clerezza/issues/CLEREZZA-35/org.apache.clerezza.rdf.core/src/site/xsite/content/tutorial_1.xhtml
Modified:
incubator/clerezza/issues/CLEREZZA-35/org.apache.clerezza.rdf.core/src/site/xsite/content/scb-triaxrs-tutorial.xhtml
URL:
http://svn.apache.org/viewvc/incubator/clerezza/issues/CLEREZZA-35/org.apache.clerezza.rdf.core/src/site/xsite/content/scb-triaxrs-tutorial.xhtml?rev=890847&r1=890755&r2=890847&view=diff
==============================================================================
---
incubator/clerezza/issues/CLEREZZA-35/org.apache.clerezza.rdf.core/src/site/xsite/content/scb-triaxrs-tutorial.xhtml
(original)
+++
incubator/clerezza/issues/CLEREZZA-35/org.apache.clerezza.rdf.core/src/site/xsite/content/scb-triaxrs-tutorial.xhtml
Tue Dec 15 15:56:47 2009
@@ -18,6 +18,367 @@
* specific language governing permissions and limitations
* under the License.
*/
---></i></p>
+-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en-us">
+ <head>
+ <title>Tutorial 2: Developing RDF backed RESTful
applicationts</title>
+ <link rel="stylesheet" type="text/css"
href="style/documentation.css"/>
+ </head>
+ <body>
+ <h1>Tutorial 2: Developing RDF backed RESTful applications</h1>
+ <p>Author: Reto Bachmann-Gmür and Tsuyoshi Ito -
clerezza.org</p>
+ <p>Contributor: Hasan - clerezza.org</p>
+ <h2>Table of Contents</h2>
+ <p>
+ <a href="#introduction">1. Introduction</a>
+ </p>
+ <p>
+ <a href="#setting">2. Setting up the project</a>
+ </p>
+ <p>
+ <a href="#accessible">3. Creating an accessible
service</a>
+ </p>
+ <p>
+ <a href="#build">4. Build</a>
+ </p>
+ <p>
+ <a href="#install">5. Installing the bundle</a>
+ </p>
+ <p>
+ <a href="#test">5. Test your bundle</a>
+ </p>
+ <p>
+ <a href="#references">6. References</a>
+ </p>
+ <h2 id="introduction">1. Introduction</h2>
+ <p>
+ REST [<a href="#ref1">1</a>] 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.
+ </p>
+ <p>
+ 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.
+ </p>
+ <p>
+ Therefore, you will learn about SCB [<a
href="#ref2">2</a>] and Triaxrs
+ [<a href="#ref3">3</a>] 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.
+ </p>
+ <h2 id="setting">2. Setting up the project</h2>
+ <p>
+ 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 [<a
href="#ref4">4</a>]):
+ </p>
+
+ <p>First configure the repositories as follows:</p>
+ <blockcode>
+<repositories>
+ <repository>
+ <id>clerezza-release</id>
+ <name>clerezza.org distribution repository</name>
+ <url>http://repo.trialox.org/release</url>
+ <layout>default</layout>
+ </repository>
+ <repository>
+ <id>clerezza-snapshot</id>
+ <name>clerezza.org snapshot repository</name>
+ <url>http://repo.trialox.org/snapshot</url>
+ <layout>default</layout>
+ </repository>
+</repositories>
+ </blockcode>
+ <blockcode>
+<parent>
+ <artifactId>org.clerezza.parent</artifactId>
+ <groupId>org.clerezza</groupId>
+ <version>0.11-SNAPSHOT</version> //check <a
href="http://repo.trialox.org/release/org/clerezza/org.clerezza.parent/";>here</a>
for the newest release version or
+ <a
href="http://repo.trialox.org/snapshot/org/clerezza/org.clerezza.parent/";>here</a>
for newest snapshot version</parent> </blockcode>
+ <p>It in not necessary to define the <code>version</code> parameter of
each dependency because they are specified in the parents pom file.</p>
+ <blockcode>
+<dependency>
+ <groupId>org.clerezza</groupId>
+ <artifactId>org.clerezza.jaxrs.rdf.providers</artifactId>
+</dependency>
+<dependency>
+ <groupId>org.clerezza</groupId>
+
<artifactId>org.clerezza.platform.typerendering.seedsnipe</artifactId>
+</dependency>
+<dependency>
+ <groupId>org.clerezza</groupId>
+ <artifactId>org.clerezza.triaxrs</artifactId>
+</dependency>
+ </blockcode>
+ <p>Also set packaging to <code>bundle</code></p>
+ <p class="note">
+ By default the <code>maven-bundle-plugin</code> 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 <code>org.example.clerezza</code>
as
+ groupId and <code>combined.tutorial</code> as
artifactId.
+ </p>
+
+ <h2 id="accessible">3. Creating an accessible service</h2>
+ <p>
+ Like in the Triaxrs Tutorial 1 [<a href="#ref4">4</a>]
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:</p>
+ <blockcode>
+...@prefix foaf: <http://xmlns.com/foaf/0.1/>.
+
+[ a foaf:Person;
+ foaf:title "Mr";
+ foaf:name "John Doe";
+ foaf:mbox <mailto:[email protected]>;
+ foaf:topic_interest
<http://dbpedia.org/resource/Category:BBC_television_sitcoms>;
+ foaf:nick "jo" ] .
+
+[ a foaf:Person;
+ foaf:title "Mrs";
+ foaf:name "Jane Bloggs";
+ foaf:mbox <mailto:[email protected]>;
+ foaf:openid <http://openid.example.org/jbloggs> ] .
+ </blockcode>
+
+ <p>
+ The JAX-RS resource class mentioned above is called in
this tutorial
+ <code>TutorialApp</code> and looks as follows:
+ </p>
+ <blockcode>
+package org.example.clerezza.combined.tutorial;
+
+import java.io.InputStream;
+import java.net.URISyntaxException;
+import java.net.URL;
+import java.util.Iterator;
+
+import javax.ws.rs.GET;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+import javax.ws.rs.WebApplicationException;
+import javax.ws.rs.core.MediaType;
+
+import org.osgi.service.component.ComponentContext;
+
+import org.clerezza.platform.typerendering.seedsnipe.SeedsnipeRenderlet;
+import org.clerezza.platform.typerendering.RenderletManager;
+import org.clerezza.rdf.ontologies.FOAF;
+import org.clerezza.rdf.utils.GraphNode;
+import org.clerezza.rdf.core.Graph;
+import org.clerezza.rdf.core.MGraph;
+import org.clerezza.rdf.core.NonLiteral;
+import org.clerezza.rdf.core.Triple;
+import org.clerezza.rdf.core.TripleCollection;
+import org.clerezza.rdf.core.UriRef;
+import org.clerezza.rdf.core.access.NoSuchEntityException;
+import org.clerezza.rdf.core.access.TcManager;
+import org.clerezza.rdf.core.serializedform.Parser;
+
+/**
+ * Get Persons by their email
+ *
+ * @scr.component
+ * @scr.service interface="java.lang.Object"
+ * @scr.property name="javax.ws.rs" type="Boolean" value="true"
+ */
+
+...@path("/foaf")
+public class TutorialApp {
+
+ /**
+ * @scr.reference
+ */
+ TcManager tcManager;
+
+ /**
+ * @scr.reference
+ */
+ private RenderletManager renderletManager;
+
+ private UriRef graphName = new UriRef("http://localhost.mygraph";);
+
+ @GET
+ @Path("find")
+ @Produces("application/rdf+xml")
+ public Graph getPersonRdf(@QueryParam("mbox") String mboxString) {
+ MGraph mGraph = tcManager.getMGraph(graphName);
+ NonLiteral person = getPersonByMbox(mboxString, mGraph);
+ return new GraphNode(person, mGraph).getNodeContext();
+ }
+
+ @GET
+ @Path("find")
+ @Produces("application/xhtml+xml")
+ public GraphNode getPersonHtml(@QueryParam("mbox") String mboxString) {
+ MGraph mGraph = tcManager.getMGraph(graphName);
+ NonLiteral person = getPersonByMbox(mboxString, mGraph);
+ return new GraphNode(person, mGraph);
+ }
+
+ private NonLiteral getPersonByMbox(String mboxString, MGraph mGraph) {
+ Iterator<Triple> iter = mGraph.filter(null, FOAF.mbox,
new UriRef(mboxString));
+ NonLiteral person = null;
+ while(iter.hasNext()) {
+ person = iter.next().getSubject();
+ }
+ return person;
+ }
+
+ /**
+ * The activate method is called when SCR activates the component
configuration.
+ * This method gets the system graph or create a new one if it doesn't
exist.
+ *
+ * @param componentContext
+ */
+ protected void activate(ComponentContext componentContext) {
+
+ URL templateURL = getClass().getResource("tutorial.xhtml");
+ try {
+
renderletManager.registerRenderlet(SeedsnipeRenderlet.class
+ .getName(), new
UriRef(templateURL.toURI().toString()),
+ FOAF.Person, null,
MediaType.APPLICATION_XHTML_XML_TYPE,
+ true);
+ } catch (URISyntaxException ex) {
+ throw new WebApplicationException(ex);
+ }
+ TripleCollection tc;
+ try {
+ tcManager.getMGraph(graphName);
+ } catch (NoSuchEntityException nsee) {
+ tc = tcManager.createMGraph(graphName);
+ InputStream fin = null;
+ fin = getClass().getResourceAsStream("data.turtle");
+ Parser parser = Parser.getInstance();
+ tc.addAll(parser.parse(fin, "text/turtle"));
+ }
+ }
+}
+
+ </blockcode>
+ <p>
+ 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
+ <code>getPersonRdf</code> and
<code>getPersonHtml</code> 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 <code>getPersonRdf</code>
should produce
+ "application/rdf+xml", whereas
<code>getPersonHtml</code> 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.
+ </p>
+ <p>
+ 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
+ <code>MessageBodyWriter</code> which maps a Java type
to a
+ representation. In this tutorial
<code>getPersonRdf</code> returns
+ a Graph, whereas <code>getPersonHtml</code> 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 <code>MessageBodyWriter</code>.
+ </p>
+ <p>
+ The clerezza platform's
<code>TemplatingMessageBodyWriter</code>
+ produces a representation of the format
"application/xhtml+xml"
+ from a <code>GraphNode</code>, whereas the
<code>GraphWriter</code>
+ produces "application/rdf+xml" from a
<code>Graph</code>.
+ <code>GraphWriter</code> is implemented in the maven
project
+ org.clerezza.jaxrs.rdf.providers.
+ The <code>TemplatingMessageBodyWriter</code> uses a
templating engine
+ to render a <code>GraphNode</code> based on a
predefined template file.
+ In order to allow a different <code>GraphNode</code> to
be rendered
+ using a different template, each <code>GraphNode</code>
and template
+ is bound to a specific RDF type.
+ </p>
+ <p>
+ For the purpose of registering a template, a
+ <code>RenderletManager</code> 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 <code>activate</code> method using
the
+ <code>RenderletManager</code> service.
+ </p>
+ <p>
+ In the <code>activate</code> method we also use the
<code>TcManager</code> to get
+ the <code>MGraph</code> called
"http://localhost.mygraph";. If this
+ graph doesn't exist, a
<code>NoSuchEntityException</code> is thrown.
+ In this latter case, we catch this exception and create
an
+ <code>MGraph</code>. Afterwards we add the triples from
the file
+ mentioned above into the graph.
+ </p>
+
+ <p>
+ 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
<code>$</code>.
+ The templating language allows loops and conditions.
More examples
+ are available on the project website of the templating
engine
+ (<a
href="http://clerezza.org/projects/org.clerezza.templating.seedsnipe/documentation/overview.xhtml";
target="_blank"
>http://clerezza.org/projects/org.clerezza.templating.seedsnipe/documentation/overview.xhtml</a>
+ </p>
+ <blockcode>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
+<head>
+ ${ns:foaf=http://xmlns.com/foaf/0.1/}
+ <meta http-equiv="Content-Type" content="text/html;
charset=UTF-8"/>
+ <title>clerezza - Combined Tutorial</title>
+</head>
+<body>
+ <h1>clerezza - Combined Tutorial</h1>
+ <h2>FOAF Person:</h2>
+ <div>
+ <p>Name: ${foaf:title} ${foaf:name}</p>
+ <p>Email: ${foaf:mbox}</p>
+ ${if foaf:nick}
+ <p>Nickname: ${foaf:nick}</p>
+ ${/if}
+ <p>Topic interests: <br />
+ ${loop}
+ ${foaf:topic_interest}<br />
+ ${/loop}
+ </p>
+ </div>
+</body>
+</html>
+ </blockcode>
+ <h2 id="build">4. Build</h2>
+ <p>To build the package, execute the command:
+ </p>
+ <blockcode>
+ $ mvn package
+ </blockcode>
+
+ <h2 id="install">5. Installing the bundle in the Clerezza
Platform</h2>
+ <p>
+ Download the latest clerezza platform launcher from
+ <a
href="http://repo.trialox.org/snapshot/org/clerezza/org.clerezza.platform.launcher.sesame/";
target="_blank" >
+
http://repo.trialox.org/snapshot/org/clerezza/org.clerezza.platform.launcher.sesame/</a>
and start it.
+ Go to <a
href="http://localhost:8080/user/admin/control-panel"; target="_blank"
>http://localhost:8080/user/admin/control-panel</a> (enter username: admin,
password; admin) and upload your bundle.
+ </p>
+ <h2 id="test">Test your bundle</h2>
+ <p>Open the URL <a
href="http://localhost:8080/foaf/find";>http://localhost:8080/foaf/find</a> and
add the URL parameter <code>mbox=mailto:[email protected]</code> to receive
information about john</p>
+ <h2 id="references">References</h2>
+ <p id="ref1">[1] R.T. Fielding: Architectural Styles and the
Design of Network-based Software Architectures; CHAPTER 5 Representational
State Transfer (REST), 2000, <a
href="http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm";>http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm</a></p>
+ <p id="ref2">[2] Clerezza Smart Content Binding SCB <a
href="http://clerezza.org/projects/org.clerezza.rdf.core/";>http://clerezza.org/projects/org.clerezza.rdf.core/</a></p>
+ <p id="ref3">[3] Clerezza Triaxrs<a
href="http://clerezza.org/projects/org.clerezza.triaxrs/";>http://clerezza.org/projects/org.clerezza.triaxrs/</a></p>
+ <p id="ref4">[4] Clerezza Triaxrs Tutorial 1<a
href="http://clerezza.org/projects/org.clerezza.triaxrs/documentation/tutorial_1.xhtml";>http://clerezza.org/projects/org.clerezza.triaxrs/documentation/tutorial_1.xhtml</a></p>
+ <p><i>That's all folks for this time! <br/><!--You can send
your feedback to: --></i></p>
</body>
</html>
Modified:
incubator/clerezza/issues/CLEREZZA-35/org.apache.clerezza.rdf.core/src/site/xsite/content/tutorial_1.xhtml
URL:
http://svn.apache.org/viewvc/incubator/clerezza/issues/CLEREZZA-35/org.apache.clerezza.rdf.core/src/site/xsite/content/tutorial_1.xhtml?rev=890847&r1=890755&r2=890847&view=diff
==============================================================================
---
incubator/clerezza/issues/CLEREZZA-35/org.apache.clerezza.rdf.core/src/site/xsite/content/tutorial_1.xhtml
(original)
+++
incubator/clerezza/issues/CLEREZZA-35/org.apache.clerezza.rdf.core/src/site/xsite/content/tutorial_1.xhtml
Tue Dec 15 15:56:47 2009
@@ -19,6 +19,432 @@
* under the License.
*/
-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en-us">
+ <head>
+ <title>Tutorial 1: Exploring and aggregating RDF data with
SCB</title>
+ <link rel="stylesheet" type="text/css"
href="style/documentation.css"/>
+ </head>
+ <body>
+ <h1>Tutorial 1: Exploring and aggregating RDF data with SCB</h1>
+ <p>Author: Reto Bachmann-Gmür - clerezza.org</p>
+ <p>Contributor: Hasan - clerezza.org</p>
+ <p>Date: 2009-01-25</p>
+ <h2>Table of Contents</h2>
+ <p>
+ <a href="#objective">1. Objective</a>
+ </p>
+ <p>
+ <a href="#maven">2. Initializing a Maven Project</a>
+ </p>
+ <p>
+ <a href="#functionality">3. Creating a Graph and
loading Data</a>
+ </p>
+ <p>
+ <a href="#accessing">4. Accessing the Triples</a>
+ </p>
+ <p>
+ <a href="#context">5. Resource context</a>
+ </p>
+ <p>
+ <a href="#example">6. Putting it all together: the
example app</a>
+ </p>
+ <p>
+ <a href="#further">7. Taking it further</a>
+ </p>
+ <p>
+ <a href="#references">8. References</a>
+ </p>
+ <h2 id="objective">1. Objective</h2>
+ <p>
+ In this tutorial you will learn how to use SCB to
manage data modeled
+ as a graph based on the RDF [<a href="#ref1">1</a>]
standard
+ maintained by W3C.
+ </p>
+ <p>
+ You'll learn how to get Graph objects from serialized
RDF data on
+ the web and how to access such a graph using the core
SCB package
+ and the SCB utilities package.
+ </p>
+ <p>
+ Key advantages of SCB include the support of OSGi [<a
href="#ref2">2</a>]
+ to allow for a better modularization of application and
the support of
+ other triple store APIs through technology specific
façades (adapters).
+ However, you will learn to know these key advantages in
next tutorials. This
+ tutorial provides for a good foundation to work with
and understand
+ the basic concept of SCB graph data model.
+ </p>
+ <p>
+ Our example will download data about BBC television
sitcoms from
+ dbpedia into a local graph, display the context of a
given resource
+ and download additional data from the web when the user
requests it.
+ The time it takes to go through this tutorial is
approximately an hour. This
+ tutorial is intended for java developers, some
familiarity with the
+ build tool maven [<a href="#ref3">3</a>] is an
advantage.
+ </p>
+ <h2 id="maven">2. Setting up the Maven project</h2>
+ <p>
+ We use maven to build our project and to keep track of
dependencies
+ in an IDE independent way. Maven will take care of
downloading the
+ required dependencies from their respective
repositories.
+ </p>
+ <h3 id="initialization">2.1. Initializing</h3>
+ <p>
+ First, a maven project with the groupId
org.example.clerezza.scb
+ and the artifactId tutorial1 will be created by
executing the
+ following command in a shell:
+ </p>
+ <!-- blockcode not yet supported in XHTML 1.1, squatting from
XHTML 2.0 -->
+ <blockcode>
+$ mvn archetype:generate --batch-mode \
+-DarchetypeGroupId=org.apache.maven.archetypes \
+-DarchetypeArtifactId=maven-archetype-quickstart \
+-DgroupId=org.example.clerezza.scb \
+-DartifactId=tutorial1 \
+-Dversion=1.0-SNAPSHOT \
+-Dpackage=org.example.clerezza.scb.tutorial1
+ </blockcode>
+ <p>
+ If all goes well the output output of the command
contains the
+ following:
+ </p>
+ <blockcode>
+------------------------------------------------------------------------
+[INFO] BUILD SUCCESSFUL
+[INFO]
+------------------------------------------------------------------------
+ </blockcode>
+
+ <p>
+ A new directory called tutorial1 is created containing
a source
+ directory src and a file called pom.xml used by maven
to build the
+ project. A program file called App.java is created and
placed under
+ the directory
src/main/java/org/example/clerezza/scb/tutorial1/, we
+ will modify this Class to build our demo application,
but before we
+ add the required dependencies to our pom.xml.
+ </p>
+
+ <h3 id="dependencies">2.2. Adding dependencies</h3>
+ <p>
+ As the required Clerezza artifacts are not yet in the
maven default
+ repositories we need to add the respective repository
locations to
+ our pom.xml (alternatively we could add them globally
+ to the maven settings.xml). Add the following as a
child element of
+ <code>project</code> in your pom.xml:
+ </p>
+ <blockcode>
+<repositories>
+ <repository>
+ <id>clerezza-release</id>
+ <name>clerezza.org distribution repository</name>
+ <url>http://repo.trialox.org/release</url>
+ <layout>default</layout>
+ </repository>
+ <repository>
+ <id>clerezza-snapshot</id>
+ <name>clerezza.org snapshot repository</name>
+ <url>http://repo.trialox.org/snapshot</url>
+ <layout>default</layout>
+ </repository>
+</repositories>
+ </blockcode>
+
+ <p>
+ Now we can add the dependencies to the
<code>dependencies</code>
+ section that maven will download from the clerezza
repositories.
+ </p>
+ <p>
+ The following are the compile-time dependencies (the
default scope
+ for dependencies is <code>compile</code>). Beside
+ <code>org.clerezza.rdf.core</code> which provides the
core scb bundles
+ we add <code>org.clerezza.rdf.utils</code> that
contains handy utility
+ classes and <code>org.clerezza.rdf.ontologies</code>
which contains
+ classes containing constants for the terms of popular
ontologies.
+ </p>
+ <blockcode>
+<dependency>
+ <groupId>org.clerezza</groupId>
+ <artifactId>org.clerezza.rdf.core</artifactId>
+ <version>0.5-SNAPSHOT</version>
+</dependency>
+<dependency>
+ <groupId>org.clerezza</groupId>
+ <artifactId>org.clerezza.rdf.utils</artifactId>
+ <version>0.5-SNAPSHOT</version>
+</dependency>
+<dependency>
+ <groupId>org.clerezza</groupId>
+ <artifactId>org.clerezza.rdf.ontologies</artifactId>
+ <version>0.3-SNAPSHOT</version>
+</dependency>
+ </blockcode>
+
+ <p class="note">
+ The set version numbers were the latest at time of
writing to
+ find the latest release or snapshot version check
+ http://repo.trialox.org/release/org/clerezza/
+ respectively
http://repo.trialox.org/snapshot/org/clerezza/.
+ </p>
+
+ <p>
+ The above dependencies will be sufficient to compile
our application,
+ to run the application. However as SCB provides mainly
interfaces
+ to exchangeable implementations we should add some
runtime dependencies:
+ </p>
+ <div class="note">
+ At the time of writing this a bug in the maven
exec-plugin prevents us
+ from declaring these dependencies as what they actually
are, so
+ the runtime scope is commented out.
+ </div>
+ <blockcode>
+<dependency>
+ <groupId>org.clerezza</groupId>
+ <artifactId>org.clerezza.rdf.jena.parser</artifactId>
+ <version>0.2-SNAPSHOT</version>
+ <!-- <scope>runtime</scope> -->
+</dependency>
+<dependency>
+ <groupId>org.clerezza</groupId>
+ <artifactId>org.clerezza.rdf.jena.serializer</artifactId>
+ <version>0.2-SNAPSHOT</version>
+ <!-- <scope>runtime</scope> -->
+</dependency>
+<dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-simple</artifactId>
+ <version>1.5.5</version>
+ <!-- <scope>runtime</scope> -->
+</dependency>
+<dependency>
+ <groupId>org.clerezza</groupId>
+ <artifactId>org.clerezza.rdf.simple.storage</artifactId>
+ <version>0.2-SNAPSHOT</version>
+ <!-- <scope>runtime</scope> -->
+</dependency>
+ </blockcode>
+
+ <p>
+ The two dependencies are implementations of rdf parsers
and
+ serializers for various formats. They are based on the
Jena Framework
+ [<a href="#ref4">4</a>] but you don't have to care
about this.
+ </p>
+
+ <p>
+ Almost forgot, maven defaults to some rather old java
version, to fix
+ this we should add the following to configure the
+ <code>maven-compiler-plugin</code> to use java 6, the
+ <code>build</code> element is a child of
<code>project</code>.
+ </p>
+ <blockcode>
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <source>1.6</source>
+ <target>1.6</target>
+ </configuration>
+ </plugin>
+ </plugins>
+</build>
+ </blockcode>
+
+
+ <p>
+ Enough configuration, lets get our hands dirty and
write some code.
+ </p>
+
+ <h2 id="functionality">3. Creating a Graph and loading Data</h2>
+ <p>
+ In RDF Graphs are collections of triples, strictly
speaking graphs
+ are immutable, if you add or remove a triple its a new
graph. For
+ that SCB distinguishes between two types of
+ <code>TripleCollection</code>s: <code>Graph</code> and
+ <code>MGraph</code> where 'M' stands for "mutable". The
MGraph
+ and Graph interfaces both extend
<code>TripleCollection</code> which
+ apart from extending
<code>java.util.Collection<Triple></code>
+ provide a method <code>filter</code>
+ to query RDF triples according to filter parameters
+ specified: subject, predicate, and object.
+ </p>
+ <p>
+ The factory we need for getting
<code>TripleCollection</code>s
+ is <code>
+ <a
href="http://clerezza.org/projects/org.clerezza.rdf.core/apidocs/org/clerezza/rdf/core/access/TcManager.html";>
+ TcManager
+ </a></code>, depending on the available
+ storage providers the returned instances may be backed
on an efficient
+ triple store like Sesame, or if no provider is
available a simple and
+ terribly inefficient HashSet based implementation is
returned.
+ </p>
+ <p>
+ To store our accumulated knowledge around BBC
television sitcoms
+ we create an <code>MGraph</code> with the following
code:
+ </p>
+ <blockcode>
+import org.clerezza.rdf.core.*;
+import org.clerezza.rdf.core.access.TcManager;
+
+...
+
+//get the singleton instance of TcManager
+final TcManager tcManager = TcManager.getInstance();
+//the arbitrary name we use for our mutable graph
+final UriRef mGraphName = new UriRef("http://tutorial.example.org/";);
+//the m-graph into which we'll put the triples we collect
+final MGraph mGraph = tcManager.createMGraph(mGraphName);
+ </blockcode>
+ <div class="note">
+ We don't repeat the skeleton code generated by the
maven archetype
+ but trust the reader can add the statements above at a
sensible
+ place in App.java.
+ </div>
+ <p>
+ The code creates an empty MGraph with the name
+ <http://tutorial.example.org/>. To verify that all
went well
+ we can output the size of <code>mGraph</code> with the
following:
+ </p>
+ <blockcode>
+System.out.println("Size of mGraph: "+mGraph.size());
+ </blockcode>
+ <p>
+ To compile and run the application using maven issue
the following
+ command in the directory where the pom.xml is:
+ </p>
+ <blockcode>
+$ mvn compile exec:java -Dexec.mainClass=org.example.clerezza.scb.tutorial1.App
+ </blockcode>
+ <p>
+ The actual program output will be armored by the maven
logging, you
+ may pass the -q argument, and you'll only see the
actual output of our
+ program:
+ </p>
+ <blockcode>
+Size of mGraph: 0
+ </blockcode>
+ <p>
+ Boring emptiness, lets add the triples dbpedia has about
+
<http://dbpedia.org/resource/Category:BBC_television_sitcoms>. First
+ use standard classes from the java.net package to
dereference this
+ URI.
+ </p>
+ <blockcode>
+final URL url = new
URL("http://dbpedia.org/resource/Category:BBC_television_sitcoms";);
+final URLConnection con = url.openConnection();
+con.addRequestProperty("Accept", "application/rdf+xml");
+final InputStream inputStream = con.getInputStream();
+ </blockcode>
+ <div class="note">
+ The above code sets the "Accept"-Header of the
HTTP-Request to
+ "application/rdf+xml" this tells the server that we can
handle
+ responses in that format, for comparison the value of
the
+ Accept-Header in the request of a browser might look
like
+
"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8".<br/>
+ The URI
<http://dbpedia.org/resource/Category:BBC_television_sitcoms>
+ represents the abstract notion (the category) of BBC
television sitcoms
+ which is not something that can actually be passed over
the wire,
+ the server will answer with "303 See Other" response
pointing to a
+ document describing the category we originally
requested, in our case
+ this is
<http://dbpedia.org/data/Category:BBC_television_sitcoms.rdf>
+ for a normal browser it would be
+
<http://dbpedia.org/page/Category:BBC_television_sitcoms>. URLConnection
+ transparently handles this redirection so we don't have
to care
+ about sending the second request to the server.
+ </div>
+ <p>
+ Now that we have an InputStream from which rdf/xml can
be read we
+ use
<code>org.clerezza.rdf.core.serializedform.Parser</code> to
+ convert it to a graph:
+ </p>
+ <blockcode>
+//get the singleton instance of Parser
+final Parser parser = Parser.getInstance();
+Graph deserializedGraph = parser.parse(inputStream, "application/rdf+xml");
+ </blockcode>
+ <p>
+ Using the <code>addAll</code> which MGraph inherits from
+ <code>Collection<triple></code> we can add the
triples of the
+ retrieved Graph to mGraph:
+ </p>
+ <blockcode>
+mGraph.addAll(deserializedGraph);
+ </blockcode>
+ <p>
+ Outputting the size of the graph now returns something
else (the
+ number of triples will vary as dbpedia evolves):
+ </p>
+ <blockcode>
+Size of mGraph: 251
+ </blockcode>
+ <h2 id="accessing">4. Accessing the Triples</h2>
+ <p>
+ It's good to know that by loading data into our
<code>MGraph</code>
+ its size has increased, but actually we would like to
get data
+ out of <code>mGraph</code>. The easiest would be to
just use
+ the Serializer to write the Graph to standard output:
+ </p>
+ <blockcode>
+final Serializer serializer = Serializer.getInstance();
+serializer.serialize(System.out, mGraph, "text/turtle");
+ </blockcode>
+ <p>The above code serialized <code>mGraph</code> in the turtle
format
+ to the standard output. You may want to try "text/rdf+nt" and
+ "application/rdf+xml" to see the triples serialized in
different ways.
+ </p>
+ <p>The typical way to get specific triples is to use the
<code>filter</code>
+ method which <code>Graph</code> and <code>MGraph</code> inherit
from
+ <code>TripleCollection</code>. The following outputs the
+ <code>RDF:type</code> of the resource
+
<http://dbpedia.org/resource/Category:BBC_television_sitcoms>:</p>
+ <blockcode>
+Iterator<Triple> typeTriples = mGraph.filter(new
UriRef("http://dbpedia.org/resource/Category:BBC_television_sitcoms";),
RDF.type, null);
+while (typeTriples.hasNext()) {
+ System.out.println(typeTriples.next());
+}
+ </blockcode>
+ <p>Note the use of <code>RDF.type</code> a constant from the
+ org.clerezza.rdf.ontologies package and maven artifact,
<code>null</code>
+ is used as a wild card, here in the object position</p>
+ <h2 id="context">5. Resource context</h2>
+ <p>Often we want to get a concise description of a resource,
the context
+ of a resource. In terms of RDF this can be formalized "context"
as the set of
+ statements in which the resource is either subject or object.
If such a
+ statement contains a blank node its context is included as well
+ [<a href="#ref5">5</a>].</p>
+ <p>The context can easily be accessed by using the
<code>GraphNode</code>
+ class in the org.clerezza.rdf.utils package.</p>
+ <blockcode>
+public Graph getCurrentContext() {
+ return new GraphNode(new UriRef(selectedUri), mGraph).getNodeContext();
+}
+ </blockcode>
+ <p>The method above returns the context of the resource of which
+ <code>selectedUri</code> contains the name.</p>
+ <h2 id="example">6. Putting it all together: the example
app</h2>
+ <p>Putting what we learned together and adding a swing
front-end:</p>
+ <p>The <a
href="http://clerezza.org/projects/org.clerezza.rdf.core/documentation/tutorial1/pom.xml";>pom.xml</a>
should be equivalent to
+ what you already have if you followed this tutorial, the
+ <a
href="http://clerezza.org/projects/org.clerezza.rdf.core/documentation/tutorial1/src/main/java/org/example/clerezza/scb/tutorial1/Tutorial1App.java";>
+ java code</a> creates a swing frame with a table containing the
context
+ of a selected resource. By default, when clicking on a named
resource that
+ is the subject or object of a statement, the context of this
resource is
+ shown. By clicking on the button "Loadre Context from Web" the
resource
+ is dereferenced and the triples are added to the local
store.</p>
+ <h2 id="further">7. Taking it further</h2>
+ <p>A trivially achievable improvement of the example
application would
+ be to add persistent storage.</p>
+ <p>By adding the sesame persitent storage provider to the
runtime classpath
+ of the application our <code>MGraph</code> is stored in a
sesame store
+ [<a href="#ref8">8</a>] (this obsolotes the dependency on
+ <code>org.clerezza.rdf.sesame.storage</code>).
+ </p>
+ <blockcode>
+<dependency>
+ <groupId>org.clerezza</groupId>
+ <artifactId>org.clerezza.rdf.sesame.storage</artifactId>
+ <version>0.7-SNAPSHOT</version>
+ <!-- <scope>runtime</scope> -->
</dependency>
</blockcode>
<p>After adding this dependency on the second launch of the
application
@@ -33,9 +459,9 @@
mGraph = tcManager.createMGraph(mGraphName);
}
</blockcode>
- <p>If anything is unclear or you'd like to take it even
further, ask
- about it on our mailing list <a
href="http://lists.trialox.org/mailman/listinfo/users";>
- http://lists.trialox.org/mailman/listinfo/users/</a></p>
+ <p>If anything is unclear or you'd like to take it even
further, discuss
+ about it on <a
href="http://forum.clerezza.org/scb-smart-content-binding-f6/";>
+ http://forum.clerezza.org/scb-smart-content-binding-f6/</a></p>
<h2 id="references">8. References</h2>
<p id="ref1">[1] W3C: Resource Description Framework (RDF):
Concepts and Abstract Syntax; 2004,
<a
href="http://www.w3.org/TR/2004/REC-rdf-concepts-20040210/";>http://www.w3.org/TR/2004/REC-rdf-concepts-20040210/</a>
