Author: buildbot
Date: Mon Nov 7 06:03:42 2011
New Revision: 798228
Log:
Staging update by buildbot
Modified:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/reasoners.html
Modified:
websites/staging/stanbol/trunk/content/stanbol/docs/trunk/reasoners.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/reasoners.html
(original)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/reasoners.html
Mon Nov 7 06:03:42 2011
@@ -46,7 +46,265 @@
<div id="content">
<h1 class="title">Reasoners</h1>
-
+ <p>The Stanbol Reasoners component provides a set of services to take
advantage of automatic inference engines.</p>
+<p>The module implements a common api for reasoning services, providing the
possibility to plug different reasoners and configurations in parallel.</p>
+<p>Actually the module includes OWLApi and Jena based abstract services, with
concrete implementations for Jena RDFS, OWL, OWLMini and HermiT reasoning
service.</p>
+<p>The Reasoners module expose a REST endpoint at the following location:</p>
+<div class="codehilite"><pre><span class="n">http:</span><span
class="sr">//</span><span class="n">localhost:8080</span><span
class="o">/</span><span class="n">reasoners</span>
+</pre></div>
+
+
+<p>with the following preloaded services:</p>
+<ul>
+<li>/rdfs, which is based on Jena RDFS reasoner and supports almost all of the
RDFS entailments.</li>
+<li>/owl, a Jena reasoner configured to support OWL (with some
limitations)</li>
+<li>/owlmini, another Jena configuration that partially supports OWL</li>
+</ul>
+<p>In addition, it is also available a service which uses the HermiT reasoner
to exploit the full OWL2 specification.</p>
+<p>Each reasoner can be accessed with one of three tasks:</p>
+<ul>
+<li>check: to perform a consistency check. This service returns HTTP Status
200 if data is consistent, 204 otherwise (at the current state of
implementation the service does not include an explanation about why the input
is inconsistent. This feature is in our �todo� list, by the way)</li>
+<li>classify: to materialize all inferred rdf:type statements.</li>
+<li>enrich: to materialize all inferred statements.</li>
+</ul>
+<p>For example:</p>
+<div class="codehilite"><pre><span class="n">http:</span><span
class="sr">//</span><span class="n">localhost:8080</span><span
class="sr">/reasoners/o</span><span class="n">wl</span><span class="sr">/check
/</span><span class="o">/</span> <span class="n">expose</span> <span
class="n">the</span> <span class="n">Jena</span> <span class="n">owl</span>
<span class="n">service</span> <span class="n">with</span> <span
class="n">task</span> <span class="n">check</span><span class="p">,</span>
<span class="ow">or</span>
+<span class="n">http:</span><span class="sr">//</span><span
class="n">localhost:8080</span><span class="sr">/reasoners/o</span><span
class="n">wl2</span><span class="sr">/classify /</span><span class="o">/</span>
<span class="n">to</span> <span class="k">use</span> <span class="n">the</span>
<span class="n">HermiT</span> <span class="n">service</span> <span
class="n">with</span> <span class="n">task</span> <span
class="n">classify</span>
+</pre></div>
+
+
+<p>We can use the curl command line utility to ask the Jena OWL reasoning
service to materialize all inferences produced by loading the FOAF ontology:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span
class="nv">curl</span> <span class="o">-</span><span class="n">H</span> <span
class="s">"Accept: text/n3"</span> <span
class="s">"http://localhost:8080/stanbol/reasoners/owl/enrich?url=http://xmlns.com/foaf/0.1/"</span>
+</pre></div>
+
+
+<p>The above example performs a GET asking for a <tt>text/n3</tt>
representation of the result. For example, the equivalency of
<tt>foaf:Agent</tt> and <tt>dc:Agent</tt> result in the
<tt>rdfs:subClassOf</tt> statements for the <tt>foaf:Person</tt> type:
+<pre>[...]
+<http://xmlns.com/foaf/0.1/Person>
+ a <http://www.w3.org/2002/07/owl#Thing> ,
+ <http://www.w3.org/2002/07/owl#Class> ,
+ <http://www.w3.org/2000/01/rdf-schema#Resource> ,
+ <http://www.w3.org/2000/01/rdf-schema#Class> ;
+ <http://www.w3.org/2000/01/rdf-schema#label>
+ "Person" ;
+ <http://www.w3.org/2000/01/rdf-schema#subClassOf>
+ <http://xmlns.com/foaf/0.1/Person> ,
+ <http://purl.org/dc/terms/Agent> ,
+ <http://xmlns.com/foaf/0.1/Agent> ,
+ <http://www.w3.org/2002/07/owl#Thing> ,
+ <http://www.w3.org/2000/01/rdf-schema#Resource> ,
+ <http://www.w3.org/2000/10/swap/pim/contact#Person> ,
+ <http://www.w3.org/2003/01/geo/wgs84_pos#SpatialThing> ;
+ <http://www.w3.org/2002/07/owl#disjointWith>
+ <http://xmlns.com/foaf/0.1/Organization> ,
+ <http://xmlns.com/foaf/0.1/Project> ;
+[...]</pre>
+This behaviour is equivalent if we use the method POST with the header
<tt>Content-type: application/x-www-form-urlencoded</tt>. In addition, if the
<tt>target</tt> parameter is provided, the service saves the output in the
given graph in the triple store and does not return the RDF stream.</p>
+<h2 id="differences_between_the_reasoners">Differences between the
reasoners</h2>
+<p>Let's give some example on the differences between the available reasoners
(to try the example ontology snippets you can download them from <a
href="https://github.com/enridaga/reasoners.examples/tree/master/enridaga.reasoners.examples";
target="_blank">here</a>).</p>
+<p>The first snippet uses rdfs:subClassOf to declare that any Article is a
Document, which is in turn a ContentItem.
+<pre>
+<!-- item_1 is an Article -->
+<ex:Article rdf:about="http://www.example.org/reasoners/item_1"/></p>
+<p><!-- An article is a kind of Document -->
+<rdf:Description rdf:about="http://www.example.org/reasoners/Article">
+ <rdfs:subClassOf
rdf:resource="http://www.example.org/reasoners/Document"/>
+</rdf:Description></p>
+<p><!-- An document is a kind of content item -->
+<rdf:Description rdf:about="http://www.example.org/reasoners/Document">
+ <rdfs:subClassOf
rdf:resource="http://www.example.org/reasoners/ContentItem"/>
+</rdf:Description>
+</pre>
+<a
href="https://raw.github.com/enridaga/reasoners.examples/master/enridaga.reasoners.examples/rdfs/subclass.xml";
target="_blank">download it</a></p>
+<p>Giving it to the /rdfs reasoning service, we obtain as resulted inferred
statement that item_1 is also a Document and a ContentItem. Another feature of
RDFS is the definition of the domain and range of a property.
+<pre style="overflow: auto">
+<!-- Both enridaga and alexdma are authors of item_1 -->
+<rdf:Description rdf:about="http://www.example.org/reasoners/enridaga">
+ <ex:author rdf:resource="http://www.example.org/reasoners/item_1"/>
+</rdf:Description>
+<rdf:Description rdf:about="http://www.example.org/reasoners/alexdma">
+ <ex:author rdf:resource="http://www.example.org/reasoners/item_1"/>
+</rdf:Description></p>
+<p><!-- ex:author wants a person as subject, and a content-item as object
-->
+<rdf:Description rdf:about="http://www.example.org/reasoners/author">
+ <rdfs:domain rdf:resource="http://www.example.org/reasoners/Person"/>
+ <rdfs:range
rdf:resource="http://www.example.org/reasoners/ContentItem"/>
+</rdf:Description>
+</pre>
+<a
href="https://raw.github.com/enridaga/reasoners.examples/master/enridaga.reasoners.examples/rdfs/domain-range.xml";
target="_blank">download it</a>
+We will obtain, in this case, that both <tt>enridaga</tt> and <tt>alexdma</tt>
are <tt>Authors</tt>, and that <tt>item_1</tt> is a <tt>ContentItem</tt>. RDFS
semantics is considered also by other reasoners. The <tt>/rdfs</tt> service is
the less "expressive" of the four.</p>
+<p>The following snippet will work with <tt>/owl</tt>, <tt>/owlmini</tt> and
<tt>/owl2</tt> (but not with <tt>/rdfs</tt>):
+<pre style="overflow: auto">
+<!-- ogrisel, enridaga and alexdma are developers -->
+<ex:Developer rdf:about="#enridaga" />
+<ex:Developer rdf:about="#ogrisel" />
+<ex:Developer rdf:about="#alexdma" /></p>
+<p><!-- We know:</p>
+<h1 id="alexdma_workedtogheter_enridaga_and_ogrisel">alexdma #workedTogheter
#enridaga and #ogrisel</h1>
+<p>-->
+<rdf:Description rdf:about="#alexdma">
+<workedTogheter rdf:resource="#ogrisel"/>
+<workedTogheter rdf:resource="#enridaga"/>
+</rdf:Description></p>
+<p><!-- #workedTogheter is an owl:SymmetricProperty (well, this is an
example...) -->
+<owl:SymmetricProperty rdf:about="#workedTogheter"/>
+<!-- #workedTogheter is also a owl:TransitiveProperty (well, this is an
example...) -->
+<owl:TransitiveProperty rdf:about="#workedTogheter"/>
+</pre>
+<a
href="https://raw.github.com/enridaga/reasoners.examples/master/enridaga.reasoners.examples/owlmini/symmetric.xml";
target="_blank">download it</a>
+The OWL vocabulary introduce logical capabilities, allowing more complex
inferences to be produced. In the above example we state that <tt>alexdma
workedWith enridaga</tt> and <tt>ogrisel</tt>. Since we declare the property
<tt>workedTogheter</tt> to be "Symmetric" and "Transitive", the result will
include the following:
+<ul>
+<li><tt>enridaga workedWith alexdma</tt> (is symmetric)</li>
+<li><tt>ogrisel workedWith alexdma</tt></li>
+<li><tt>ogrisel workedWith enridaga</tt> (is transitive)</li>
+<li><tt>enridaga workedWith ogrisel</tt></li>
+</ul></p>
+<p>Next snippet is inconsistent. This means that the OWL based reasoners will
not return any inference, but a 204 HTTP response:
+<pre style="overflow: auto">
+<!-- enridaga is a person -->
+<ex:Person rdf:about="http://www.example.org/reasoners/enridaga"; /></p>
+<p><!-- Persons and Organizations are disjoint -->
+<owl:Class rdf:about="http://www.example.org/reasoners/Person"; />
+<owl:Class rdf:about="http://www.example.org/reasoners/Organization">
+ <owl:disjointWith
rdf:resource="http://www.example.org/reasoners/Person"; />
+</owl:Class></p>
+<p><!-- A Public Limited Company is a kind of Company, which is a kind of
Organization -->
+<owl:Class
rdf:about="http://www.example.org/reasoners/PublicLimitedCompany">
+ <rdfs:subClassOf
rdf:resource="http://www.example.org/reasoners/Company"; />
+</owl:Class>
+<owl:Class rdf:about="http://www.example.org/reasoners/Company">
+ <rdfs:subClassOf
rdf:resource="http://www.example.org/reasoners/Organization"; />
+</owl:Class></p>
+<p><!-- enridaga cannot be a Public Limited Company -->
+<ex:PublicLimitedCompany
rdf:about="http://www.example.org/reasoners/enridaga"; />
+</pre>
+<a
href="https://raw.github.com/enridaga/reasoners.examples/master/enridaga.reasoners.examples/owlmini/inconsistent-types.xml";
target="_blank">download it</a>
+The <tt>/owlmini</tt> implements the OWL language with some (more) limitations
then <tt>/owl</tt> (both are based on the Jena rule based reasoner, as said
before).</p>
+<p>The following example shows the use of class restrictions, in particular
the usage of <tt>owl:someValuesFrom</tt>:
+<pre style="overflow: auto">
+<!-- john, is an developer, but we don't know anything else -->
+<ex:Developer rdf:about="#john">
+</ex:Developer></p>
+<p><!-- a #SoftwareCompany is a kind of #Organization -->
+<owl:Class rdf:about="SoftwareCompany">
+ <rdfs:subClassOf rdf:resource="#Organization" />
+</owl:Class></p>
+<p><!-- #Developers #worksAt some #SoftwareCompany (they are not the only
one...,
+ this is why we use owl:subClassOf) -->
+<owl:Class rdf:about="#Developer">
+ <rdfs:subClassOf>
+ <owl:restriction>
+ <owl:onProperty rdf:resource="#worksAt" />
+ <owl:someValuesFrom rdf:resource="#SoftwareCompany" />
+ </owl:restriction>
+ </rdfs:subClassOf>
+</owl:Class></p>
+<p><!-- Employees are all who #worksAt any kind of Organization
(owl:equivalentClass) -->
+<owl:Class rdf:about="#Employee">
+ <owl:equivalentClass>
+ <owl:restriction>
+ <owl:onProperty rdf:resource="#worksAt" />
+ <owl:someValuesFrom rdf:resource="#Organization" />
+ </owl:restriction>
+ </owl:equivalentClass>
+</owl:Class>
+</pre>
+<a
href="https://raw.github.com/enridaga/reasoners.examples/master/enridaga.reasoners.examples/owl/some-values-from.xml";
target="_blank">download it</a></p>
+<p>We expect an OWL reasoner to state that John is an <tt>Employee</tt>. This
example does not work with <tt>/rdfs</tt> (it ignores the OWL semantics), and
does not work with <tt>/owlmini</tt>, because the Jena OWL(mini) reasoner omits
the forward entailments for <tt>owl:someValuesFrom restrictions</tt> (see [<a
href="#ref4">4</a>]). It works correctly if we use the service
<tt>/owl</tt>.</p>
+<p>The <tt>/owl</tt> service support the most of the semantic of OWL. The
HermiT reasoner is based on <a href="http://owlapi.sourceforge.net/";>OWLApi</a>
and is an example of a DL reasoner. It fully covers OWL and OWL2, which
introduces lot of interesting features. Here is an example:
+<pre style="overflow: auto">
+<!-- any Employee must have some features: firstname, familyname, email
+ and worksAt (in one of the allowed places) -->
+<owl:Class rdf:about="#Employee">
+ <owl:equivalentClass>
+ <owl:Class>
+ <owl:intersectionOf rdf:parseType="Collection">
+ <rdf:Description rdf:about="#Person" />
+ <owl:Restriction>
+ <owl:onProperty rdf:resource="#firstname" />
+ <owl:someValuesFrom rdf:resource="&rdfs;Literal"
/>
+ </owl:Restriction>
+ <owl:Restriction>
+ <owl:onProperty rdf:resource="#familyname" />
+ <owl:someValuesFrom rdf:resource="&rdfs;Literal"
/>
+ </owl:Restriction>
+ <owl:Restriction>
+ <owl:onProperty rdf:resource="#email" />
+ <owl:someValuesFrom rdf:resource="&rdfs;Literal"
/>
+ </owl:Restriction>
+ <!-- -->
+ <!-- Let's say that Employees can work only in #Rome ,
#Catania and
+ #Bologna -->
+ <owl:Restriction>
+ <owl:onProperty rdf:resource="#worksAt" />
+ <owl:someValuesFrom>
+ <owl:Class>
+ <owl:oneOf rdf:parseType="Collection">
+ <owl:Thing rdf:about="#Rome" />
+ <owl:Thing rdf:about="#Catania" />
+ <owl:Thing rdf:about="#Bologna" />
+ </owl:oneOf>
+ </owl:Class>
+ </owl:someValuesFrom>
+ </owl:Restriction>
+ </owl:intersectionOf>
+ </owl:Class>
+ </owl:equivalentClass>
+</owl:Class></p>
+<p><owl:DatatypeProperty rdf:about="#firstname" />
+<owl:DatatypeProperty rdf:about="#familyname" />
+<owl:DatatypeProperty rdf:about="#email" /></p>
+<p><!-- #worksAt has range #Place -->
+<owl:ObjectProperty rdf:about="#worksAt">
+ <rdfs:range rdf:resource="#Place" />
+</owl:ObjectProperty></p>
+<p><!-- all the following places are distinct (no synonyms here) -->
+<owl:AllDifferent>
+ <owl:distinctMembers rdf:parseType="Collection">
+ <owl:Thing rdf:about="#Rome" />
+ <owl:Thing rdf:about="#Catania" />
+ <owl:Thing rdf:about="#Bologna" />
+ <owl:Thing rdf:about="#Moricone" />
+ </owl:distinctMembers>
+</owl:AllDifferent></p>
+<p><!-- enridaga, to be an Employee, must fulfill the restrictions defined
+ for the class #Employee. -->
+<Person rdf:about="#enridaga">
+ <!-- If you comment one of the next 4 statement, you won't have
#enridaga
+ to result as #Employee. -->
+ <firstname>Enrico</firstname>
+ <familyname>Daga</familyname>
+ <email>[email protected]</email>
+ <worksAt rdf:resource="#Catania" /></p>
+<div class="codehilite"><pre><span class="o">&</span><span
class="ow">lt</span><span class="p">;</span><span class="o">!--</span> <span
class="n">If</span> <span class="n">you</span> <span class="n">uncomment</span>
<span class="n">the</span> <span class="n">two</span> <span
class="n">statements</span> <span class="n">below</span> <span
class="n">you</span> <span class="n">will</span> <span class="n">obtain</span>
<span class="n">an</span> <span class="n">inconsistency</span><span
class="p">,</span>
+ <span class="n">because</span> <span class="c1">#Moricone is not an
allowed place for developers --&gt;</span>
+<span class="o">&</span><span class="ow">lt</span><span
class="p">;</span><span class="o">!--</span> <span class="o">&</span><span
class="ow">lt</span><span class="p">;</span><span class="n">worksAt</span>
<span class="n">rdf:resource</span><span class="o">=</span><span
class="s">"#Moricone"</span> <span class="o">/&</span><span
class="ow">gt</span><span class="p">;</span> <span class="o">&</span><span
class="ow">lt</span><span class="p">;</span><span class="n">rdf:type</span>
<span class="n">rdf:resource</span><span class="o">=</span><span
class="s">"#Employee"</span>
+ <span class="o">/&</span><span class="ow">gt</span><span
class="p">;</span> <span class="o">--&</span><span
class="ow">gt</span><span class="p">;</span>
+</pre></div>
+
+
+<p></Person>
+</pre>
+<a
href="https://raw.github.com/enridaga/reasoners.examples/master/enridaga.reasoners.examples/owl2/class-restrictions-owl2.xml";
target="_blank">download it</a></p>
+<p>The above differences depend on the semantic supported by the specific
reasoner and from the implementation, which limit the power of the system in
favour of a better efficiency (is the case of the <tt>/owlmini</tt>
implementation of Jena, more efficient then the respective <tt>/owl</tt>). If
you need to work with RDFS semantic, and don't need OWL for your inferences,
just use the RDFS one.</p>
+<h2 id="build_and_install">Build and install</h2>
+<p>Run Stanbol, for example:</p>
+<p>% java -jar -Xmx1g
org.apache.stanbol.launchers.full-0.9.0-incubating-SNAPSHOT.jar</p>
+<p>You must have the Ontonet and Rules modules already installed (they are if
you have followed the above example).
+Move to the /reasoners directory, then run</p>
+<p>% mvn install -PinstallBundle -Dsling.url=<the path to your running Felix
administration console></p>
+<p>for example</p>
+<p>% mvn install -PinstallBundle http://localhost:8080/system/console</p>
+<h3 id="add_the_hermit_reasoner">Add the HermiT reasoner</h3>
+<p>To enable HermiT as OWL2 reasoner you can download and install it from the
Stanbol (Incubating) svn repository. The steps are the following:</p>
+<div class="codehilite"><pre><span class="nv">$</span> <span
class="nv">svn</span> <span class="n">co</span> <span
class="n">https:</span><span class="sr">//s</span><span
class="n">vn</span><span class="o">.</span><span class="n">apache</span><span
class="o">.</span><span class="n">org</span><span
class="sr">/repos/</span><span class="n">asf</span><span
class="sr">/incubator/s</span><span class="n">tanbol</span><span
class="sr">/trunk/</span><span class="n">reasoners</span><span
class="o">/</span><span class="n">hermit</span> <span
class="n">stanbol</span><span class="o">-</span><span class="n">hermit</span>
+<span class="nv">$</span> <span class="nv">cd</span> <span
class="n">stanbol</span><span class="o">-</span><span class="n">hermit</span>
+<span class="nv">$</span> <span class="nv">mvn</span> <span
class="n">install</span> <span class="o">-</span><span
class="n">PinstallBundle</span> <span class="o">-</span><span
class="n">Dsling</span><span class="o">.</span><span class="n">url</span><span
class="o">=</span><span class="n">http:</span><span class="sr">//</span><span
class="n">localhost:8080</span><span class="sr">/system/co</span><span
class="n">nsole</span> <span class="sr">//</span> <span class="n">change</span>
<span class="n">this</span> <span class="n">to</span> <span
class="n">the</span> <span class="n">path</span> <span class="n">related</span>
<span class="n">to</span> <span class="n">your</span> <span
class="n">Stanbol</span> <span class="n">instance</span>
+</pre></div>
+
+
+<hr />
+<p><em><a href="index.html">Back to index</a></em></p>
</div>
<div id="footer">
