Permalink
Browse files

Documentation update for 0.6 release

  • Loading branch information...
1 parent d1658c3 commit abf747cd09b9668b7d2ded2ad6ca2cc744b62a75 fatorange committed Feb 16, 2009
Showing with 126 additions and 17 deletions.
  1. +126 −17 doc/manual/index.htm
View
143 doc/manual/index.htm
@@ -1,6 +1,6 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<?xml version="1.0" encoding="utf-8"?><HTML lang=en xml:lang="en"
-xmlns="http://www.w3.org/1999/xhtml"><HEAD><TITLE>The D2RQ Plattform v0.5.1 - User Manual</TITLE>
+xmlns="http://www.w3.org/1999/xhtml"><HEAD><TITLE>The D2RQ Plattform v0.6 - User Manual</TITLE>
<META http-equiv=Content-Type content="text/html; charset=utf-8">
<STYLE type=text/css>
@@ -131,12 +131,12 @@
</HEAD>
<BODY>
<DIV class=head>
- <h1 id=title>The D2RQ Platform v0.5.1 - Treating Non-RDF Relational Databases as Virtual RDF Graphs</h1>
+ <h1 id=title>The D2RQ Platform v0.6 - Treating Non-RDF Relational Databases as Virtual RDF Graphs</h1>
<h2 id=doctype>User Manual and Language Specification</h2>
<DL>
<DT>This Version:
<DD><A
- href="http://www.wiwiss.fu-berlin.de/suhl/bizer/d2rq/spec/20071025/">http://www.wiwiss.fu-berlin.de/suhl/bizer/d2rq/spec/20071025/</A>
+ href="http://www.wiwiss.fu-berlin.de/suhl/bizer/d2rq/spec/20090217/">http://www.wiwiss.fu-berlin.de/suhl/bizer/d2rq/spec/20090217/</A>
<DT>Latest Version:
<DD><A
href="http://www.wiwiss.fu-berlin.de/suhl/bizer/d2rq/spec/">http://www.wiwiss.fu-berlin.de/suhl/bizer/d2rq/spec/</A>
@@ -152,6 +152,9 @@ <h2 id=doctype>User Manual and Language Specification</h2>
<DD>
<DD><a href="http://www.oliver-maresch.de/" target="_blank">Oliver Maresch</a> (Technische Universit&auml;t Berlin, Germany)
<DD>
+ <DD>
+ <DD><a href="http://beckr.org/" target="_blank">Christian Becker</a> (Freie Universit&auml;t Berlin, Germany)
+ <DD>
<DT>
</DL>
<P>&nbsp;</P>
@@ -198,11 +201,12 @@ <h2 id="toc">Table of Contents</h2>
<li>7.1. <a href="#database">d2rq:Database</a></li>
<li>7.2. <a href="#classmap">d2rq:ClassMap</a></li>
<li>7.3. <a href="#propertybridge">d2rq:PropertyBridge</a></li>
- <li>7.4. <a href="#additionalproperty">d2rq:AdditionalProperty</a></li>
- <li>7.5. <a href="#translationtable">d2rq:TranslationTable</a></li>
- <li>7.6. <a href="#conditional">Conditional Mappings</a></li>
- <li>7.7. <a href="#hint">Performance Optimization using Hint Properties</a></li>
- <li>7.8. <a href="#deprecated">Deprecated Language Constructs</a></li>
+ <li>7.4. <a href="#configuration">d2rq:Configuration</a></li>
+ <li>7.5. <a href="#additionalproperty">d2rq:AdditionalProperty</a></li>
+ <li>7.6. <a href="#translationtable">d2rq:TranslationTable</a></li>
+ <li>7.7. <a href="#conditional">Conditional Mappings</a></li>
+ <li>7.8. <a href="#hint">Performance Optimization using Hint Properties</a></li>
+ <li>7.9. <a href="#deprecated">Deprecated Language Constructs</a></li>
</ul>
</li>
<li>8. <a href="#change_log">Change Log</a></li>
@@ -950,6 +954,21 @@ <h1 id="specification">7. Language Specification</h1>
data which is older or newer than a certain date. See section <a href="#conditional">Conditional
Mappings</a> for details.</td>
</tr>
+ <tr>
+ <td valign="top"><strong>d2rq:classDefinitionLabel</strong></td>
+ <td valign="top">Specifies a label that will be served as <tt>rdfs:label</tt>
+ for all associated class definitions. Multiple lables, e.g. in several languages, are supported.</td>
+ </tr>
+ <tr>
+ <td valign="top"><strong>d2rq:classDefinitionComment</strong></td>
+ <td valign="top">Specifies a comment that will be served as <tt>rdfs:comment</tt>
+ for all associated class definitions. Multiple comments are supported.</td>
+ </tr>
+ <tr>
+ <td valign="top"><strong>d2rq:additionalClassDefinitionProperty</strong></td>
+ <td valign="top">Adds an <a href="#additionalproperty">AdditionalProperty</a>
+ to all associated class definitions.</td>
+ </tr>
</table>
<P><strong>ClassMap property:</strong></P>
<table width="100%" border="1" cellpadding="5" cellspacing="0" bordercolor="#CCCCCC">
@@ -964,6 +983,8 @@ <h1 id="specification">7. Language Specification</h1>
<pre>map:PaperClassMap a d2rq:ClassMap;
d2rq:uriPattern &quot;http://www.conference.org/conf02004/paper#Paper@@Papers.PaperID@@&quot;;
d2rq:class :Paper;
+ d2rq:classDefinitionLabel "paper"@en;
+ d2rq:classDefinitionComment "A conference paper."@en;
d2rq:dataStorage map:Database1.</pre>
<P>The d2rq:class property is used to state that all resources generated by the
d2rq:ClassMap are instances of an RDFS or OWL class. D2RQ automatically creates
@@ -973,6 +994,8 @@ <h1 id="specification">7. Language Specification</h1>
<pre>map:Topic a d2rq:ClassMap ;
d2rq:bNodeIdColumns &quot;Topics.TopicID&quot; ;
d2rq:class :Topic ;
+ d2rq:classDefinitionLabel "topic"@en;
+ d2rq:classDefinitionComment "A topic."@en;
d2rq:dataStorage map:Database1 .</pre>
<p>In order to recognize bNodes across several find() calls and to be able to
@@ -1147,6 +1170,21 @@ <h1 id="specification">7. Language Specification</h1>
in the database. See section <a href="#hint">Performance Optimization</a>
for details.</td>
</tr>
+ <tr>
+ <td valign="top"><strong>d2rq:propertyDefinitionLabel</strong></td>
+ <td valign="top">Specifies a label that will be served as <tt>rdfs:label</tt>
+ for all associated property definitions. Multiple lables, e.g. in several languages, are supported.</td>
+ </tr>
+ <tr>
+ <td valign="top"><strong>d2rq:propertyDefinitionComment</strong></td>
+ <td valign="top">Specifies a comment that will be served as <tt>rdfs:comment</tt>
+ for all associated property definitions. Multiple comments are supported.</td>
+ </tr>
+ <tr>
+ <td valign="top"><strong>d2rq:additionalPropertyDefinitionProperty</strong></td>
+ <td valign="top">Adds an <a href="#additionalproperty">AdditionalProperty</a>
+ to all associated property definitions.</td>
+ </tr>
</table>
<P><strong>PropertyBridge property:</strong></P>
@@ -1167,6 +1205,8 @@ <h1 id="specification">7. Language Specification</h1>
d2rq:property :title;
d2rq:column &quot;Papers.Title&quot;;
d2rq:lang "en";
+ d2rq:propertyDefinitionLabel "title"@en;
+ d2rq:propertyDefinitionComment "A paper's title."@en;
.</pre>
<p>This attaches a <tt>:title</tt> property to all resources generated
by the <tt>map:Paper</tt> class map. The property values are
@@ -1182,6 +1222,8 @@ <h1 id="specification">7. Language Specification</h1>
d2rq:join &quot;Papers.PaperID = Rel_Person_Paper.PaperID&quot;;
d2rq:join &quot;Rel_Person_Paper.PersonID = Persons.PerID&quot;;
d2rq:datatype xsd:string;
+ d2rq:propertyDefinitionLabel "name"@en;
+ d2rq:propertyDefinitionComment "Name of an author."@en;
.</pre>
<p>This property bridge adds the names of authors to papers.
If a paper has several authors, then several <tt>:authorName</tt>
@@ -1280,7 +1322,70 @@ <h1 id="specification">7. Language Specification</h1>
<p>This adds an <tt>rdfs:seeAlso</tt> statement with a fixed URL object
to every instance of the <tt>map:PersonsClassMap</tt> class map.</p>
-<h2><a name="translationtable"></a>7.5 Translation Tables</h2>
+<h2><a name="configuration"></a>7.4 Configuration</h2>
+
+<p>The optional <tt>d2rq:Configuration</tt> block allows to modify the global behavior of D2RQ.
+ It currently has one property, <tt>d2rq:serveVocabulary</tt>.</p>
+
+<a name="serveVocabulary"></a><h3>7.4.1 serveVocabulary</h3>
+<p><tt>d2rq:serveVocabulary</tt> controls whether vocabulary data is provided in graphs (boolean value; defaults to <tt>true</tt>).</p>
+<p>In the spirit of <a href="http://www.w3.org/DesignIssues/LinkedData.html">Linked Data</a>, vocabulary data should be dereferencable by clients. D2RQ infers types of classes and properties as <tt>rdfs:Class</tt> and <tt>rdf:Property</tt> and allows the user to provide labels
+using the <tt>d2rq:classDefinitionLabel</tt> and <tt>d2rq:propertyDefinitionLabel</tt> constructs,
+comments using the <tt>d2rq:classDefinitionComment</tt> and <tt>d2rq:propertyDefinitionComment</tt> constructs,
+as well as additional properties using the <tt>d2rq:additionalClassDefinitionProperty</tt> and <tt>d2rq:additionalPropertyDefinitionProperty</tt> constructs.</p>
+
+<P><strong>Example: Deactivating vocabulary serving</strong></P>
+ <pre>map:Configuration a d2rq:Configuration;
+ d2rq:serveVocabulary false.</pre>
+
+<h2><a name="additionalproperty"></a>7.5 AdditionalProperty</h2>
+<p>A <strong>d2rq:AdditionalProperty</strong> can be used to add a fixed statement
+ to all class definitions of a class map, or to all property definitions of a property bridge.
+ The statement is added to the result sets, if patterns like (ANY, ANY, ANY), (URI, ANY, ANY) or (URI, additionalPropertyName,
+ ANY) are used.
+
+ The usage of <tt>d2rq:AdditionalProperty</tt> to add instance data is now deprecated (<a href="#additionalproperty_deprecated">details</a>).
+
+ The <tt>d2rq:additionalClassDefinitionProperty</tt> and <tt>d2rq:additionalPropertyDefinitionProperty</tt> properties are used to link from the class map
+ or property bridge to the <tt>d2rq:AdditionalProperty</tt> definition.</p>
+<P><strong>Properties</strong></P>
+<table width="100%" border="1" cellpadding="5" cellspacing="0" bordercolor="#CCCCCC">
+ <tr>
+ <td width="20%" valign="top"><strong>d2rq:propertyName </strong></td>
+ <td width="80%" valign="top">The RDF property to be used as the predicate
+ of all fixed statements.</td>
+
+ </tr>
+ <tr>
+ <td valign="top"><strong>d2rq:propertyValue</strong></td>
+ <td valign="top">The value to be used as the object of all fixed statements.</td>
+ </tr>
+</table>
+<P><strong>Example: Providing an additional property for a class definition</strong></P>
+ <pre>map:PersonsClassMap a d2rq:ClassMap;
+ d2rq:class :Person;
+ d2rq:additionalClassDefinitionProperty map:PersonEquivalence.
+
+map:PersonEquivalence a d2rq:AdditionalProperty;
+ d2rq:propertyName owl:equivalentClass;
+ d2rq:propertyValue foaf:Person.</pre>
+
+<p>This adds an <tt>owl:equivalentClass</tt> statement with the fixed object <tt>foaf:Person</tt> to every related class definition.</p>
+
+<P><strong>Example: Providing an additional property for a property definition</strong></P>
+ <pre>map:PaperTitle a d2rq:PropertyBridge;
+ d2rq:belongsToClassMap map:Paper;
+ d2rq:property :title;
+ d2rq:column "Papers.Title";
+ d2rq:additionalPropertyDefinitionProperty map:PaperTitleEquivalence.
+
+map:PaperTitleEquivalence a d2rq:AdditionalProperty;
+ d2rq:propertyName owl:equivalentProperty;
+ d2rq:propertyValue dc:title.</pre>
+
+<p>This adds an <tt>owl:equivalentProperty</tt> statement with the fixed object <tt>dc:title</tt> to every related property definition.</p>
+
+<h2><a name="translationtable"></a>7.6 Translation Tables</h2>
<p>A <strong>d2rq:TranslationTable</strong> is an additional layer between the
database and the RDF world. It translates back and forth between values taken
from the database and RDF URIs or literals. A translation table can be attached
@@ -1309,7 +1414,7 @@ <h1 id="specification">7. Language Specification</h1>
</tr>
</table>
-<h3><a name="translation"></a>7.5.1 Translation</h3>
+<h3><a name="translation"></a>7.6.1 Translation</h3>
<p>A <strong>d2rq:Translation</strong> is a single entry in a
d2rq:TranslationTable.
@@ -1356,7 +1461,7 @@ <h1 id="specification">7. Language Specification</h1>
Thus, the translation will create URI nodes. If it used d2rq:column,
then literals would be created.</p>
-<h2><a name="conditional" id="conditional"></a>7.6 Conditional Mappings</h2>
+<h2><a name="conditional" id="conditional"></a>7.7 Conditional Mappings</h2>
<p>Sometimes only certain information from a database should be accessible, because
parts of the database might be confidential or outdated. Using <strong>d2rq:condition</strong>
you can specify conditions, which must be satisfied by all accessible data.</p>
@@ -1416,7 +1521,7 @@ <h1 id="specification">7. Language Specification</h1>
d2rq:join "Rel_Paper_Topic.TopicID = Topics.TopicID";
d2rq:condition "Rel_Paper_Topic.RelationType = 2".</pre>
-<h2><a name="hint" id="hint"></a>7.7 Performance Optimization using Hint Properties</h2>
+<h2><a name="hint" id="hint"></a>7.8 Performance Optimization using Hint Properties</h2>
<p>This section covers hint properties that can be added to property bridges in
order to speed up queries: d2rq:valueMaxLength, d2rq:valueRegex and d2rq:valueContains.</p>
@@ -1461,13 +1566,13 @@ <h1 id="specification">7. Language Specification</h1>
or a <a href="#translationtable">translation table</a> with a custom Java class
that returns <tt>null</tt> for unwanted database values.</p>
-<h2 id="deprecated">7.8 Deprecated Language Constructs</h2>
+<h2 id="deprecated">7.9 Deprecated Language Constructs</h2>
<p>This section lists several language constructs from older versions
of the D2RQ mapping language that have been replaced by better
alternatives and should no longer be used.</p>
-<h3 id="datatype-object">7.8.1 <tt>d2rq:DatatypePropertyBridge</tt> and <tt>d2rq:ObjectPropertyBridge</tt></h3>
+<h3 id="datatype-object">7.9.1 <tt>d2rq:DatatypePropertyBridge</tt> and <tt>d2rq:ObjectPropertyBridge</tt></h3>
<p>Older versions of the language used two different classes to
distinguish between property bridges that produce literals, and
@@ -1480,7 +1585,7 @@ <h3 id="datatype-object">7.8.1 <tt>d2rq:DatatypePropertyBridge</tt> and <tt>d2rq
<tt>d2rq:uriColumn</tt>, <tt>d2rq:uriPattern</tt> and
<tt>d2rq:bNodeIdColumns</tt> for resources.</dd></p>
-<h3 id="additionalproperty"><a name="additionalproperty"></a>7.8.2 AdditionalProperty</h3>
+<h3 id="additionalproperty_deprecated"><a name="additionalproperty_deprecated"></a>7.9.2 d2rq:additionalProperty</h3>
<p>Up until D2RQ 0.5.1, the <tt>d2rq:AdditionalProperty</tt> construct could be used
to add a constant property-value pairs to all instances of a class map. An example
is shown below:</p>
@@ -1495,12 +1600,16 @@ <h3 id="additionalproperty"><a name="additionalproperty"></a>7.8.2 AdditionalPro
the persons class map. In recent versions of the mapping language, the same is
achieved by adding a property bridge to the class map, and giving it a
<tt>d2rq:constantValue</tt> property with the fixed URL as the object, as
- shown in <a href="#exconstantvalue">this example</a>.</p>
+ shown in <a href="#exconstantvalue">this example</a>.
+</p>
+<p><tt>d2rq:AdditionalProperty</tt> constructs are still used with <tt>d2rq:additionalClassDefinitionProperty</tt>
+and <tt>d2rq:additionalPropertyDefinitionProperty</tt> (<a href="#additionalproperty">see section 7.5</a>).
<hr />
<h1 id="change_log">8. Change Log</h1>
<ul>
+ <li>2009-02-16: Updated for D2RQ v0.6 and D2R Server v0.4.1.</li>
<li>2007-10-25: Updated for D2RQ v0.5.1 and D2R Server v0.4. </li>
<li>2006-10-26: Updated for D2RQ v0.5.</li>
<li>2005-10-21: Updated for D2RQ v0.4.</li>
@@ -1509,7 +1618,7 @@ <h1 id="change_log">8. Change Log</h1>
<li>2004-06-15: Initial version of this document.</li>
</ul>
<hr />
-<p>$Id: index.htm,v 1.40 2009/02/13 14:31:54 dorgon Exp $</p>
+<p>$Id: index.htm,v 1.41 2009/02/16 11:33:55 fatorange Exp $</p>
</BODY>
</HTML>

0 comments on commit abf747c

Please sign in to comment.