You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@clerezza.apache.org by it...@apache.org on 2009/12/15 16:56:47 UTC
svn commit: r890847 - in /incubator/clerezza/issues/CLEREZZA-35: ./
org.apache.clerezza.rdf.core/
org.apache.clerezza.rdf.core/src/site/xsite/content/scb-triaxrs-tutorial.xhtml
org.apache.clerezza.rdf.core/src/site/xsite/content/tutorial_1.xhtml
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:john@example.org>;
+ 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:jane@example.org>;
+ 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:john@example.org</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>