You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@stanbol.apache.org by bu...@apache.org on 2012/07/16 15:02:48 UTC

svn commit: r825985 [10/12] - in /websites/staging/stanbol/trunk/content: ./ stanbol/docs/trunk/ stanbol/docs/trunk/cmsadapter/ stanbol/docs/trunk/components/ stanbol/docs/trunk/components/cmsadapter/ stanbol/docs/trunk/components/contenthub/ stanbol/d...

Added: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/factstore/specification.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/factstore/specification.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/factstore/specification.html Mon Jul 16 13:02:45 2012
@@ -0,0 +1,387 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE- 2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+
+  <link href="/stanbol/css/stanbol.css" rel="stylesheet" type="text/css">
+  <title>Apache Stanbol - FactStore Specification</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+  <link rel="icon" type="image/png" href="/stanbol/images/stanbol-logo/stanbol-favicon.png"/>
+  <script type="text/javascript">
+    // Google Analytics Tracking Code
+    var _gaq = _gaq || [];
+    _gaq.push(['_setAccount', 'UA-32086816-1']);
+    _gaq.push(['_trackPageview']);
+
+    (function() {
+      var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+      ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+      var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+    })();
+  </script>  
+</head>
+
+<body>
+  <div id="logo"> <!-- do not scroll the logo -->
+  <a href="/stanbol/index.html"><img alt="Apache Stanbol" width="220" height="101" border="0" src="/stanbol/images/stanbol-logo/stanbol-2010-12-14.png"/></a></div>
+  <div id="navigation"> <!-- but auto scroll the menue -->
+      <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</a></li>
+</ul>
+<h1 id="project">Project</h1>
+<ul>
+<li><a href="/stanbol/docs/trunk/mailinglists.html">Mailing Lists</a></li>
+<li><a href="https://issues.apache.org/jira/browse/STANBOL">Issue Tracker</a></li>
+<li><a href="/stanbol/team.html">Project Team</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</a></li>
+</ul>
+<h1 id="the-asf">The ASF</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+  </div>
+  <div id="content">
+    <div class="breadcrump" style="font-size: 80%;">
+      <a href="/">Home</a>&nbsp;&raquo&nbsp;<a href="/stanbol/">Stanbol</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/">Docs</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/trunk/">Trunk</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/trunk/components/">Components</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/trunk/components/factstore/">Factstore</a>
+    </div>
+    <h1 class="title">FactStore Specification</h1>
+    <p>The FactStore is designed to store semantic relations in terms of facts about entities and their relationships. Additionally, the FactStore specifies a simple SQL-like query language expressed in JSON-LD to search for semantic relations and to reason through the use of joined relationships. This specification defines required interfaces for the FactStore in terms of RESTful API interfaces and a <a href="implementation.html">concept for a possible implementation</a>.</p>
+<p>In the following, we will refer to semantic relationships as facts about entities. For example, the relation ‘emplyeeOf’ may be a fact about two entities one of type person and one of type organization. Facts are n-ary meaning that the number of participating entities is not limited. The FactStore implements a store for facts plus the ability to query for single facts and for combinations of facts. In summary, the FactStore provides:</p>
+<ul>
+<li>Persistence storage for n-ary facts about entities</li>
+<li>Query language to query for a single fact</li>
+<li>Query language to query for combinations of facts (reasoning)</li>
+</ul>
+<p>In the following, we will define the required interfaces for the FactStore plus the required query language.</p>
+<p>''Note'': Interfaces will be defined as RESTful service APIs. The payload of service calls is specified using <a href="http://www.json-ld.org/spec/ED/20110507/JSON-LD">Specification version 20110507</a>.</p>
+<p>''Note'': The FactStore does not provide any SPARQL endpoint so far. This could be part of an extended version.</p>
+<h2 id="store-interface">Store Interface</h2>
+<p>The store interface allows clients to put new fact schemata and according facts (instances of that schemata) to the FactStore.</p>
+<h3 id="publish-a-new-fact-schema">Publish a New Fact Schema</h3>
+<p>Allows clients to publish new fact schemata to the FactStore. Each fact is an n-tuple where each element of that tuple defines a certain type of entity. A fact schema defines which types of entities and their roles are part of instances of that fact.</p>
+<p>Path: /factstore/facts/{fact-schema-name}</p>
+<p>Method: PUT with data type application/json returns HTTP 201 (created) on success.</p>
+<p>Data: The fact schema is sent as the PUT payload in JSON-LD format as a JSON-LD profile. The name of the fact is given by the URL. The elements of the schema are defined in the "#types" section of the JSON-LD "#context". Each element is specified using a unique role name for that entity plus the entity type specified by an URN.</p>
+<p>Example 1: PUT /factstore/facts/http%3A%2F%2Fiks-project.eu%2Font%2FemployeeOf with the following data</p>
+<div class="codehilite"><pre><span class="p">{</span>
+  <span class="s">&quot;@context&quot;</span>  <span class="p">:</span>
+  <span class="p">{</span>
+    <span class="s">&quot;iks&quot;</span>     <span class="p">:</span> <span class="s">&quot;http://iks-project.eu/ont/&quot;</span><span class="p">,</span>
+    <span class="s">&quot;#types&quot;</span>  <span class="p">:</span>
+    <span class="p">{</span>
+      <span class="s">&quot;person&quot;</span>       <span class="p">:</span> <span class="s">&quot;iks:person&quot;</span><span class="p">,</span>
+      <span class="s">&quot;organization&quot;</span> <span class="p">:</span> <span class="s">&quot;iks:organization&quot;</span>
+    <span class="p">}</span>
+  <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>will create the new fact schema for "employeeOf" at the given URL which is in decoded representation: /factstore/facts/http://iks-project.eu/ont/employeeOf</p>
+<p>Instead one can use the cURL tool for this. Store the fact schema in a JSON file and then use this command.</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/factstore/</span><span class="n">facts</span><span class="o">/</span><span class="n">http</span><span class="nv">%3A%2F%2Fiks</span><span class="o">-</span><span class="n">project</span><span class="o">.</span><span class="n">eu</span><span class="nv">%2Font%2FemployeeOf</span> <span class="o">-</span><span class="n">T</span> <span class="n">spec</span><span class="o">-</span><span class="n">example1</span><span class="o">.</span><span class="n">json</span>
+</pre></div>
+
+
+<p>Example 2: PUT /factstore/facts/http%3A%2F%2Fwww.schema.org%2FEvent.attendees with the following data</p>
+<div class="codehilite"><pre><span class="p">{</span>
+  <span class="s">&quot;@context&quot;</span> <span class="p">:</span>
+  <span class="p">{</span>
+    <span class="s">&quot;sorg&quot;</span>       <span class="p">:</span> <span class="s">&quot;http://www.schema.org/&quot;</span><span class="p">,</span>
+    <span class="s">&quot;#types&quot;</span>     <span class="p">:</span>
+    <span class="p">{</span>
+      <span class="s">&quot;event&quot;</span>    <span class="p">:</span> <span class="s">&quot;sorg:Event&quot;</span><span class="p">,</span>
+      <span class="s">&quot;attendee&quot;</span> <span class="p">:</span> <span class="p">[</span><span class="s">&quot;sorg:Person&quot;</span><span class="p">,</span><span class="s">&quot;sorg:Organization&quot;</span><span class="p">]</span>
+    <span class="p">}</span>
+  <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>will create the new fact schema for "attendees" at the given URL which is in decoded representation: /factstore/facts/http://www.schema.org/Event.attendees.</p>
+<p>''Note'': This fact schema uses the ability to define more than one possible type for a role. The role 'attendee' can be of type http://www.schema.org/Person or http://www.schema.org/Organization.</p>
+<h3 id="get-fact-schema">Get Fact Schema</h3>
+<p>Allows clients to get the definition of an existing fact schema.</p>
+<p>Path: /factstore/facts/{fact-schema-name}</p>
+<p>Method: GET with data type application/json returns HTTP 200 on success.</p>
+<p>Data: The fact schema is returned as a JSON-LD profile.</p>
+<p>Example: GET /factstore/facts/http%3A%2F%2Fiks-project.eu%2Font%2FemployeeOf will return the following data:</p>
+<div class="codehilite"><pre><span class="p">{</span>
+  <span class="s">&quot;@context&quot;</span> <span class="p">:</span>
+  <span class="p">{</span>
+    <span class="s">&quot;#types&quot;</span>  <span class="p">:</span>
+    <span class="p">{</span>
+      <span class="s">&quot;person&quot;</span>       <span class="p">:</span> <span class="s">&quot;http://iks-project.eu/ont/person&quot;</span><span class="p">,</span>
+      <span class="s">&quot;organization&quot;</span> <span class="p">:</span> <span class="s">&quot;http://iks-project.eu/ont/organization&quot;</span>
+    <span class="p">}</span>
+  <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Status: <strong>Implemented</strong></p>
+<h3 id="publish-new-facts">Publish New Facts</h3>
+<p>Allows clients to publish a new facts according to a defined fact schema that was previously published to the FactStore. Each new fact is an n-tuple according to its schema where each tuple element identifies an entity using its unique IRI.</p>
+<p>Path: /factstore/facts</p>
+<p>Method: POST with data type application/json returns HTTP 201 (created) on success.</p>
+<p>Data: The facts are sent as the POST payload in JSON-LD format referring to the defined JSON-LD profile. The name of the fact is given in the "@profile" element of the JSON-LD object. The JSON-LD object contains a list of facts under the attribute "facts" where each element of that list is an n-tuple of entity instances according to fhe fact schema. The instance of an entity can be specified either by its unique IRI or by specifying the instance by example.</p>
+<p>Using the instance by example variant requires the FactStore to resolve the entity in an EntityHub. An entity by example is specified by defining attributes and required values of the searched entity. A fact can only be stored if all entities can be uniquely identified either by their IRI or by example.</p>
+<p>Example 1: POST /factstore/facts with the following data</p>
+<div class="codehilite"><pre><span class="p">{</span>
+  <span class="s">&quot;@context&quot;</span> <span class="p">:</span> <span class="p">{</span>
+    <span class="s">&quot;iks&quot;</span> <span class="p">:</span> <span class="s">&quot;http://iks-project.eu/ont/&quot;</span><span class="p">,</span>
+    <span class="s">&quot;upb&quot;</span> <span class="p">:</span> <span class="s">&quot;http://upb.de/persons/&quot;</span>
+  <span class="p">},</span>
+  <span class="s">&quot;@profile&quot;</span>     <span class="p">:</span> <span class="s">&quot;iks:employeeOf&quot;</span><span class="p">,</span>
+  <span class="s">&quot;person&quot;</span>       <span class="p">:</span> <span class="p">{</span> <span class="s">&quot;@iri&quot;</span> <span class="p">:</span> <span class="s">&quot;upb:bnagel&quot;</span> <span class="p">},</span>
+  <span class="s">&quot;organization&quot;</span> <span class="p">:</span> <span class="p">{</span> <span class="s">&quot;@iri&quot;</span> <span class="p">:</span> <span class="s">&quot;http://uni-paderborn.de&quot;</span><span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>creates a new fact of type http://iks-project.eu/ont/employeeof specifying that the person http://upb.de/persons/bnagel is employee of the organization defined by the IRI http://uni-paderborn.de.</p>
+<p>Example 2: POST /factstore/facts with the following data to create several facts of the same type at once</p>
+<div class="codehilite"><pre><span class="p">{</span>
+  <span class="s">&quot;@context&quot;</span> <span class="o">:</span> <span class="p">{</span>
+    <span class="s">&quot;iks&quot;</span> <span class="o">:</span> <span class="s">&quot;http://iks-project.eu/ont/&quot;</span><span class="p">,</span>
+    <span class="s">&quot;upb&quot;</span> <span class="o">:</span> <span class="s">&quot;http://upb.de/persons/&quot;</span>
+  <span class="p">},</span>
+  <span class="s">&quot;@profile&quot;</span>     <span class="o">:</span> <span class="s">&quot;iks:employeeOf&quot;</span><span class="p">,</span>
+  <span class="s">&quot;@&quot;</span> <span class="o">:</span> <span class="p">[</span>
+    <span class="p">{</span> <span class="s">&quot;person&quot;</span>       <span class="o">:</span> <span class="p">{</span> <span class="s">&quot;@iri&quot;</span> <span class="o">:</span> <span class="s">&quot;upb:bnagel&quot;</span> <span class="p">},</span>
+      <span class="s">&quot;organization&quot;</span> <span class="o">:</span> <span class="p">{</span> <span class="s">&quot;@iri&quot;</span> <span class="o">:</span> <span class="s">&quot;http://uni-paderborn.de&quot;</span> <span class="p">}</span>
+    <span class="p">},</span>
+    <span class="p">{</span> <span class="s">&quot;person&quot;</span>       <span class="o">:</span> <span class="p">{</span> <span class="s">&quot;@iri&quot;</span> <span class="o">:</span> <span class="s">&quot;upb:fchrist&quot;</span> <span class="p">},</span>
+      <span class="s">&quot;organization&quot;</span> <span class="o">:</span> <span class="p">{</span> <span class="s">&quot;@iri&quot;</span> <span class="o">:</span> <span class="s">&quot;http://uni-paderborn.de&quot;</span> <span class="p">}</span>
+    <span class="p">}</span>
+  <span class="p">]</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>creates two new facts of type http://iks-project.eu/ont/employeeof specifying that the persons http://upb.de/persons/bnagel and http://upb.de/persons/fchrist are employees of the organization defined by the IRI http://uni-paderborn.de.</p>
+<p>Example 3: POST /factstore/facts with the following data to create several facts of different type</p>
+<div class="codehilite"><pre><span class="p">{</span>
+  <span class="s">&quot;@context&quot;</span> <span class="o">:</span> <span class="p">{</span>
+    <span class="s">&quot;iks&quot;</span> <span class="o">:</span> <span class="s">&quot;http://iks-project.eu/ont/&quot;</span><span class="p">,</span>
+    <span class="s">&quot;upb&quot;</span> <span class="o">:</span> <span class="s">&quot;http://upb.de/persons/&quot;</span>
+  <span class="p">},</span>
+  <span class="s">&quot;@&quot;</span> <span class="o">:</span> <span class="p">[</span>
+    <span class="p">{</span> <span class="s">&quot;@profile&quot;</span>     <span class="o">:</span> <span class="s">&quot;iks:employeeOf&quot;</span><span class="p">,</span>
+      <span class="s">&quot;person&quot;</span>       <span class="o">:</span> <span class="p">{</span> <span class="s">&quot;@iri&quot;</span> <span class="o">:</span> <span class="s">&quot;upb:bnagel&quot;</span> <span class="p">},</span>
+      <span class="s">&quot;organization&quot;</span> <span class="o">:</span> <span class="p">{</span> <span class="s">&quot;@iri&quot;</span> <span class="o">:</span> <span class="s">&quot;http://uni-paderborn.de&quot;</span> <span class="p">}</span>
+    <span class="p">},</span>
+    <span class="p">{</span> <span class="s">&quot;@profile&quot;</span>     <span class="o">:</span> <span class="s">&quot;iks:friendOf&quot;</span><span class="p">,</span>
+      <span class="s">&quot;person&quot;</span>       <span class="o">:</span> <span class="p">{</span> <span class="s">&quot;@iri&quot;</span> <span class="o">:</span> <span class="s">&quot;upb:bnagel&quot;</span> <span class="p">},</span>
+      <span class="s">&quot;friend&quot;</span>       <span class="o">:</span> <span class="p">{</span> <span class="s">&quot;@iri&quot;</span> <span class="o">:</span> <span class="s">&quot;upb:fchrist&quot;</span> <span class="p">}</span>
+    <span class="p">}</span>
+  <span class="p">]</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>creates two new facts. The first one of type http://iks-project.eu/ont/employeeof specifying that the person http://upb.de/persons/bnagel is employee of the organization defined by the IRI http://uni-paderborn.de. The second of type http://iks-project.eu/ont/friendOf specifying that http://upb.de/persons/fchrist is a friend of http://upb.de/persons/bnagel.</p>
+<p>Status: <strong>Implemented</strong></p>
+<h2 id="query-interface">Query Interface</h2>
+<p>The query interface allows clients to query for facts and combination of facts (reasoning). The JSON-LD query structure is inspired by SQL using SELECT FROM [JOIN] WHERE constructs. Depending on the implementation the JSON-LD queries may be transformed directly into valid SQL queries.</p>
+<h3 id="query-for-facts-of-a-certain-type">Query for Facts of a Certain Type</h3>
+<p>Allows clients to query stored facts of a specific type defined by the fact's schema. The clients specify the desired fact plus an arbitrary number of entities that play some role in the fact.</p>
+<p>Path: /factstore/query</p>
+<p>Method: POST with data type application/json returns application/json</p>
+<p>Data: The query is specified by a JSON-LD object in the payload of the request. The query defines a "select" to specify the desired type of result to be returned in the result set. The "from" part specifies the fact type to query and the "where" clause specifies constraints to be fulfilled.</p>
+<p><em>Note</em>: For the moment constraints only support the equals "=" relation. There may be more relations like "&gt;" in future versions of this specification. If there is more than one constraint all constraints are concatenated by "AND".</p>
+<p>Example 1: POST /factstore/query with the following data</p>
+<div class="codehilite"><pre><span class="p">{</span>
+  <span class="s">&quot;@context&quot;</span> <span class="p">:</span> <span class="p">{</span>
+    <span class="s">&quot;iks&quot;</span> <span class="p">:</span> <span class="s">&quot;http://iks-project.eu/ont/&quot;</span>
+  <span class="p">},</span>
+  <span class="s">&quot;select&quot;</span> <span class="p">:</span> <span class="p">[</span> <span class="s">&quot;person&quot;</span> <span class="p">],</span>
+  <span class="s">&quot;from&quot;</span>   <span class="p">:</span> <span class="s">&quot;iks:employeeOf&quot;</span><span class="p">,</span>
+  <span class="s">&quot;where&quot;</span>  <span class="p">:</span> <span class="p">[</span>
+    <span class="p">{</span>
+      <span class="s">&quot;=&quot;</span>  <span class="p">:</span> <span class="p">{</span>
+        <span class="s">&quot;organization&quot;</span> <span class="p">:</span> <span class="p">{</span> <span class="s">&quot;@iri&quot;</span> <span class="p">:</span> <span class="s">&quot;http://uni-paderborn.de&quot;</span> <span class="p">}</span>
+      <span class="p">}</span>
+    <span class="p">}</span>
+  <span class="p">]</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>returns the list of all persons participating in the fact of type http://iks-project.eu/ont/employeeOf where the organization is http://uni-paderborn.de. The result is sent back in JSON-LD format with the result set specified by the select clause.</p>
+<div class="codehilite"><pre><span class="p">{</span>
+  <span class="s">&quot;@subject&quot;</span> <span class="p">:</span> <span class="p">[</span>
+    <span class="p">{</span>
+      <span class="s">&quot;@subject&quot;</span> <span class="p">:</span> <span class="s">&quot;_bnode1&quot;</span><span class="p">,</span>
+      <span class="s">&quot;PERSON&quot;</span>   <span class="p">:</span> <span class="s">&quot;http://upb.de/persons/gengels&quot;</span>
+    <span class="p">},</span>
+    <span class="p">{</span>
+      <span class="s">&quot;@subject&quot;</span> <span class="p">:</span> <span class="s">&quot;_bnode2&quot;</span><span class="p">,</span>
+      <span class="s">&quot;PERSON&quot;</span>   <span class="p">:</span> <span class="s">&quot;http://upb.de/persons/ssauer&quot;</span>
+    <span class="p">},</span>
+    <span class="p">{</span>
+      <span class="s">&quot;@subject&quot;</span> <span class="p">:</span> <span class="s">&quot;_bnode3&quot;</span><span class="p">,</span>
+      <span class="s">&quot;PERSON&quot;</span>   <span class="p">:</span> <span class="s">&quot;http://upb.de/persons/bnagel&quot;</span>
+    <span class="p">},</span>
+    <span class="p">{</span>
+      <span class="s">&quot;@subject&quot;</span> <span class="p">:</span> <span class="s">&quot;_bnode4&quot;</span><span class="p">,</span>
+      <span class="s">&quot;PERSON&quot;</span>   <span class="p">:</span> <span class="s">&quot;http://upb.de/persons/fchrist&quot;</span>
+    <span class="p">}</span>
+  <span class="p">]</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>If there is only one entry in the result set, this would be returned as follows.</p>
+<div class="codehilite"><pre><span class="p">{</span>
+  <span class="s">&quot;PERSON&quot;</span>   <span class="p">:</span> <span class="s">&quot;http://upb.de/persons/fchrist&quot;</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Status: <strong>Example 1 is implemented</strong>.</p>
+<p>Example 2: GET /factstore/query?q= with the following data as the request parameter "q"</p>
+<div class="codehilite"><pre><span class="p">{</span>
+  <span class="s">&quot;@context&quot;</span> <span class="p">:</span> <span class="p">{</span>
+    <span class="s">&quot;iks&quot;</span> <span class="p">:</span> <span class="s">&quot;http://iks-project.eu/ont/&quot;</span>
+  <span class="p">},</span>
+  <span class="s">&quot;select&quot;</span> <span class="p">:</span> <span class="p">[</span>
+    <span class="s">&quot;person.name&quot;</span><span class="p">,</span> <span class="s">&quot;person.email&quot;</span>
+  <span class="p">],</span>
+  <span class="s">&quot;from&quot;</span> <span class="p">:</span> <span class="s">&quot;iks:employeeOf&quot;</span><span class="p">,</span>
+  <span class="s">&quot;where&quot;</span> <span class="p">:</span> <span class="p">[</span>
+    <span class="p">{</span>
+      <span class="s">&quot;=&quot;</span> <span class="p">:</span> <span class="p">{</span>
+        <span class="s">&quot;organization&quot;</span> <span class="p">:</span> <span class="p">{</span> <span class="s">&quot;@iri&quot;</span> <span class="p">:</span> <span class="s">&quot;http://upb.de&quot;</span> <span class="p">}</span>
+      <span class="p">}</span>
+    <span class="p">}</span>
+  <span class="p">]</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>returns a list with names and e-mail addresses of all persons participating in the fact of type http://iks-project.eu/ont/employeeOf where the organization is http://upb.de. The result is sent back in JSON-LD format with the result set specified by the select clause.</p>
+<div class="codehilite"><pre><span class="p">{</span>
+  <span class="s">&quot;resultset&quot;</span><span class="p">:</span> <span class="p">[</span>
+    <span class="p">{</span> <span class="s">&quot;person.name&quot;</span> <span class="p">:</span> <span class="s">&quot;Gregor Engels&quot;</span><span class="p">,</span>
+      <span class="s">&quot;person.email&quot;</span><span class="p">:</span> <span class="s">&quot;engels@upb.de&quot;</span>  <span class="p">},</span>
+    <span class="p">{</span> <span class="s">&quot;person.name&quot;</span> <span class="p">:</span> <span class="s">&quot;Stefan Sauer&quot;</span><span class="p">,</span>
+      <span class="s">&quot;person.email&quot;</span><span class="p">:</span> <span class="s">&quot;sauer@upb.de&quot;</span>   <span class="p">},</span>
+    <span class="p">{</span> <span class="s">&quot;person.name&quot;</span> <span class="p">:</span> <span class="s">&quot;Benjamin Nagel&quot;</span><span class="p">,</span>
+      <span class="s">&quot;person.email&quot;</span><span class="p">:</span> <span class="s">&quot;nagel@upb.de&quot;</span>   <span class="p">},</span>
+    <span class="p">{</span> <span class="s">&quot;person.name&quot;</span> <span class="p">:</span> <span class="s">&quot;Fabian Christ&quot;</span><span class="p">,</span>
+      <span class="s">&quot;person.email&quot;</span><span class="p">:</span> <span class="s">&quot;christ@upb.de&quot;</span>  <span class="p">}</span>
+  <span class="p">]</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Status: <strong>Example 2 is NOT Implemented, yet.</strong></p>
+<h3 id="query-for-combinations-of-facts">Query for Combinations of Facts</h3>
+<p>Allows clients to query for combinations of facts.</p>
+<p>Path: /factstore/query?q=</p>
+<p>Method: GET with data type application/json returns application/json</p>
+<p>Data: The query is specified by a JSON-LD object in request parameter "q" of the request. The query defines a "select" to specify the desired type of result to be returned in the result set. Instead of using a "from" part this type of query supports joins over facts using the "join" field. The "join" field specifies which facts are joined by specifying the elements of the facts that are evaluated to be equal during the join. The "where" clause specifies constraints over the join to be fulfilled.</p>
+<p><em>Note</em>: For the moment constraints only support the equals "=" relation. There may be more relations like "&gt;" in future versions of this specification. If there is more than one constraint all constraints are concatenated by "AND".</p>
+<p>Example: GET /factstore/query?q= with the following request data in request parameter "q"</p>
+<div class="codehilite"><pre><span class="p">{</span>
+  <span class="s">&quot;@context&quot;</span> <span class="p">:</span> <span class="p">{</span>
+    <span class="s">&quot;iks&quot;</span> <span class="p">:</span> <span class="s">&quot;http://iks-project.eu/ont/&quot;</span>
+  <span class="p">},</span>
+  <span class="s">&quot;select&quot;</span><span class="p">:</span> <span class="p">[</span>
+    <span class="s">&quot;iks:friendOf.friend.name&quot;</span>
+  <span class="p">],</span>
+  <span class="s">&quot;join&quot;</span> <span class="p">:</span> <span class="p">{</span>
+    <span class="s">&quot;iks:employeeOf.person&quot;</span> <span class="p">:</span> <span class="s">&quot;iks:friendOf.person&quot;</span>
+  <span class="p">},</span>
+  <span class="s">&quot;where&quot;</span> <span class="p">:</span> <span class="p">[</span>
+    <span class="p">{</span>
+      <span class="s">&quot;=&quot;</span> <span class="p">:</span> <span class="p">{</span>
+        <span class="s">&quot;iks:employeeOf.organization&quot;</span> <span class="p">:</span> <span class="p">{</span>
+          <span class="s">&quot;@iri&quot;</span> <span class="p">:</span> <span class="s">&quot;http://upb.de&quot;</span>
+        <span class="p">}</span>
+      <span class="p">}</span>
+    <span class="p">},</span>
+    <span class="p">{</span>
+      <span class="s">&quot;=&quot;</span> <span class="p">:</span> <span class="p">{</span>
+        <span class="s">&quot;iks:friendOf.friend.city&quot;</span> <span class="p">:</span> <span class="s">&quot;Paderborn&quot;</span>
+      <span class="p">}</span>
+    <span class="p">}</span>
+  <span class="p">]</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>will return a list of names of all the friends living in Paderborn of the employees of the University of Paderborn. The result in JSON-LD format would look like the following.</p>
+<div class="codehilite"><pre><span class="p">{</span>
+  <span class="s">&quot;@context&quot;</span> <span class="p">:</span> <span class="p">{</span>
+    <span class="s">&quot;iks&quot;</span> <span class="p">:</span> <span class="s">&quot;http://iks-project.eu/ont/&quot;</span>
+  <span class="p">},</span>
+  <span class="s">&quot;resultset&quot;</span><span class="p">:</span> <span class="p">[</span>
+    <span class="p">{</span> <span class="s">&quot;iks:friendOf.friend.name&quot;</span> <span class="p">:</span> <span class="s">&quot;Schmidt&quot;</span>   <span class="p">},</span>
+    <span class="p">{</span> <span class="s">&quot;iks:friendOf.friend.name&quot;</span> <span class="p">:</span> <span class="s">&quot;Meier&quot;</span>     <span class="p">},</span>
+    <span class="p">{</span> <span class="s">&quot;iks:friendOf.friend.name&quot;</span> <span class="p">:</span> <span class="s">&quot;Schneider&quot;</span> <span class="p">},</span>
+    <span class="p">{</span> <span class="s">&quot;iks:friendOf.friend.name&quot;</span> <span class="p">:</span> <span class="s">&quot;Schuster&quot;</span>  <span class="p">}</span>
+  <span class="p">]</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Status: <strong>NOT Implemented, yet.</strong></p>
+<hr />
+<p><em>Back to <a href="index.html">FactStore</a></em></p>
+  </div>
+  
+  <div id="footer">
+    <div class="copyright">
+      <p>
+        Copyright &copy; 2010 The Apache Software Foundation, Licensed under 
+        the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+        <br />
+        Apache, Stanbol and the Apache feather and Stanbol logos are trademarks of The Apache Software Foundation.
+      </p>
+    </div>
+  </div>
+  
+</body>
+</html>

Added: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/index.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/index.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/index.html Mon Jul 16 13:02:45 2012
@@ -0,0 +1,146 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE- 2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+
+  <link href="/stanbol/css/stanbol.css" rel="stylesheet" type="text/css">
+  <title>Apache Stanbol - Apache Stanbol Components</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+  <link rel="icon" type="image/png" href="/stanbol/images/stanbol-logo/stanbol-favicon.png"/>
+  <script type="text/javascript">
+    // Google Analytics Tracking Code
+    var _gaq = _gaq || [];
+    _gaq.push(['_setAccount', 'UA-32086816-1']);
+    _gaq.push(['_trackPageview']);
+
+    (function() {
+      var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+      ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+      var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+    })();
+  </script>  
+</head>
+
+<body>
+  <div id="logo"> <!-- do not scroll the logo -->
+  <a href="/stanbol/index.html"><img alt="Apache Stanbol" width="220" height="101" border="0" src="/stanbol/images/stanbol-logo/stanbol-2010-12-14.png"/></a></div>
+  <div id="navigation"> <!-- but auto scroll the menue -->
+      <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</a></li>
+</ul>
+<h1 id="project">Project</h1>
+<ul>
+<li><a href="/stanbol/docs/trunk/mailinglists.html">Mailing Lists</a></li>
+<li><a href="https://issues.apache.org/jira/browse/STANBOL">Issue Tracker</a></li>
+<li><a href="/stanbol/team.html">Project Team</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</a></li>
+</ul>
+<h1 id="the-asf">The ASF</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+  </div>
+  <div id="content">
+    <div class="breadcrump" style="font-size: 80%;">
+      <a href="/">Home</a>&nbsp;&raquo&nbsp;<a href="/stanbol/">Stanbol</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/">Docs</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/trunk/">Trunk</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/trunk/components/">Components</a>
+    </div>
+    <h1 class="title">Apache Stanbol Components</h1>
+    <p><img alt="Apache Stanbol Components" src="images/stanbol-components.png" title="Overview on the different Components included by Apache Stanbol" />
+<figcaption>Figure 1: The Apache Stanbol Components</figcaption></p>
+<p>Apache Stanbol is built as a modular set of components. Each component is accessible via its own RESTful web interface. From this viewpoint, all Apache Stanbol features can be used via RESTful service calls. </p>
+<p>Components do not depend on each other. However they can be easily combined if needed as shown by the different <a href="scenarios.html">Usage Scenarios</a>. This ensures that the list of used components depend on the specific usage scenario and not on the Stanbol architecture.</p>
+<p>All components are implemented as <a href="http://www2.osgi.org/Specifications/HomePage">OSGi</a> bundles, components and services. By default Apache Stanbol uses <a href="http://felix.apache.org">Apache Felix</a> as OSGi environment. However generally we try to avoid the use of Felix specific features. If you need to run Stanbol in an other OSGi environment an encounter problems tell us by opening a <a href="https://issues.apache.org/jira/browse/STANBOL">JIRA issue</a> and/or asking about it on the Stanbol Developer <a href="mailinglists.html">mailing list</a>.</p>
+<p>For deployment Stanbol uses the <a href="http://sling.apache.org">Apache Sling</a> launcher. While the Stanbol Community maintains different launcher options including run-able JARs and WAR files we expect users to configure their custom launchers optimized for their usage scenario. However it os also possible to us Stanbol with other launchers (such as <a href="http://karaf.apache.org/">Apache Karaf</a>) or to add its bundles to any existing OSGi environment.</p>
+<p>Figure 2 depicts the main Apache Stanbol components and their arrangement within the Apache Stanbol architecture.</p>
+<p><img alt="Apache Stanbol Components" src="images/stanbol-architecture.png" title="Apache Stanbol Components" />
+<figcaption>Figure 2: Apache Stanbol Architecture</figcaption></p>
+<ul>
+<li>
+<p>The <a href="enhancer/">Enhancer</a> component together with its <a href="enhancer/engines/list.html">Enhancement Engines</a> provides you with the ability to post content to Apache Stanbol and get suggestions for possible entity annotation in return. The enhancements are provided via natural language processing, metadata extraction and linking named entities to public or private entity repositories. Furthermore, Apache Stanbol provides a machinery to further process this data and add additional knowledge and links via applying rules and reasoning. Technically, the enhancements are stored in a triple-graph that is maintained by <a href="http://incubator.apache.org/clerezza">Apache Clerezza</a>.</p>
+</li>
+<li>
+<p>The 'Sparql endpoint' gives access to RDF graphs of Apache Stanbol. This especially includes the graph with all Enhancement Results managed by the Stanbol <a href="contenthub/">Contenthub</a>.</p>
+</li>
+<li>
+<p>The 'EnhancerVIE' is a stateful interface to submit content to analyze and store the results on the server. It is then possible to browse the resulting enhanced content items.</p>
+</li>
+<li>
+<p>The <a href="rules.html">Rules</a> component provides you with the means to refactor knowledge graphs, e.g. for supporting the schema.org vocabulary for search engine optimization. </p>
+</li>
+<li>
+<p>The <a href="reasoners.html">Reasoners</a> can be used to automatically infer additional knowledge. It is used to obtain new facts in the knowledge base, e.g. if your enhanced content tells you about a shop located in "Montparnasse", you can infer via a "located-in" relation that the same shop is located in "Paris", in the "Île-de-France" and in "France".</p>
+</li>
+<li>
+<p>The <a href="ontologymanager/">Ontology Manager</a> is the facility that manages your ontologies. Ontologies are used to define the knowledge models that describe the metadata of content. Additionally, the semantics of your metadata can be defined through an ontology.</p>
+</li>
+<li>
+<p>The <a href="cmsadapter/">CMS Adapter</a> CMS Adapter component acts as a bridge between JCR/CMIS compliant content management systems and the Apache Stanbol.  It can be used to map existing node structures from JCR/CMIS content repositories to RDF models or vica versa. It also provides services for the management of content repository items as <a href="enhancer/contentitem.html">Content Item</a>s within Contenthub.</p>
+</li>
+<li>
+<p>The <a href="entityhub/">Entityhub</a> is the component, which lets you cache and manage local indexes of repositories such as dbpedia but also custom data (e.g. product descriptions, contact data, specialized topic thesauri).</p>
+</li>
+<li>
+<p>The <a href="contenthub/">Contenthub</a> is the component which provides persistent document store whose back-end is Apache Solr. On top of the store, it enables semantic indexing facilities during text based document submission 
+and semantic search together with faceted search capability on the documents.</p>
+</li>
+<li>
+<p>The <a href="factstore/">FactStore</a> is a component that let's use store relations between entities identified by their URIs. This relation between two entities is called a <em>fact</em>.</p>
+</li>
+</ul>
+<hr />
+<p><em>Back to <a href="index.html">Documentation</a></em></p>
+  </div>
+  
+  <div id="footer">
+    <div class="copyright">
+      <p>
+        Copyright &copy; 2010 The Apache Software Foundation, Licensed under 
+        the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+        <br />
+        Apache, Stanbol and the Apache feather and Stanbol logos are trademarks of The Apache Software Foundation.
+      </p>
+    </div>
+  </div>
+  
+</body>
+</html>

Added: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/ontologymanager/index.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/ontologymanager/index.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/ontologymanager/index.html Mon Jul 16 13:02:45 2012
@@ -0,0 +1,138 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE- 2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+
+  <link href="/stanbol/css/stanbol.css" rel="stylesheet" type="text/css">
+  <title>Apache Stanbol - Apache Stanbol Ontology Manager</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+  <link rel="icon" type="image/png" href="/stanbol/images/stanbol-logo/stanbol-favicon.png"/>
+  <script type="text/javascript">
+    // Google Analytics Tracking Code
+    var _gaq = _gaq || [];
+    _gaq.push(['_setAccount', 'UA-32086816-1']);
+    _gaq.push(['_trackPageview']);
+
+    (function() {
+      var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+      ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+      var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+    })();
+  </script>  
+</head>
+
+<body>
+  <div id="logo"> <!-- do not scroll the logo -->
+  <a href="/stanbol/index.html"><img alt="Apache Stanbol" width="220" height="101" border="0" src="/stanbol/images/stanbol-logo/stanbol-2010-12-14.png"/></a></div>
+  <div id="navigation"> <!-- but auto scroll the menue -->
+      <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</a></li>
+</ul>
+<h1 id="project">Project</h1>
+<ul>
+<li><a href="/stanbol/docs/trunk/mailinglists.html">Mailing Lists</a></li>
+<li><a href="https://issues.apache.org/jira/browse/STANBOL">Issue Tracker</a></li>
+<li><a href="/stanbol/team.html">Project Team</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</a></li>
+</ul>
+<h1 id="the-asf">The ASF</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+  </div>
+  <div id="content">
+    <div class="breadcrump" style="font-size: 80%;">
+      <a href="/">Home</a>&nbsp;&raquo&nbsp;<a href="/stanbol/">Stanbol</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/">Docs</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/trunk/">Trunk</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/trunk/components/">Components</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/trunk/components/ontologymanager/">Ontologymanager</a>
+    </div>
+    <h1 class="title">Apache Stanbol Ontology Manager</h1>
+    <p>The Apache Stanbol Ontology Manager provides a <strong>controlled environment</strong> for managing ontologies, <strong>ontology networks</strong> and user sessions for semantic data modeled after them. It provides full access to ontologies stored into the Stanbol persistence layer. Managing an ontology network means that you can activate or deactivate parts of a complex model from time to time, so that your data can be viewed and classified under different &quot;logical lenses&quot;. This is especially useful in <a href="reasoners.html">Reasoning</a> operations.</p>
+<h2 id="usage-scenarios">Usage Scenarios</h2>
+<h3 id="user-networks">User networks</h3>
+<p>In your CMS, you might be interested in figuring out the trust and acquaintance network of its users. This can be a combination of the <em>asserted</em> network (i.e. what other users are included in the contact or friend list of a given user) with the <em>inferred</em> network (e.g. exclude those who are in the contact list of a blacklisted user). The latter can be derived from the user activities over the user-generated content of your CMS (e.g. blogs posts, forum posts, reviews, tweets, ratings). </p>
+<p>Both types of networks can be modelled as ontologies. Models can be build on the <em>class</em> level, or <em>TBox</em> (e.g. everyone who is an Administrator is also a User, and collaborates with every other Administrator of the same system) and on the <em>instance</em> level, or <em>ABox</em> (e.g. John is a friend of Mary, who created blog post bp345263 on 3/10/2012 at 15:10). These models can all be stored using the Store facility of the Ontology Manager.</p>
+<p>Using a <a href="reasoners.html">reasoner</a> you can classify all the knowledge loaded on Stanbol, but this can be a time-consuming process due to classifying knowledge we are not interested in for this task. <a href="ontologymanager/ontonet.html">OntoNet</a> allows you to select only the &quot;interesting&quot; parts of your knowledge base. For example, if the knowledge contains classifications of animal species, you may want to deactivate that model when reasoning on user networks. Likewise, you may want to consider the user profiles <em>today</em>, rather than who was a user's friend five years ago. Therefore, on the instance level you will exclude the profile history and only consider today's snapshot.</p>
+<h3 id="knowledge-within-content">Knowledge within content</h3>
+<p>Hierarchical, tree-like structures are a tried-and-true mechanism for organizing documents, applications and in fact any content items. What users are required to do is select <em>one</em> set of criteria and organize the directory structure accordingly. For instance, if journalists were to classify the reserch papers on their file system, they could do as follows:</p>
+<ul>
+<li><code>articles/mine</code> (articles authored by the users)</li>
+<li><code>articles/ours</code> (articles authored by colleagues from the same publication)</li>
+<li><code>articles/others</code> (articles of any other kind)</li>
+</ul>
+<p>This simple structure works well because it creates a perfect partition, i.e. you will always know in which <em>one</em> of these directories any article should go. But what if the user also wanted to create directories by year of publication, or by section (politics, sports etc.)? In a file system it is possible to create these directories and add symbolic links as needed, but what if the user does not want to <em>know</em> a priori the categories to create directories for? Why not have a system that creates them aoutomatically according to the semantics of content that create "good" directories (e.g. not too many directories with just one content item)?</p>
+<p>Organizing a network of ontologies that describe content items can allow such an application to be built. Having a dataset that represent the metadata of content stored in a CMS, it is possible to attach different ontology scopes, e.g. those with domain knowledge, or with the user's organizational hierarchy. This "virtual directory" structure can also update automatically as the knowledge does. For instance, if the user removes another user from a "friends" list, that user's contributions will also be moved out of a <code>articles/friends</code> directory but stay in a <code>articles/friends_of_friends</code> directory.</p>
+<h2 id="features">Features</h2>
+<p>A Web <strong>Ontology</strong> in computer and information science is a shareable conceptual model of a part of the world <a href="#ref1">[1]</a>. This model describes concepts terms of their characteristics and their relations with other concepts. By means of OntoNet, it is possible to improve ontology managers like this:</p>
+<ul>
+<li>Setup multiple <strong>Ontology networks</strong> simultaneously, by interconnecting the knowledge contained in ontologies that normally would not be aware of one another.</li>
+<li>Dynamic <strong>(de-)activation</strong> of parts of any ontology network, as needed by specific reasoning, rule execution, or other knowledge processing tasks.</li>
+<li>Organize ontologies into <strong>ontology libraries</strong>, which can be populated by setting up simple RDF graphs called <strong>registries</strong>.</li>
+<li>Use Stanbol as a central <strong>ontology repository</strong> that mirrors the ontologies scattered aound the Web, so that there will be no need to query more than a single server for all the formal knowledge managed by the CMS.</li>
+</ul>
+<h3 id="sub-components">Sub-Components</h3>
+<ul>
+<li><a href="ontonet/">OntoNet</a>     - allows to construct subsets of the knowledge base managed by Stanbol into OWL/OWL2 <a href="#ref2">[2]</a>ontology networks</li>
+<li><a href="registry/">Registry</a>  - manages ontology libraries for bootstrapping the network using both external and internal ontologies</li>
+<li>Store       - create, read, update and delete operations on single ontologies stored in Stanbol. These operations can be performed on entities, axioms, and whole ontologies.</li>
+</ul>
+<h2 id="references">References:</h2>
+<ul>
+<li>[1] <a name="ref1" href="http://tomgruber.org/writing/ontolingua-kaj-1993.pdf" target="_blank">Ontologies (PDF)</a></li></li>
+<li>[2] <a name="ref2" href="http://www.w3.org/TR/owl-overview/" target="_blank">The OWL 2 ontology language</a></li></li>
+</ul>
+<hr />
+<p><em><a href="../components.html">Back to components</a></em></p>
+  </div>
+  
+  <div id="footer">
+    <div class="copyright">
+      <p>
+        Copyright &copy; 2010 The Apache Software Foundation, Licensed under 
+        the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+        <br />
+        Apache, Stanbol and the Apache feather and Stanbol logos are trademarks of The Apache Software Foundation.
+      </p>
+    </div>
+  </div>
+  
+</body>
+</html>

Added: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/ontologymanager/ontonet/index.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/ontologymanager/ontonet/index.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/ontologymanager/ontonet/index.html Mon Jul 16 13:02:45 2012
@@ -0,0 +1,310 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements.  See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE- 2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+
+  <link href="/stanbol/css/stanbol.css" rel="stylesheet" type="text/css">
+  <title>Apache Stanbol - Ontology Network Manager (OntoNet)</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+  <link rel="icon" type="image/png" href="/stanbol/images/stanbol-logo/stanbol-favicon.png"/>
+  <script type="text/javascript">
+    // Google Analytics Tracking Code
+    var _gaq = _gaq || [];
+    _gaq.push(['_setAccount', 'UA-32086816-1']);
+    _gaq.push(['_trackPageview']);
+
+    (function() {
+      var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+      ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+      var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+    })();
+  </script>  
+</head>
+
+<body>
+  <div id="logo"> <!-- do not scroll the logo -->
+  <a href="/stanbol/index.html"><img alt="Apache Stanbol" width="220" height="101" border="0" src="/stanbol/images/stanbol-logo/stanbol-2010-12-14.png"/></a></div>
+  <div id="navigation"> <!-- but auto scroll the menue -->
+      <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</a></li>
+</ul>
+<h1 id="project">Project</h1>
+<ul>
+<li><a href="/stanbol/docs/trunk/mailinglists.html">Mailing Lists</a></li>
+<li><a href="https://issues.apache.org/jira/browse/STANBOL">Issue Tracker</a></li>
+<li><a href="/stanbol/team.html">Project Team</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</a></li>
+</ul>
+<h1 id="the-asf">The ASF</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+  </div>
+  <div id="content">
+    <div class="breadcrump" style="font-size: 80%;">
+      <a href="/">Home</a>&nbsp;&raquo&nbsp;<a href="/stanbol/">Stanbol</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/">Docs</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/trunk/">Trunk</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/trunk/components/">Components</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/trunk/components/ontologymanager/">Ontologymanager</a>&nbsp;&raquo&nbsp;<a href="/stanbol/docs/trunk/components/ontologymanager/ontonet/">Ontonet</a>
+    </div>
+    <h1 class="title">Ontology Network Manager (OntoNet)</h1>
+    <h2 id="terminology">Terminology</h2>
+<p>Stanbol OntoNet implements the API section for managing OWL and OWL2 ontologies, in order to prepare them for consumption by reasoning services, refactorers, rule engines and the like. Ontology management in OntoNet is sparse and not connected: once loaded internally from their remote locations, ontologies live and are known within the realm they were loaded in. This allows loose-coupling and (de-)activation of ontologies in order to scale the data sets for reasoners to process and optimize them for efficiency. </p>
+<p><center>
+    <figure>
+      <img width="500px" src="../../../../images/ontologymanager/ontonet.png" alt="OntoNet ontology network structure">
+      <figcaption>Figure 1: an example of OntoNet setup for multiple ontology networks, showing the orthogonal layering of sessions, scopes and spaces.</figcaption>
+    <figure>
+  </center></p>
+<p>The following concepts have been introduced with OntoNet:</p>
+<ul>
+<li>
+<p><strong>Ontology scope</strong>: a "logical realm" for all the ontologies that encompass a certain CMS-related set of concepts (such as "User", "ACL", "Event", "Content", "Domain", "Reengineering", "Community", "Travelling" etc.). Scopes never inherit from each other, though they can load the same ontologies if need be.</p>
+</li>
+<li>
+<p><strong>Ontology space</strong>: an access-restricted container for synchronized access to ontologies within a scope. The ontologies in a scope are loaded within its set of spaces. An ontology scope contains: (a) one core space, which contains the immutable set of essential ontologies that describe the scope; (b) one (possibly empty) custom space, which extends the core space according to specific CMS needs (e.g. the core space for the User scope may contains alignments to FOAF).</p>
+</li>
+<li>
+<p>Session: a container of (supposedly volatile) semantic data which need to be intercrossed with one or more Scopes, for stateful management of ontology networks. It can be used to load instances and reason on them using different models (one per scope). An OntoNet Session is not equivalent to an HTTP session (since it can live persistently across multiple HTTP sessions), although its behaviour can reflect the one of the HTTP session that created it, if required by the implementation.</p>
+</li>
+</ul>
+<hr />
+<h2 id="usage">Usage</h2>
+<p>Given the entire knowledge base managed by your CMS, OntoNet allows the construction and management of ontology networks, programmatically via its Java API or RESTful Web Services <em>(see next section for details on the latter)</em>. A criterion for choosing the appropriate API can be as follows:</p>
+<ul>
+<li>
+<p>Stanbol plugins or server software that incorporates Stanbol (e.g. larger OSGi platforms) should use the Java API.</p>
+</li>
+<li>
+<p>Client applications, non-Java CMSs or services decoupled from Stanbol should use the RESTful API.</p>
+</li>
+<li>
+<p>Java-based CMSs can use either API.</p>
+</li>
+</ul>
+<h3 id="java-api">Java API</h3>
+<p>First and foremost, the concept of <strong>ontology network</strong> is implicit in the OntoNet API. There is no such thing as an <code>OntologyNetwork</code> type. What you do is create <code>OntologyScope</code> and <code>Session</code> objects and link them together at creation time or when launching a process.</p>
+<h4 id="accessing-the-managers">Accessing the managers.</h4>
+<p>First and foremost let us obtain references to the main OntoNet manager classes. In an OSGi environment they can be obtained by reference:</p>
+<div class="codehilite"><pre><span class="nv">@Reference</span>
+<span class="n">ONManager</span> <span class="n">onMgr</span><span class="p">;</span>
+
+<span class="nv">@Reference</span>
+<span class="n">SessionManager</span> <span class="n">sesMgr</span><span class="p">;</span>
+</pre></div>
+
+
+<p>In a non-OSGi environment they must be instantiated as POJOs (Plain Old Java Objects):</p>
+<div class="codehilite"><pre><span class="n">TODO</span>
+</pre></div>
+
+
+<h4 id="managing-an-ontology-scope">Managing an ontology scope.</h4>
+<p>Let us now show an example of how to setup an ontology scope, which you should use for storing the models for a certain domain of your knowledge base. In this example we will refer to social networks and communities.</p>
+<div class="codehilite"><pre><span class="n">ScopeRegistry</span> <span class="n">registry</span> <span class="o">=</span> <span class="n">onMgr</span><span class="o">.</span><span class="n">getScopeRegistry</span><span class="p">();</span>
+<span class="n">OntologyScopeFactory</span> <span class="n">factory</span> 
+  <span class="o">=</span> <span class="n">onMgr</span><span class="o">.</span><span class="n">getOntologyScopeFactory</span><span class="p">();</span>
+
+<span class="o">/*</span>
+ <span class="o">*</span> <span class="n">Here</span> <span class="n">we</span> <span class="n">create</span> <span class="n">a</span> <span class="n">scope</span> <span class="n">called</span> <span class="s">&quot;social&quot;</span> <span class="n">where</span> <span class="n">we</span> <span class="n">intend</span> 
+ <span class="o">*</span> <span class="n">to</span> <span class="n">place</span> <span class="n">all</span> <span class="n">the</span> <span class="n">knowledge</span> <span class="n">needed</span> <span class="k">for</span> <span class="n">modeling</span> <span class="n">social</span> 
+ <span class="o">*</span> <span class="n">networks</span> <span class="ow">and</span> <span class="n">communities</span><span class="o">.</span>
+ <span class="o">*</span>
+ <span class="o">*</span> <span class="n">Suppose</span> <span class="n">the</span> <span class="n">FOAF</span> <span class="ow">and</span> <span class="n">SIOC</span> <span class="n">ontologies</span> <span class="n">are</span> <span class="n">the</span> <span class="n">only</span> <span class="n">ones</span> 
+ <span class="o">*</span> <span class="n">we</span> <span class="n">are</span> <span class="n">concerned</span> <span class="n">with</span> <span class="n">at</span> <span class="n">scope</span> <span class="n">creation</span> <span class="nb">time</span><span class="o">.</span> <span class="n">We</span> <span class="nb">tell</span> 
+ <span class="o">*</span> <span class="n">the</span> <span class="n">scope</span> <span class="n">factory</span> <span class="n">method</span> <span class="n">to</span> <span class="n">fetch</span> <span class="n">them</span> <span class="n">from</span> <span class="n">their</span> 
+ <span class="o">*</span> <span class="n">original</span> <span class="n">locations</span> <span class="n">on</span> <span class="n">the</span> <span class="n">Web</span><span class="o">.</span>
+ <span class="o">*/</span>
+<span class="n">try</span> <span class="p">{</span>
+
+  <span class="o">/*</span> 
+   <span class="o">*</span> <span class="n">You</span> <span class="n">can</span> <span class="n">include</span> <span class="n">as</span> <span class="n">many</span> <span class="n">ontology</span> <span class="n">input</span> <span class="n">source</span> <span class="n">as</span> 
+   <span class="o">*</span> <span class="n">you</span> <span class="n">want</span><span class="p">,</span> <span class="n">even</span> <span class="n">none</span> <span class="n">at</span> <span class="n">all</span><span class="o">.</span>
+   <span class="o">*/</span>
+  <span class="n">OntologyScope</span> <span class="n">scope</span> <span class="o">=</span> <span class="n">factory</span><span class="o">.</span><span class="n">createOntologyScope</span><span class="p">(</span>
+    <span class="s">&quot;social&quot;</span><span class="p">,</span> 
+    <span class="k">new</span> <span class="n">RootOntologyIRISource</span><span class="p">(</span>
+      <span class="n">IRI</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="s">&quot;http://xmlns.com/foaf/spec/index.rdf&quot;</span><span class="p">)),</span>
+    <span class="k">new</span> <span class="n">RootOntologyIRISource</span><span class="p">(</span>
+      <span class="n">IRI</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="s">&quot;http://rdfs.org/sioc/ns&quot;</span><span class="p">)));</span>
+
+  <span class="o">/*</span>
+   <span class="o">*</span> <span class="n">Setup</span> <span class="n">the</span> <span class="n">scope</span><span class="p">,</span> <span class="n">so</span> <span class="n">its</span> <span class="n">ontologies</span> <span class="n">will</span> <span class="n">be</span> <span class="n">available</span> 
+   <span class="o">*</span> <span class="n">via</span> <span class="n">the</span> <span class="n">RESTful</span> <span class="n">API</span>
+   <span class="o">*/</span>
+  <span class="sr">//</span> <span class="n">Lock</span> <span class="n">the</span> <span class="n">ontology</span> <span class="n">scope</span> 
+  <span class="n">scope</span><span class="o">.</span><span class="n">setUp</span><span class="p">();</span> 
+  <span class="sr">//</span> <span class="n">Register</span> <span class="n">the</span> <span class="n">scope</span> <span class="ow">and</span> <span class="n">activate</span> <span class="n">it</span>
+  <span class="n">registry</span><span class="o">.</span><span class="n">registerScope</span><span class="p">(</span><span class="n">scope</span><span class="p">,</span> <span class="n">true</span><span class="p">);</span> 
+<span class="p">}</span> <span class="n">catch</span> <span class="p">(</span><span class="n">OWLOntologyCreationException</span> <span class="n">e1</span><span class="p">)</span> <span class="p">{</span>
+  <span class="o">/*</span> 
+   <span class="o">*</span> <span class="n">Thrown</span> <span class="k">if</span> <span class="n">there</span> <span class="n">was</span> <span class="n">an</span> <span class="n">error</span> <span class="n">creating</span> <span class="n">one</span> <span class="n">of</span> <span class="n">the</span> 
+   <span class="o">*</span> <span class="n">ontology</span> <span class="n">sources</span> <span class="p">(</span><span class="n">e</span><span class="o">.</span><span class="n">g</span><span class="o">.</span> <span class="k">if</span> <span class="n">some</span> <span class="n">URL</span> <span class="n">could</span> <span class="ow">not</span> <span class="n">be</span> 
+   <span class="o">*</span> <span class="n">resolved</span> <span class="ow">or</span> <span class="n">it</span> <span class="n">is</span> <span class="ow">not</span> <span class="n">an</span> <span class="n">ontology</span><span class="o">.</span>
+   <span class="o">*/</span>
+  <span class="n">e1</span><span class="o">.</span><span class="n">printStackTrace</span><span class="p">();</span>
+<span class="p">}</span> <span class="n">catch</span> <span class="p">(</span><span class="n">DuplicateIDException</span> <span class="n">e1</span><span class="p">)</span> <span class="p">{</span>
+  <span class="o">/*</span>
+   <span class="o">*</span> <span class="n">Thrown</span> <span class="k">if</span> <span class="n">there</span> <span class="n">is</span> <span class="n">already</span> <span class="n">a</span> <span class="n">scope</span> <span class="n">called</span> <span class="s">&quot;social&quot;</span><span class="o">.</span>
+   <span class="o">*</span> <span class="n">In</span> <span class="n">this</span> <span class="k">case</span> <span class="n">we</span> <span class="n">may</span> <span class="n">decide</span> <span class="n">to</span> <span class="k">use</span> <span class="n">the</span> <span class="n">existing</span> <span class="n">one</span><span class="p">,</span> 
+   <span class="o">*</span> <span class="n">so</span> <span class="n">we</span> <span class="n">get</span> <span class="n">it</span><span class="o">.</span> <span class="n">Note</span> <span class="n">that</span> <span class="n">wen</span> <span class="n">reusing</span> <span class="n">a</span> <span class="n">scope</span><span class="p">,</span> <span class="n">you</span>
+   <span class="o">*</span> <span class="n">lose</span> <span class="n">the</span> <span class="n">provilege</span> <span class="n">of</span> <span class="n">writing</span> <span class="n">in</span> <span class="n">its</span> <span class="n">core</span> <span class="n">space</span><span class="o">.</span>
+   <span class="o">*</span> <span class="n">Only</span> <span class="n">the</span> <span class="n">custom</span> <span class="n">space</span> <span class="n">will</span> <span class="n">be</span> <span class="nb">open</span> <span class="k">for</span> <span class="n">modification</span><span class="o">.</span>
+   <span class="o">*/</span>
+  <span class="n">scope</span> <span class="o">=</span> <span class="n">registry</span><span class="o">.</span><span class="n">getScope</span><span class="p">(</span><span class="s">&quot;social&quot;</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>If you have not changed any parameters in the OntoNet configuration and have the Ontology Manager Web Service endpoint up and running, you should be able to fetch an RDF file at <code>http://localhost:8080/ontonet/ontology/social</code>. Let us check it (in Turtle Syntax):</p>
+<div class="codehilite"><pre><span class="c">% curl -H &quot;Accept: application/turtle&quot; http://localhost:8080/ontonet/ontology/social</span>
+
+<span class="p">@</span><span class="n">prefix</span> <span class="n">xsd</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">w3</span><span class="p">.</span><span class="n">org</span><span class="o">/</span>2001<span class="o">/</span><span class="n">XMLSchema</span>#<span class="o">&gt;</span> <span class="p">.</span>
+<span class="p">@</span><span class="n">prefix</span> <span class="n">owl</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">w3</span><span class="p">.</span><span class="n">org</span><span class="o">/</span>2002<span class="o">/</span>07<span class="o">/</span><span class="n">owl</span>#<span class="o">&gt;</span> <span class="p">.</span>
+<span class="p">@</span><span class="n">prefix</span> <span class="p">:</span> 
+  <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="p">:</span>8080<span class="o">/</span><span class="n">ontonet</span><span class="o">/</span><span class="n">ontology</span><span class="o">/</span><span class="n">social</span>#<span class="o">&gt;</span> <span class="p">.</span>
+<span class="p">@</span><span class="n">prefix</span> <span class="n">xml</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">w3</span><span class="p">.</span><span class="n">org</span><span class="o">/</span><span class="n">XML</span><span class="o">/</span>1998<span class="o">/</span><span class="n">namespace</span><span class="o">&gt;</span> <span class="p">.</span>
+<span class="p">@</span><span class="n">prefix</span> <span class="n">rdf</span><span class="p">:</span> 
+  <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">w3</span><span class="p">.</span><span class="n">org</span><span class="o">/</span>1999<span class="o">/</span>02<span class="o">/</span>22<span class="o">-</span><span class="n">rdf</span><span class="o">-</span><span class="n">syntax</span><span class="o">-</span><span class="n">ns</span>#<span class="o">&gt;</span> <span class="p">.</span>
+<span class="p">@</span><span class="n">prefix</span> <span class="n">rdfs</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">w3</span><span class="p">.</span><span class="n">org</span><span class="o">/</span>2000<span class="o">/</span>01<span class="o">/</span><span class="n">rdf</span><span class="o">-</span><span class="n">schema</span>#<span class="o">&gt;</span> <span class="p">.</span>
+<span class="p">@</span><span class="n">base</span> <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="p">:</span>8080<span class="o">/</span><span class="n">ontonet</span><span class="o">/</span><span class="n">ontology</span><span class="o">/</span><span class="n">social</span><span class="o">&gt;</span> <span class="p">.</span>
+
+<span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="p">:</span>8080<span class="o">/</span><span class="n">ontonet</span><span class="o">/</span><span class="n">ontology</span><span class="o">/</span><span class="n">social</span><span class="o">&gt;</span> 
+  <span class="n">rdf</span><span class="p">:</span><span class="n">type</span> <span class="n">owl</span><span class="p">:</span><span class="n">Ontology</span> <span class="p">;</span>
+  <span class="n">owl</span><span class="p">:</span><span class="n">imports</span> 
+    <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="p">:</span>8080<span class="o">/</span><span class="n">ontonet</span><span class="o">/</span><span class="n">ontology</span><span class="o">/</span><span class="n">social</span><span class="o">/</span><span class="n">core</span><span class="o">&gt;</span> <span class="p">.</span>
+</pre></div>
+
+
+<p>Let us take a look at the imported ontology that represents the core space of the "social" scope.</p>
+<div class="codehilite"><pre><span class="c">% curl -H &quot;Accept: application/turtle&quot; http://localhost:8080/ontonet/ontology/social/core</span>
+
+<span class="p">@</span><span class="n">base</span> 
+  <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="p">:</span>8080<span class="o">/</span><span class="n">ontonet</span><span class="o">/</span><span class="n">ontology</span><span class="o">/</span><span class="n">social</span><span class="o">/</span><span class="n">core</span><span class="o">&gt;</span> <span class="p">.</span>
+
+<span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="p">:</span>8080<span class="o">/</span><span class="n">ontonet</span><span class="o">/</span><span class="n">ontology</span><span class="o">/</span><span class="n">social</span><span class="o">/</span><span class="n">core</span><span class="o">&gt;</span> 
+  <span class="n">rdf</span><span class="p">:</span><span class="n">type</span> <span class="n">owl</span><span class="p">:</span><span class="n">Ontology</span> <span class="p">;</span>
+  <span class="n">owl</span><span class="p">:</span><span class="n">imports</span> 
+    <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="p">:</span>8080<span class="o">/</span><span class="n">ontonet</span><span class="o">/</span><span class="n">ontology</span><span class="o">/</span><span class="n">social</span><span class="o">/</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">rdfs</span><span class="p">.</span><span class="n">org</span><span class="o">/</span><span class="n">sioc</span><span class="o">/</span><span class="n">ns</span><span class="o">&gt;</span> <span class="p">,</span>
+    <span class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">localhost</span><span class="p">:</span>8080<span class="o">/</span><span class="n">ontonet</span><span class="o">/</span><span class="n">ontology</span><span class="o">/</span><span class="n">social</span><span class="o">/</span><span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">xmlns</span><span class="p">.</span><span class="n">com</span><span class="o">/</span><span class="n">foaf</span><span class="o">/</span>0<span class="p">.</span>1<span class="o">/&gt;</span> <span class="p">.</span>
+</pre></div>
+
+
+<p>Here are the <code>owl:imports</code> statements for the FOAF and SIOC ontologies, which are hijacked to "internal" versions managed by Stanbol. Of course if a domain namespace other than "http://localhost:8080/" was configured, you will see that one in each import statement. </p>
+<p>Also note that the import statement for FOAF ends with <code>http://xmlns.com/foaf/0.1/</code>, which is different from the IRI we passed to Stanbol <code>http://xmlns.com/foaf/spec/index.rdf</code>. This happens because in the case of FOAF the <em>physical</em> IRI (which must be known a priori) differs from its <em>logical</em> IRI (which identifies the ontology and is discovered only when the ontology is read), and OntoNet tends to privilege the logical IRI when one is found, i.e. when the ontology is not anonymous.</p>
+<p>The FOAF and SIOC ontologies are imported by the core space because they were indicated at <em>creation</em> time.</p>
+<p>Of course it is possible to onbtain a Java object for the ontology using the Java API. Here is how to export an entire scope to an OWL API object of type <code>OWLOntology</code>:</p>
+<div class="codehilite"><pre><span class="o">/*</span>
+ <span class="o">*</span> <span class="n">To</span> <span class="n">obtain</span> <span class="n">the</span> <span class="n">OWLOntology</span><span class="p">,</span> <span class="n">we</span> <span class="n">must</span> <span class="n">specify</span> <span class="n">its</span> <span class="n">class</span> <span class="n">as</span>
+ <span class="o">*</span> <span class="n">a</span> <span class="k">return</span> <span class="n">parameter</span><span class="o">.</span>
+ <span class="o">*</span> <span class="n">We</span> <span class="n">also</span> <span class="n">set</span> <span class="n">the</span> <span class="n">second</span> <span class="n">argument</span> <span class="n">to</span> <span class="n">true</span><span class="p">,</span> <span class="n">to</span> <span class="n">specifiy</span> 
+ <span class="o">*</span> <span class="n">that</span> <span class="n">we</span> <span class="n">want</span> <span class="n">it</span> <span class="n">merged</span> <span class="n">with</span> <span class="n">its</span> <span class="n">imports</span><span class="p">,</span> <span class="n">so</span> <span class="n">that</span> <span class="n">the</span> 
+ <span class="o">*</span> <span class="n">resulting</span> <span class="n">object</span> <span class="n">contains</span> <span class="n">all</span> <span class="n">axioms</span><span class="o">.</span>
+ <span class="o">*/</span>
+<span class="n">OWLOntology</span> <span class="n">scopeAsOWL</span> 
+  <span class="o">=</span> <span class="n">scope</span><span class="o">.</span><span class="n">export</span><span class="p">(</span><span class="n">OWLOntology</span><span class="o">.</span><span class="n">class</span><span class="p">,</span> <span class="n">true</span><span class="p">);</span>
+</pre></div>
+
+
+<p>An scope can be exported either as an OWL API object or as a Clerezza object.</p>
+<div class="codehilite"><pre><span class="o">/*</span>
+ <span class="o">*</span> <span class="n">In</span> <span class="n">Clerezza</span><span class="p">,</span> <span class="n">a</span> <span class="n">Graph</span> <span class="n">is</span> <span class="n">a</span> <span class="n">subclass</span> <span class="n">of</span> <span class="n">TripleCollection</span><span class="p">,</span> 
+ <span class="o">*</span> <span class="n">so</span> <span class="n">it</span> <span class="n">is</span> <span class="n">supported</span> <span class="n">by</span> <span class="n">OntoNet</span><span class="o">.</span> <span class="n">We</span> <span class="n">could</span> <span class="n">also</span> <span class="n">export</span> <span class="n">a</span> 
+ <span class="o">*</span> <span class="n">scope</span> <span class="n">to</span> <span class="n">a</span> <span class="n">MGraph</span> <span class="p">(</span><span class="n">modifiable</span> <span class="n">Graph</span><span class="p">)</span><span class="o">.</span>
+ <span class="o">*/</span>
+<span class="n">Graph</span> <span class="n">scopeAsClerezza</span> <span class="o">=</span> <span class="n">scope</span><span class="o">.</span><span class="n">export</span><span class="p">(</span><span class="n">Graph</span><span class="p">,</span> <span class="n">false</span><span class="p">);</span>
+</pre></div>
+
+
+<h4 id="ontology-input-sources">Ontology input sources.</h4>
+<p>Note that when you add an ontology to a space or session, you pass it an <code>OntologyInputSource</code> object, or more precisely, an <code>OntologyInputSource&lt;O,P&gt;</code>. This is because there can be several ways to obtain an ontology, and those most common are supported in Stanbol. For example, it can be obtained by defererencing a IRI and parsing its source code (in RDF/XML, Turtle, etc.), or by reading an input stream, or taking an already stored RDF graph in the Stanbol store; or it could be an ontology Java object created from scratch. An <strong>Ontology input source</strong> is an object that incorporates (1) the "method" by which an ontology should be accessed; (2) the type of Java object it should create to represent an ontology; (3) where it should store the ontology.</p>
+<ul>
+<li><strong><code>OWLOntology</code> input sources</strong> comply with the OWL API specification <a href="#ref1">[1]</a> and creates objects of type <code>OWLOntology</code> stored in an <em>in-memory</em> <code>OWLOntologyManager</code>. It will be stored persistently once added to an ontology network.<ul>
+<li><code>RootOntologySource</code>. Wraps an already existing <code>OWLOntology</code>, therefore it does not provide a physical IRI.</li>
+<li><code>RootOntologyIRISource</code>. Tries to locate and load an ontology, and its imports, from a given IRI. It can use a custom <code>OWLOntologyManager</code> as a store, and can even override any mappers, in order to force-dereference the IRI.</li>
+<li><code>ParentPathInputSource</code>. Tries to load an ontology from a root <code>File</code>, and will seek its imports among the files in the same directory as the root <code>File</code>. It also allows a custom <code>OWLOntologyManager</code> as a store.
+Loads the ontology source codeWraps an already existing <code>OWLOntology</code>, therefore it does not provide a physical IRI.</li>
+<li><code>BlankOntologySource</code>. Creates an <code>OWLOntology</code> with no ID and no axioms. It can be useful for supplying dummy ontologies to methods that will not admit a null ontology. Note that the blank ontology is not shared: each <code>BlankOntologySource</code> has a distinct blank ontology object, and they are <em>not</em> equal!</li>
+</ul>
+</li>
+<li><strong><code>TripleCollection</code> input sources</strong> comply with the Apache Clerezza API specification, which is also the default native implementation of OntoNet. The resulting ontology is a subtype of <code>TripleCollection</code> (<code>Graph</code> or <code>MGraph</code>) and uses a <code>TcProvider</code> as a store. Depending on the chosen Stanbol storage, it can be pesistent or in-memory. Generally, these input sources take less memory that OWL API counterparts, but do not allow RDF graphs to be managed using the OWL language constructs. Note that any <code>TripleCollection</code> can be exported as an <code>OWLOntology</code> afterwards, once stored.<ul>
+<li><code>GraphContentInputSource</code>. Creates a <code>TripleCollection</code> by reading an input stream, which can be obtained from a file, URL etc. It can use any <code>TcProvider</code> as a store, otherwise it will create an in-memory triple collection, which will be copied to the Stanbol store when adding the ontology to a network. If this <code>TcProvider</code> is the <code>TcManager</code> used by Stanbol, its triples are not copied across.</li>
+<li><code>GraphSource</code>. Wraps an existing <code>TripleCollection</code> object. In general, it does not 'know' where the ontology was stored.</li>
+</ul>
+</li>
+</ul>
+<h3 id="service-endpoints">Service Endpoints</h3>
+<p>The OntoNet RESTful API is structured as follows:</p>
+<p><em>(Please note, that the following links to the actual service endpoints link to a running instance of Apache Stanbol. If you use domains or ports other than "localhost:8080", then please change accordingly)</em></p>
+<h4 id="scopes-ontonetontology">Scopes ("/ontonet/ontology")</h4>
+<ul>
+<li>The endpoint @ <a href="http://localhost:8080/ontonet/ontology">/ontonet/ontology</a> shows an overview (as an RDF graph or HTML document) of all registered ontology scopes.</li>
+<li>An Ontology Scope @ /ontonet/ontology/{scopeId} provides the de-referenceable OWL form of the ontology scope <em>scopeId</em>, inclusive of OWL import statements for the spaces and ontologies therein.</li>
+</ul>
+<h4 id="sessions-ontonetsession">Sessions ("/ontonet/session")</h4>
+<ul>
+<li>The endpoint @ <a href="http://localhost:8080/ontonet/session">/ontonet/session</a> shows an overview (as an RDF graph or HTML document) of all open OntoNet sessions.</li>
+<li>A Session @ /ontonet/session/{sessionId} provides the de-referenceable OWL form of the OntoNet Session <em>sessionId</em>, inclusive of OWL import statements for the ontologies therein.</li>
+</ul>
+<h4 id="managed-ontologies-ontonetontologyid">Managed Ontologies ("ontonet/{ontologyId}")</h4>
+<ul>
+<li>A Managed Ontology @ /ontonet/{ontologyId}, where <em>ontologyId</em> is the full logical IRI that identifies the ontology, provides the RDF form of the ontology with that ID, if that ontology has been stored and is managed by OntoNet (i.e. is in some scope or session).</li>
+</ul>
+<h2 id="references">References:</h2>
+<ul>
+<li>[1] <a name="ref1" href="http://owlapi.sourceforge.net" target="_blank">OWL API</a></li></li>
+</ul>
+<hr />
+<p><em><a href="../">Back to Ontology Manager</a></em></p>
+  </div>
+  
+  <div id="footer">
+    <div class="copyright">
+      <p>
+        Copyright &copy; 2010 The Apache Software Foundation, Licensed under 
+        the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+        <br />
+        Apache, Stanbol and the Apache feather and Stanbol logos are trademarks of The Apache Software Foundation.
+      </p>
+    </div>
+  </div>
+  
+</body>
+</html>