Author: enridaga
Date: Fri Nov 4 17:09:55 2011
New Revision: 1197671
URL: http://svn.apache.org/viewvc?rev=1197671&view=rev
Log:
Readding the most of the markup code deleted before (STANBOL-373)
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/reasoners.mdtext
Modified:
incubator/stanbol/site/trunk/content/stanbol/docs/trunk/reasoners.mdtext
URL:
http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/reasoners.mdtext?rev=1197671&r1=1197670&r2=1197671&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/reasoners.mdtext
(original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/reasoners.mdtext
Fri Nov 4 17:09:55 2011
@@ -33,6 +33,261 @@ We can use the curl command line utility
$ curl -H "Accept: text/n3"
"http://localhost:8080/stanbol/reasoners/owl/enrich?url=http://xmlns.com/foaf/0.1/";
+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.
+
+## Differences between the reasoners
+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>).
+
+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"/>
+
+<!-- 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>
+
+<!-- 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>
+
+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>
+
+<!-- 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.
+
+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" />
+
+<!-- We know:
+#alexdma #workedTogheter #enridaga and #ogrisel
+-->
+<rdf:Description rdf:about="#alexdma">
+<workedTogheter rdf:resource="#ogrisel"/>
+<workedTogheter rdf:resource="#enridaga"/>
+</rdf:Description>
+
+<!-- #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>
+
+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"; />
+
+<!-- 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>
+
+<!-- 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>
+
+<!-- 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).
+
+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>
+
+<!-- a #SoftwareCompany is a kind of #Organization -->
+<owl:Class rdf:about="SoftwareCompany">
+ <rdfs:subClassOf rdf:resource="#Organization" />
+</owl:Class>
+
+<!-- #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>
+
+<!-- Employers are all who #worksAt any kind of Organization
(owl:equivalentClass) -->
+<owl:Class rdf:about="#Employer">
+ <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>
+
+We expect an OWL reasoner to state that John is an <tt>Employer</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>.
+
+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 employer must have some features: firstname, familyname, email
+ and worksAt (in one of the allowed places) -->
+<owl:Class rdf:about="#Employer">
+ <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 Employers 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>
+
+<owl:DatatypeProperty rdf:about="#firstname" />
+<owl:DatatypeProperty rdf:about="#familyname" />
+<owl:DatatypeProperty rdf:about="#email" />
+
+<!-- #worksAt has range #Place -->
+<owl:ObjectProperty rdf:about="#worksAt">
+ <rdfs:range rdf:resource="#Place" />
+</owl:ObjectProperty>
+
+<!-- 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>
+
+
+<!-- enridaga, to be an employer, must fulfill the restrictions defined
+ for the class #Employer. -->
+<Person rdf:about="#enridaga">
+ <!-- If you comment one of the next 4 statement, you won't have
#enridaga
+ to result as #Employer. -->
+ <firstname>Enrico</firstname>
+ <familyname>Daga</familyname>
+ <email>[email protected]</email>
+ <worksAt rdf:resource="#Catania" />
+
+ <!-- If you uncomment the two statements below you will obtain an
inconsistency,
+ because #Moricone is not an allowed place for developers -->
+ <!-- <worksAt rdf:resource="#Moricone" /> <rdf:type
rdf:resource="#Employer"
+ /> -->
+</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>
+
+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.
+## Build and install
+Run Stanbol, for example:
+
+ % java -jar -Xmx1g
org.apache.stanbol.launchers.full-0.9.0-incubating-SNAPSHOT.jar
+
+
+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
+
+ % mvn install -PinstallBundle -Dsling.url=<the path to your running Felix
administration console>
+
+for example
+
+ % mvn install -PinstallBundle http://localhost:8080/system/console
+
+### Add the HermiT reasoner
+
+To enable HermiT as OWL2 reasoner you can download and install it from the
Stanbol (Incubating) svn repository. The steps are the following:
+
+ $ svn co
https://svn.apache.org/repos/asf/incubator/stanbol/trunk/reasoners/hermit
stanbol-hermit
+ $ cd stanbol-hermit
+ $ mvn install -PinstallBundle
-Dsling.url=http://localhost:8080/system/console // change this to the path
related to your Stanbol instance
+
____
