Author: buildbot
Date: Mon Aug 17 08:43:01 2015
New Revision: 962090
Log:
Staging update by buildbot for jena
Modified:
websites/staging/jena/trunk/content/ (props changed)
websites/staging/jena/trunk/content/documentation/query/construct-quad.html
Propchange: websites/staging/jena/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Aug 17 08:43:01 2015
@@ -1 +1 @@
-1696214
+1696218
Modified:
websites/staging/jena/trunk/content/documentation/query/construct-quad.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/query/construct-quad.html
(original)
+++ websites/staging/jena/trunk/content/documentation/query/construct-quad.html
Mon Aug 17 08:43:01 2015
@@ -162,11 +162,115 @@ result is an RDF graph formed by taking
sequence, substituting for the variables in the graph template, and
combining the triples into a single RDF graph by set union. However, it
does not directly generate quads or
-<a href="http://www.w3.org/TR/sparql11-query/#rdfDataset";>RDF datasets</a>.
</p>
-<p>In order to
+<a href="http://www.w3.org/TR/sparql11-query/#rdfDataset";>RDF datasets</a>.<br
/>
+In order to
eliminate this limitation, Jena ARQ extends the grammar of the CONSTRUCT
query form and provides the according components, which brings more
conveniences for the users manipulating RDF datasets with SPARQL.</p>
+<h2 id="query-syntax">Query Syntax<a class="headerlink" href="#query-syntax"
title="Permanent link">¶</a></h2>
+<p>A CONSTRUST template of the SPARQL 1.1 query String is
+<a href="http://www.w3.org/TR/turtle/";>Turtle</a> format with possible
variables. The
+syntax for this extension follows that style in ARQ, using
+<a href="http://www.w3.org/TR/trig/";>TriG</a> plus variables. Just like
SPARQL 1.1,
+there're 2 forms for ARQ Contruct Quad query String:</p>
+<h3 id="complete-form">Complete Form<a class="headerlink"
href="#complete-form" title="Permanent link">¶</a></h3>
+<div class="codehilite"><pre><span class="n">CONSTRUCT</span> <span
class="p">{</span>
+ # <span class="n">Named</span> <span class="n">graph</span>
+ <span class="n">GRAPH</span> <span class="p">:</span><span
class="n">g</span> <span class="p">{</span> ?<span class="n">s</span> <span
class="p">:</span><span class="n">p</span> ?<span class="n">o</span> <span
class="p">}</span>
+ # <span class="n">Default</span> <span class="n">graph</span>
+ <span class="p">{</span> ?<span class="n">s</span> <span
class="p">:</span><span class="n">p</span> ?<span class="n">o</span> <span
class="p">}</span>
+ # <span class="n">Named</span> <span class="n">graph</span>
+ ?<span class="n">g</span> <span class="p">{</span> <span
class="p">:</span><span class="n">s</span> ?<span class="n">p</span> <span
class="p">:</span><span class="n">o</span> <span class="p">}</span>
+ # <span class="n">Default</span> <span class="n">graph</span>
+ <span class="p">:</span><span class="n">s</span> ?<span class="n">p</span>
<span class="p">:</span><span class="n">o</span>
+<span class="p">}</span> <span class="n">WHERE</span> <span class="p">{</span>
+ # <span class="n">SPARQL</span> 1<span class="p">.</span>1 <span
class="n">WHERE</span> <span class="n">Clause</span>
+<span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>The default graphs and the named graphs can be constructed within the
+CONSTRUCT clause in the above way. Note that, for constructing the named
+graph, the token of GRAPH can be optional. The brackets of the triples to
+be constructed in the default graph can also be optional.</p>
+<h3 id="short-form">Short Form<a class="headerlink" href="#short-form"
title="Permanent link">¶</a></h3>
+<div class="codehilite"><pre><span class="n">CONSTRUCT</span> <span
class="n">WHERE</span> <span class="p">{</span>
+ # <span class="n">Basic</span> <span class="n">dataset</span> <span
class="n">pattern</span> <span class="p">(</span><span class="n">only</span>
<span class="n">the</span> <span class="n">default</span> <span
class="n">graph</span> <span class="n">and</span> <span class="n">the</span>
<span class="n">named</span> <span class="n">graphs</span><span
class="p">)</span>
+<span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>A short form is provided for the case where the template and the pattern
+are the same and the pattern is just a basic dataset pattern (no FILTERs
+and no complex graph patterns are allowed in the short form). The keyword
+WHERE is required in the short form.</p>
+<h3 id="grammar">Grammar<a class="headerlink" href="#grammar" title="Permanent
link">¶</a></h3>
+<p>The normative definition of the syntax grammar of the query string is
defined in this table:</p>
+<div class="codehilite"><pre><span class="n">ConstructQuery</span>
<span class="o">|</span> <span class="p">::=</span> <span
class="s">'CONSTRUCT'</span> <span class="p">(</span> <span
class="n">ConstructTemplate</span> <span class="n">DatasetClause</span><span
class="o">*</span> <span class="n">WhereClause</span> <span
class="n">SolutionModifier</span> <span class="o">|</span> <span
class="n">DatasetClause</span><span class="o">*</span> <span
class="s">'WHERE'</span> <span class="s">'{'</span> <span
class="n">ConstructQuads</span> <span class="s">'}'</span> <span
class="n">SolutionModifier</span> <span class="p">)</span>
+<span class="n">ConstructTemplate</span> <span class="o">|</span>
<span class="p">::=</span> <span class="s">'{'</span> <span
class="n">ConstructQuads</span> <span class="s">'}¡¯</span>
+<span class="s">ConstructQuads | ::= TriplesTemplate? (
ConstructQuadsNotTriples '</span><span class="p">.</span><span
class="s">'? TriplesTemplate? )*</span>
+<span class="s">ConstructQuadsNotTriples | ::= ( '</span><span
class="n">GRAPH</span><span class="o">'</span> <span
class="n">VarOrIri</span> <span class="p">)</span>? <span
class="s">'{'</span> <span class="n">TriplesTemplate</span>? <span
class="s">'}'</span>
+<span class="n">TriplesTemplate</span> <span class="o">|</span>
<span class="p">::=</span> <span class="n">TriplesSameSubject</span> <span
class="p">(</span> <span class="s">'.'</span> <span
class="n">TriplesTemplate</span>? <span class="p">)</span>?
+</pre></div>
+
+
+<p><code>DatasetClause</code>, <code>WhereClause</code>,
<code>SolutionModifier</code>, <code>TriplesTemplate</code>,
<code>VarOrIri</code>,
+<code>TriplesSameSubject</code> are as for the <a
href="http://www.w3.org/TR/sparql11-query/#grammar";>SPARQL 1.1 Grammar</a></p>
+<h2 id="programming-api">Programming API<a class="headerlink"
href="#programming-api" title="Permanent link">¶</a></h2>
+<p>ARQ provides 2 additional methods in QueryExecution for Construct Quad.</p>
+<div class="codehilite"><pre><span class="n">Iterator</span><span
class="o"><</span><span class="n">Quad</span><span class="o">></span>
<span class="n">QueryExecution</span><span class="p">.</span><span
class="n">execConstructQuads</span><span class="p">()</span> <span
class="o">//</span> <span class="n">allow</span> <span
class="n">duplication</span>
+<span class="n">Dataset</span> <span class="n">QueryExecution</span><span
class="p">.</span><span class="n">execConstructDataset</span><span
class="p">()</span> <span class="o">//</span> <span class="n">no</span> <span
class="n">duplication</span>
+</pre></div>
+
+
+<p>One difference of the 2 methods is:
+The method of execConstructQuads() returns an Iterator of Quad, allowing
duplication.
+But execConstructDataset() constructs the desired Dataset object with only
unique Quads.</p>
+<p>In order to use these methods, it's required to swtich on the query syntax
+of ARQ beforehead, when creating the Query object:</p>
+<div class="codehilite"><pre><span class="n">Query</span> <span
class="n">query</span> <span class="p">=</span> <span
class="n">QueryFactory</span><span class="p">.</span><span
class="n">create</span><span class="p">(</span><span
class="n">queryString</span><span class="p">,</span> <span
class="n">Syntax</span><span class="p">.</span><span
class="n">syntaxARQ</span><span class="p">);</span>
+</pre></div>
+
+
+<p>If the query is supposed to construct only triples, not quads, the triples
+will be constructed in the default graph. For example:</p>
+<div class="codehilite"><pre><span class="n">String</span> <span
class="n">queryString</span> <span class="p">=</span> "<span
class="n">CONSTRUCT</span> <span class="p">{</span> ?<span class="n">s</span>
?<span class="n">p</span> ?<span class="n">o</span> <span class="p">}</span>
<span class="n">WHERE</span> <span class="p">...</span> "
+<span class="p">...</span>
+<span class="o">//</span> <span class="n">The</span> <span
class="n">graph</span> <span class="n">node</span> <span class="n">of</span>
<span class="n">the</span> <span class="n">quads</span> <span
class="n">are</span> <span class="n">the</span> <span class="n">default</span>
<span class="n">graph</span> <span class="p">(</span><span class="n">ARQ</span>
<span class="n">uses</span> <span class="o"><</span><span
class="n">urn</span><span class="p">:</span><span class="n">x</span><span
class="o">-</span><span class="n">arq</span><span class="p">:</span><span
class="n">DefaultGraphNode</span><span class="o">></span><span
class="p">).</span>
+<span class="n">Iterator</span><span class="o"><</span><span
class="n">Quad</span><span class="o">></span> <span class="n">quads</span>
<span class="p">=</span> <span class="n">qexec</span><span
class="p">.</span><span class="n">execConstructQuads</span><span
class="p">();</span>
+</pre></div>
+
+
+<p>If the query string stands for constructing quads while the method of
+exeConstructTriples() are called, it returns only the triples in the
+default graph of the CONSTRUCT query template. It's called a "projection"
+on the default graph. For instance:</p>
+<div class="codehilite"><pre><span class="n">String</span> <span
class="n">queryString</span> <span class="p">=</span> "<span
class="n">CONSTRUCT</span> <span class="p">{</span> ?<span class="n">s</span>
?<span class="n">p</span> ?<span class="n">o</span> <span class="p">.</span>
<span class="n">GRAPH</span> ?<span class="n">g1</span> <span
class="p">{</span> ?<span class="n">s1</span> ?<span class="n">p1</span> ?<span
class="n">o1</span> <span class="p">}</span> <span class="p">}</span> <span
class="n">WHERE</span> <span class="p">...</span>"
+<span class="p">...</span>
+<span class="o">//</span> <span class="n">The</span> <span
class="n">part</span> <span class="n">of</span> "<span
class="n">GRAPH</span> ?<span class="n">g1</span> <span class="p">{</span>
?<span class="n">s1</span> ?<span class="n">p1</span> ?<span
class="n">o1</span> <span class="p">}</span>" <span class="n">will</span>
<span class="n">be</span> <span class="n">ignored</span><span
class="p">.</span> <span class="n">Only</span> "?<span class="n">s</span>
?<span class="n">p</span> ?<span class="n">o</span>" <span
class="n">in</span> <span class="n">the</span> <span class="n">default</span>
<span class="n">graph</span> <span class="n">will</span> <span
class="n">be</span> <span class="n">returned</span><span class="p">.</span>
+<span class="n">Iterator</span><span class="o"><</span><span
class="n">Triple</span><span class="o">></span> <span
class="n">triples</span> <span class="p">=</span> <span
class="n">qexec</span><span class="p">.</span><span
class="n">exeConstructTriples</span><span class="p">();</span>
+</pre></div>
+
+
+<p>More examples can be found at
jena-arq/src-examples/arq/examples/constructquads/ExampleConstructQuads.java</p>
+<h2 id="fuseki-support">Fuseki Support<a class="headerlink"
href="#fuseki-support" title="Permanent link">¶</a></h2>
+<p>Jena [Fuseki] is also empowed with Construct Quad query as a built-in
+function. No more addtional configuration is required to switch it on.
+Because
+<a
href="http://jena.apache.org/documentation/javadoc/arq/com/hp/hpl/jena/sparql/engine/http/QueryEngineHTTP.html";>QueryEngineHTTP</a>
+is just an implementation of QueryExcecution, there's no much difference
+for the client users to manipulate the programming API described in the
+previous sections, e.g.</p>
+<div class="codehilite"><pre><span class="n">String</span> <span
class="n">queryString</span> <span class="p">=</span> " <span
class="n">CONSTRUCT</span> <span class="p">{</span> <span
class="n">GRAPH</span> <span class="o"><</span><span
class="n">http</span><span class="p">:</span><span class="o">//</span><span
class="n">example</span><span class="o">/</span><span class="n">ns</span>#<span
class="n">g1</span><span class="o">></span> <span class="p">{</span>?<span
class="n">s</span> ?<span class="n">p</span> ?<span class="n">o</span><span
class="p">}</span> <span class="p">}</span> <span class="n">WHERE</span> <span
class="p">{</span>?<span class="n">s</span> ?<span class="n">p</span> ?<span
class="n">o</span><span class="p">}</span>" <span class="p">;</span>
+<span class="n">Query</span> <span class="n">query</span> <span
class="p">=</span> <span class="n">QueryFactory</span><span
class="p">.</span><span class="n">create</span><span class="p">(</span><span
class="n">queryString</span><span class="p">,</span> <span
class="n">Syntax</span><span class="p">.</span><span
class="n">syntaxARQ</span><span class="p">);</span>
+<span class="k">try</span> <span class="p">(</span> <span
class="n">QueryExecution</span> <span class="n">qExec</span> <span
class="p">=</span> <span class="n">QueryExecutionFactory</span><span
class="p">.</span><span class="n">sparqlService</span><span
class="p">(</span><span class="n">serviceQuery</span><span class="p">,</span>
<span class="n">query</span><span class="p">)</span> <span class="p">)</span>
<span class="p">{</span> <span class="o">//</span> <span
class="n">serviceQuery</span> <span class="n">is</span> <span
class="n">the</span> <span class="n">URL</span> <span class="n">of</span> <span
class="n">the</span> <span class="n">remote</span> <span
class="n">service</span>
+ <span class="n">Iterator</span><span class="o"><</span><span
class="n">Quad</span><span class="o">></span> <span class="n">result</span>
<span class="p">=</span> <span class="n">qExec</span><span
class="p">.</span><span class="n">execConstructQuads</span><span
class="p">();</span>
+<span class="p">...</span>
+<span class="p">}</span>
+<span class="p">...</span>
+</pre></div>
</div>
</div>
