Author: buildbot
Date: Sat Jul 5 15:09:37 2014
New Revision: 915096
Log:
Staging update by buildbot for jena
Modified:
websites/staging/jena/trunk/content/ (props changed)
websites/staging/jena/trunk/content/documentation/query/app_api.html
Propchange: websites/staging/jena/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Sat Jul 5 15:09:37 2014
@@ -1 +1 @@
-1608027
+1608029
Modified: websites/staging/jena/trunk/content/documentation/query/app_api.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/query/app_api.html
(original)
+++ websites/staging/jena/trunk/content/documentation/query/app_api.html Sat
Jul 5 15:09:37 2014
@@ -160,11 +160,10 @@ package.</p>
Query are normally created by calling one of the methods of
<code>QueryFactory</code> methods which provide access to the various
parsers.</li>
<li><code>QueryExecution</code> - represents one execution of a query.</li>
-<li><code>QueryExecutionFactory</code> - a place to get
<code>QueryExecution</code>
- instances</li>
-<li><code>DatasetFactory</code> - a place to make datasets</li>
+<li><code>QueryExecutionFactory</code> - a place to get
<code>QueryExecution</code> instances.</li>
+<li><code>DatasetFactory</code> - a place to make datasets.</li>
<li>For SELECT queries:<ul>
-<li><code>QuerySolution</code> - A single solution to the query</li>
+<li><code>QuerySolution</code> - A single solution to the query.</li>
<li><code>ResultSet</code> - All the QuerySolutions. An iterator.</li>
<li><code>ResultSetFormatter</code> - turn a ResultSet into various forms;
into text, into an RDF graph (Model, in Jena terminology) or as
@@ -177,14 +176,14 @@ package.</p>
example below. A query is created from a string using the
<code>QueryFactory</code>. The query and model or RDF dataset to be queried
are then passed to <code>QueryExecutionFactory</code> to produce an instance
-of a query execution. Result are handled in a loop and finally the
+of a query execution. <code>QueryExecution</code> objects are
<code>java.lang.AutoCloseable</code>
+and can be used in try-resource. Result are handled in a loop and finally the
query execution is closed.</p>
<div class="codehilite"><pre> <span class="n">import</span> <span
class="n">com</span><span class="p">.</span><span class="n">hp</span><span
class="p">.</span><span class="n">hpl</span><span class="p">.</span><span
class="n">jena</span><span class="p">.</span><span class="n">query</span><span
class="o">.*</span> <span class="p">;</span>
<span class="n">Model</span> <span class="n">model</span> <span
class="p">=</span> <span class="p">...</span> <span class="p">;</span>
<span class="n">String</span> <span class="n">queryString</span> <span
class="p">=</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="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">create</span><span class="p">(</span><span
class="n">query</span><span class="p">,</span> <span
class="n">model</span><span class="p">)</span> <span class="p">;</span>
- <span class="k">try</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">create</span><span class="p">(</span><span
class="n">query</span><span class="p">,</span> <span
class="n">model</span><span class="p">)</span> <span class="p">)</span>
<span class="n">ResultSet</span> <span class="n">results</span> <span
class="p">=</span> <span class="n">qexec</span><span class="p">.</span><span
class="n">execSelect</span><span class="p">()</span> <span class="p">;</span>
<span class="k">for</span> <span class="p">(</span> <span
class="p">;</span> <span class="n">results</span><span class="p">.</span><span
class="n">hasNext</span><span class="p">()</span> <span class="p">;</span>
<span class="p">)</span>
<span class="p">{</span>
@@ -193,14 +192,14 @@ query execution is closed.</p>
<span class="n">Resource</span> <span class="n">r</span> <span
class="p">=</span> <span class="n">soln</span><span class="p">.</span><span
class="n">getResource</span><span class="p">(</span>"<span
class="n">VarR</span>"<span class="p">)</span> <span class="p">;</span>
<span class="o">//</span> <span class="n">Get</span> <span class="n">a</span>
<span class="n">result</span> <span class="n">variable</span> <span
class="o">-</span> <span class="n">must</span> <span class="n">be</span> <span
class="n">a</span> <span class="n">resource</span>
<span class="n">Literal</span> <span class="n">l</span> <span
class="p">=</span> <span class="n">soln</span><span class="p">.</span><span
class="n">getLiteral</span><span class="p">(</span>"<span
class="n">VarL</span>"<span class="p">)</span> <span class="p">;</span>
<span class="o">//</span> <span class="n">Get</span> <span class="n">a</span>
<span class="n">result</span> <span class="n">variable</span> <span
class="o">-</span> <span class="n">must</span> <span class="n">be</span> <span
class="n">a</span> <span class="n">literal</span>
<span class="p">}</span>
- <span class="p">}</span> <span class="n">finally</span> <span
class="p">{</span> <span class="n">qexec</span><span class="p">.</span><span
class="n">close</span><span class="p">()</span> <span class="p">;</span> <span
class="p">}</span>
+ <span class="p">}</span>
</pre></div>
<p>It is important to cleanly close the query execution when finished.
System resources connected to persistent storage may need to be
released.</p>
-<p>A ResultSetARQ supports the Java iterator interface so the
+<p>A <code>ResultSet</code> supports the Java iterator interface so the
following is also a way to process the results if preferred:</p>
<div class="codehilite"><pre> <span class="n">Iterator</span><span
class="o"><</span><span class="n">QuerySolution</span><span
class="o">></span> <span class="n">results</span> <span class="p">=</span>
<span class="n">qexec</span><span class="p">.</span><span
class="n">execSelect</span><span class="p">()</span> <span class="p">;</span>
<span class="k">for</span> <span class="p">(</span> <span
class="p">;</span> <span class="n">results</span><span class="p">.</span><span
class="n">hasNext</span><span class="p">()</span> <span class="p">;</span>
<span class="p">)</span>
@@ -216,17 +215,35 @@ reduced to one step in some common cases
<div class="codehilite"><pre> <span class="n">import</span> <span
class="n">com</span><span class="p">.</span><span class="n">hp</span><span
class="p">.</span><span class="n">hpl</span><span class="p">.</span><span
class="n">jena</span><span class="p">.</span><span class="n">query</span><span
class="o">.*</span> <span class="p">;</span>
<span class="n">Model</span> <span class="n">model</span> <span
class="p">=</span> <span class="p">...</span> <span class="p">;</span>
<span class="n">String</span> <span class="n">queryString</span> <span
class="p">=</span> " <span class="p">....</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">create</span><span class="p">(</span><span
class="n">queryString</span><span class="p">,</span> <span
class="n">model</span><span class="p">)</span> <span class="p">;</span>
- <span class="k">try</span> <span class="p">{</span>
- <span class="n">ResultSet</span> <span class="n">results</span> <span
class="p">=</span> <span class="n">qexec</span><span class="p">.</span><span
class="n">execSelect</span><span class="p">()</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">create</span><span class="p">(</span><span
class="n">queryString</span><span class="p">,</span> <span
class="n">model</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">ResultSet</span> <span class="n">results</span> <span
class="p">=</span> <span class="n">qexec</span><span class="p">.</span><span
class="n">execSelect</span><span class="p">()</span> <span class="p">;</span>
<span class="p">.</span> <span class="p">.</span> <span class="p">.</span>
- <span class="p">}</span> <span class="n">finally</span> <span
class="p">{</span> <span class="n">qexec</span><span class="p">.</span><span
class="n">close</span><span class="p">()</span> <span class="p">;</span> <span
class="p">}</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<h3 id="passing-a-result-set-out-of-the-processing-loop">Passing a result set
out of the processing loop.</h3>
+<p>A <code>ResultSet</code> is an iterator and can be traversed only once.
What is more, much of query execution
+and result set processing is handled internally in a streaming fashion. The
<code>ResultSet</code> returned
+by <code>execSelect</code> is not valid after the <code>QueryExecution</code>
is closed,
+whether explicitly or by
+try-resources as the <code>QueryExecution</code> implements
<code>AutoCloseable</code>.</p>
+<p>A result set may be materialized - this is then usable outside </p>
+<div class="codehilite"><pre> <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">create</span><span class="p">(</span><span
class="n">queryString</span><span class="p">,</span> <span
class="n">model</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">ResultSet</span> <span class="n">results</span> <span
class="p">=</span> <span class="n">qexec</span><span class="p">.</span><span
class="n">execSelect</span><span class="p">()</span> <span class="p">;</span>
+ <span class="n">results</span> <span class="p">=</span> <span
class="n">ResultSetFactory</span><span class="p">.</span><span
class="n">copyResults</span><span class="p">(</span><span
class="n">results</span><span class="p">)</span> <span class="p">;</span>
+ <span class="k">return</span> <span class="n">results</span> <span
class="p">;</span> <span class="o">//</span> <span class="n">Passes</span>
<span class="n">the</span> <span class="n">result</span> <span
class="n">set</span> <span class="n">out</span> <span class="n">of</span> <span
class="n">the</span> <span class="k">try</span><span class="o">-</span><span
class="n">resources</span>
+ <span class="p">}</span>
</pre></div>
+<p>The result set from <code>ResultSetFactory.copyResults</code> is a
<code>ResultSetRewindable</code> which has a
+<code>reset()</code> operation that positions the iterator at the start of the
result again.</p>
+<p>The models returned by <code>execConstruct</code> and
<code>execDescribe</code> are valid
+after the <code>QueryExecution</code> is closed.</p>
<h3 id="example-formatting-a-result-set">Example: formatting a result set</h3>
<p>Instead of a loop to deal with each row in the result set, the
-application can call an operation of the ResultSetFormatter. This
+application can call an operation of the <code>ResultSetFormatter</code>. This
is what the command line applications do.</p>
<p>Example: processing results to produce a simple text presentation:</p>
<div class="codehilite"><pre> <span class="n">ResultSetFormatter</span>
<span class="n">fmt</span> <span class="p">=</span> <span class="n">new</span>
<span class="n">ResultSetFormatter</span><span class="p">(</span><span
class="n">results</span><span class="p">,</span> <span
class="n">query</span><span class="p">)</span> <span class="p">;</span>
