jena-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r915096 - in /websites/staging/jena/trunk/content: ./ documentation/query/app_api.html
Date Sat, 05 Jul 2014 15:09:38 GMT
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> &quot; <span class="p">....</span> &quot;
<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>&quot;<span
class="n">VarR</span>&quot;<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>&quot;<span
class="n">VarL</span>&quot;<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">&lt;</span><span class="n">QuerySolution</span><span
class="o">&gt;</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> &quot; <span class="p">....</span> &quot;
<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>



Mime
View raw message