clerezza-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From i..@apache.org
Subject 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
Date Tue, 15 Dec 2009 15:56:47 GMT
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>
+&lt;repositories&gt;
+	 &lt;repository&gt;
+		 &lt;id&gt;clerezza-release&lt;/id&gt;
+		 &lt;name&gt;clerezza.org distribution repository&lt;/name&gt;
+		 &lt;url&gt;http://repo.trialox.org/release&lt;/url&gt;
+		 &lt;layout&gt;default&lt;/layout&gt;
+	 &lt;/repository&gt;
+	 &lt;repository&gt;
+		 &lt;id&gt;clerezza-snapshot&lt;/id&gt;
+		 &lt;name&gt;clerezza.org snapshot repository&lt;/name&gt;
+		 &lt;url&gt;http://repo.trialox.org/snapshot&lt;/url&gt;
+		 &lt;layout&gt;default&lt;/layout&gt;
+	 &lt;/repository&gt;
+&lt;/repositories&gt;     
+		</blockcode>
+		<blockcode>
+&lt;parent&gt;
+	 &lt;artifactId&gt;org.clerezza.parent&lt;/artifactId&gt;
+	 &lt;groupId&gt;org.clerezza&lt;/groupId&gt;
+	 &lt;version&gt;0.11-SNAPSHOT&lt;/version&gt; //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&lt;/parent&gt; 		</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>
+&lt;dependency&gt;
+ 	 &lt;groupId&gt;org.clerezza&lt;/groupId&gt;
+ 	 &lt;artifactId&gt;org.clerezza.jaxrs.rdf.providers&lt;/artifactId&gt;
+&lt;/dependency&gt;	            
+&lt;dependency&gt;
+	 &lt;groupId&gt;org.clerezza&lt;/groupId&gt;
+	 &lt;artifactId&gt;org.clerezza.platform.typerendering.seedsnipe&lt;/artifactId&gt;
+&lt;/dependency&gt;
+&lt;dependency&gt;
+	 &lt;groupId&gt;org.clerezza&lt;/groupId&gt;
+	 &lt;artifactId&gt;org.clerezza.triaxrs&lt;/artifactId&gt;
+&lt;/dependency&gt;   
+		</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 &lt;groupId>.&lt;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: &lt;http://xmlns.com/foaf/0.1/&gt;.
+
+[	a foaf:Person;
+    foaf:title "Mr";
+    foaf:name "John Doe";
+    foaf:mbox &lt;mailto:john@example.org&gt;;
+    foaf:topic_interest &lt;http://dbpedia.org/resource/Category:BBC_television_sitcoms&gt;;
+    foaf:nick "jo" ] .
+
+[	a foaf:Person;
+    foaf:title "Mrs";
+    foaf:name "Jane Bloggs";
+    foaf:mbox &lt;mailto:jane@example.org&gt;;
+    foaf:openid &lt;http://openid.example.org/jbloggs&gt; ] .
+		</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&lt;Triple&gt; 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>
+&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"&gt;
+&lt;html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"&gt;
+&lt;head&gt;
+	${ns:foaf=http://xmlns.com/foaf/0.1/}
+	&lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/&gt;
+	&lt;title&gt;clerezza - Combined Tutorial&lt;/title&gt;
+&lt;/head&gt;
+&lt;body&gt;
+	&lt;h1&gt;clerezza - Combined Tutorial&lt;/h1&gt;
+	&lt;h2&gt;FOAF Person:&lt;/h2&gt;
+	&lt;div&gt;
+		&lt;p&gt;Name: ${foaf:title} ${foaf:name}&lt;/p&gt;
+		&lt;p&gt;Email: ${foaf:mbox}&lt;/p&gt;
+		${if foaf:nick}
+		&lt;p&gt;Nickname: ${foaf:nick}&lt;/p&gt;
+		${/if}
+		&lt;p&gt;Topic interests: &lt;br /&gt;
+		${loop}
+			${foaf:topic_interest}&lt;br /&gt;
+		${/loop}
+		&lt;/p&gt;
+	&lt;/div&gt;
+&lt;/body&gt;
+&lt;/html&gt;
+		</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>
+&lt;repositories>
+	&lt;repository>
+		&lt;id>clerezza-release&lt;/id>
+		&lt;name>clerezza.org distribution repository&lt;/name>
+		&lt;url>http://repo.trialox.org/release&lt;/url>
+		&lt;layout>default&lt;/layout>
+	&lt;/repository>
+	&lt;repository>
+		&lt;id>clerezza-snapshot&lt;/id>
+		&lt;name>clerezza.org snapshot repository&lt;/name>
+		&lt;url>http://repo.trialox.org/snapshot&lt;/url>
+		&lt;layout>default&lt;/layout>
+	&lt;/repository>
+&lt;/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>
+&lt;dependency&gt;
+	&lt;groupId&gt;org.clerezza&lt;/groupId&gt;
+	&lt;artifactId&gt;org.clerezza.rdf.core&lt;/artifactId&gt;
+	&lt;version&gt;0.5-SNAPSHOT&lt;/version&gt;
+&lt;/dependency&gt;
+&lt;dependency&gt;
+	&lt;groupId&gt;org.clerezza&lt;/groupId&gt;
+	&lt;artifactId&gt;org.clerezza.rdf.utils&lt;/artifactId&gt;
+	&lt;version&gt;0.5-SNAPSHOT&lt;/version&gt;
+&lt;/dependency&gt;
+&lt;dependency&gt;
+	&lt;groupId&gt;org.clerezza&lt;/groupId&gt;
+	&lt;artifactId&gt;org.clerezza.rdf.ontologies&lt;/artifactId&gt;
+	&lt;version&gt;0.3-SNAPSHOT&lt;/version&gt;
+&lt;/dependency&gt;
+		</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>
+&lt;dependency>
+	&lt;groupId>org.clerezza&lt;/groupId>
+	&lt;artifactId>org.clerezza.rdf.jena.parser&lt;/artifactId>
+	&lt;version>0.2-SNAPSHOT&lt;/version>
+	&lt;!-- &lt;scope>runtime&lt;/scope> -->
+&lt;/dependency>
+&lt;dependency>
+	&lt;groupId>org.clerezza&lt;/groupId>
+	&lt;artifactId>org.clerezza.rdf.jena.serializer&lt;/artifactId>
+	&lt;version>0.2-SNAPSHOT&lt;/version>
+	&lt;!-- &lt;scope>runtime&lt;/scope> -->
+&lt;/dependency>
+&lt;dependency>
+	&lt;groupId>org.slf4j&lt;/groupId>
+	&lt;artifactId>slf4j-simple&lt;/artifactId>
+	&lt;version>1.5.5&lt;/version>
+	&lt;!-- &lt;scope>runtime&lt;/scope> -->
+&lt;/dependency>
+&lt;dependency>
+	&lt;groupId>org.clerezza&lt;/groupId>
+	&lt;artifactId>org.clerezza.rdf.simple.storage&lt;/artifactId>
+	&lt;version>0.2-SNAPSHOT&lt;/version>
+	&lt;!-- &lt;scope>runtime&lt;/scope> -->
+&lt;/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>		
+&lt;build>
+	&lt;plugins>
+		&lt;plugin>
+			&lt;groupId>org.apache.maven.plugins&lt;/groupId>
+			&lt;artifactId>maven-compiler-plugin&lt;/artifactId>
+			&lt;configuration>
+				&lt;source>1.6&lt;/source>
+				&lt;target>1.6&lt;/target>
+			&lt;/configuration>
+		&lt;/plugin>
+	&lt;/plugins>
+&lt;/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&lt;Triple&gt;</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
+			&lt;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
+			&lt;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 &lt;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 &lt;http://dbpedia.org/data/Category:BBC_television_sitcoms.rdf>
+			for a normal browser it would be
+			&lt;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&lt;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
+		&lt;http://dbpedia.org/resource/Category:BBC_television_sitcoms>:</p>
+		<blockcode>
+Iterator&lt;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>
+&lt;dependency>
+	&lt;groupId>org.clerezza&lt;/groupId>
+	&lt;artifactId>org.clerezza.rdf.sesame.storage&lt;/artifactId>
+	&lt;version>0.7-SNAPSHOT&lt;/version>
+	&lt;!-- &lt;scope>runtime&lt;/scope> -->
 &lt;/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>



Mime
View raw message