jena-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r899131 - in /websites/staging/jena/trunk/content: ./ documentation/query/parameterized-sparql-strings.html
Date Tue, 25 Feb 2014 11:08:24 GMT
Author: buildbot
Date: Tue Feb 25 11:08:24 2014
New Revision: 899131

Log:
Staging update by buildbot for jena

Modified:
    websites/staging/jena/trunk/content/   (props changed)
    websites/staging/jena/trunk/content/documentation/query/parameterized-sparql-strings.html

Propchange: websites/staging/jena/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Feb 25 11:08:24 2014
@@ -1 +1 @@
-1567298
+1571647

Modified: websites/staging/jena/trunk/content/documentation/query/parameterized-sparql-strings.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/query/parameterized-sparql-strings.html
(original)
+++ websites/staging/jena/trunk/content/documentation/query/parameterized-sparql-strings.html
Tue Feb 25 11:08:24 2014
@@ -131,30 +131,6 @@
 	<h1 class="title">Parameterized SPARQL String</h1>
   <p>A Parameterized SPARQL String is a SPARQL query/update into which values
 may be injected.</p>
-<h3 id="injecting-values">Injecting Values</h3>
-<p>Values may be injected in several ways:</p>
-<ul>
-<li>By treating a variable in the SPARQL string as a parameter</li>
-<li>Using JDBC style positional parameters</li>
-<li>Appending values directly to the command text being built</li>
-</ul>
-<h4 id="variable-parameters">Variable Parameters</h4>
-<p>Any variable in the command may have a value injected to it, injecting a
-value replaces all usages of that variable in the command i.e.
-substitutes the variable for a constant, injection is done by textual
-substitution.</p>
-<h4 id="positional-parameters">Positional Parameters</h4>
-<p>You can use JDBC style positional parameters if you prefer, a JDBC style
-parameter is a single <tt>?</tt> followed by whitespace or certain
-punctuation characters (currently <tt>; , .</tt>). Positional parameters
-have a unique index which reflects the order in which they appear in the
-string. Positional parameters use a zero based index.</p>
-<h4 id="buffer-usage">Buffer Usage</h4>
-<p>Additionally you may use this purely as a <code>StringBuffer</code>
-replacement for creating queries since it provides a large variety of
-convenience methods for appending things either as-is or as nodes (which
-causes appropriate formatting to be applied).</p>
-<h3 id="intended-usage">Intended Usage</h3>
 <p>The intended usage of this is where using a <code>QuerySolutionMap</code>
as
 initial bindings is either inappropriate or not possible e.g.</p>
 <ul>
@@ -176,6 +152,92 @@ the query with constants and to add pref
 <code>Query</code> or <code>UpdateRequest</code> can be created using

 the <code>asQuery()</code> and <code>asUpdate()</code> methods assuming
the command an
 instance represents is actually valid as a query/update.</p>
+<h2 id="building-parameterised-commands">Building parameterised commands</h2>
+<p>A <a href="http://jena.apache.org/documentation/javadoc/arq/com/hp/hpl/jena/query/ParameterizedSparqlString.html">ParameterizedSparqlString</a>
is created as follows:</p>
+<div class="codehilite"><pre><span class="n">ParameterizedSparqlString</span>
<span class="n">pss</span> <span class="p">=</span> <span class="n">new</span>
<span class="n">ParameterizedSparqlString</span><span class="p">();</span>
+</pre></div>
+
+
+<p>There are also constructor overloads that take in an initial command text, parameter
values, namespace prefixes etc.
+which may allow you to simplify some code.</p>
+<p>Once you have an instance you first set your template command with the <code>setCommandText()</code>
method like so:</p>
+<div class="codehilite"><pre><span class="n">pss</span><span class="p">.</span><span
class="n">setCommandText</span><span class="p">(</span>&quot;<span
class="n">SELECT</span> <span class="o">*</span> <span class="n">WHERE</span>
<span class="p">{</span><span class="o">\</span><span class="n">n</span>&quot;
<span class="o">+</span>
+     &quot;  ?<span class="n">s</span> <span class="n">a</span>
?<span class="n">type</span> <span class="o">.\</span><span class="n">n</span>&quot;
<span class="o">+</span>
+     &quot;  <span class="n">OPTIONAL</span> <span class="p">{</span>
?<span class="n">s</span> <span class="n">rdfs</span><span class="p">:</span><span
class="n">label</span> ?<span class="n">label</span> <span class="p">.</span>
<span class="p">}</span><span class="o">\</span><span class="n">n</span>&quot;
<span class="o">+</span>
+     &quot;<span class="p">}</span>&quot;<span class="p">);</span>
+</pre></div>
+
+
+<p>Note that in the above example we did not define the <code>rdfs:</code>
prefix so as it stands the query is invalid.  However 
+you can automatically populate <code>BASE</code> and <code>PREFIX</code>
declarations for your command without having to explicitly 
+declare them in your command text by using the <code>setBaseUri()</code> and
<code>setNsPrefix()</code> method e.g.</p>
+<div class="codehilite"><pre><span class="c1">// Add a Base URI and define
the rdfs prefix</span>
+<span class="n">pss</span><span class="p">.</span><span class="n">setBaseUri</span><span
class="p">(</span><span class="s">&quot;http://example.org/base#&quot;</span><span
class="p">);</span>
+<span class="n">pss</span><span class="p">.</span><span class="n">setNsPrefix</span><span
class="p">(</span><span class="s">&quot;rdfs&quot;</span><span
class="p">,</span> <span class="s">&quot;http://www.w3.org/2000/01/rdf-schema#&quot;</span><span
class="p">);</span>
+</pre></div>
+
+
+<p>You can always call <code>toString()</code> to see the current state
of your instance e.g.</p>
+<div class="codehilite"><pre><span class="c1">// Print current state to
stdout</span>
+<span class="n">System</span><span class="p">.</span><span class="n">out</span><span
class="p">.</span><span class="n">println</span><span class="p">(</span><span
class="n">pss</span><span class="p">.</span><span class="n">toString</span><span
class="p">());</span>
+</pre></div>
+
+
+<p>Which based on the calls so far would print the following:</p>
+<div class="codehilite"><pre><span class="n">BASE</span> <span
class="o">&lt;</span><span class="n">http</span><span class="p">:</span><span
class="o">//</span><span class="n">example</span><span class="p">.</span><span
class="n">org</span><span class="o">/</span><span class="n">base</span>#<span
class="o">&gt;</span>
+<span class="n">PREFIX</span> <span class="n">rdfs</span><span
class="p">:</span> <span class="o">&lt;</span><span class="n">http</span><span
class="p">:</span><span class="o">//</span><span class="n">www</span><span
class="p">.</span><span class="n">w3</span><span class="p">.</span><span
class="n">org</span><span class="o">/</span>2000<span class="o">/</span>01<span
class="o">/</span><span class="n">rdf</span><span class="o">-</span><span
class="n">schema</span>#<span class="o">&gt;</span>
+
+<span class="n">SELECT</span> <span class="o">*</span> <span class="n">WHERE</span>
<span class="p">{</span>
+  ?<span class="n">s</span> <span class="n">a</span> ?<span class="n">type</span>
<span class="p">.</span>
+  <span class="n">OPTIONAL</span> <span class="p">{</span> ?<span
class="n">s</span> <span class="n">rdfs</span><span class="p">:</span><span
class="n">label</span> ?<span class="n">label</span> <span class="p">.</span>
<span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h3 id="injecting-values">Injecting Values</h3>
+<p>Once you have a command text prepared then you want to actually inject values into
it, values may be injected in several ways:</p>
+<ul>
+<li>By treating a variable in the SPARQL string as a parameter</li>
+<li>Using JDBC style positional parameters</li>
+<li>Appending values directly to the command text being built</li>
+</ul>
+<p>See the <a href="http://jena.apache.org/documentation/javadoc/arq/com/hp/hpl/jena/query/ParameterizedSparqlString.html">ParameterizedSparqlString</a>
javadocs for a comprehensive reference of available methods for setting values,
+the following sections shows some basic examples of this.</p>
+<h4 id="variable-parameters">Variable Parameters</h4>
+<p>Any SPARQL variable in the command text may have a value injected to it, injecting
a value replaces all usages of 
+that variable in the command i.e. substitutes the variable for a constant.  Importantly injection
is done by textual 
+substitution so in some cases may cause unexpected side effects.</p>
+<p>Variables parameters are set via the various <code>setX()</code> methods
which take a <code>String</code> as their first argument e.g.</p>
+<div class="codehilite"><pre><span class="c1">// Set an IRI</span>
+<span class="n">pss</span><span class="p">.</span><span class="n">setIri</span><span
class="p">(</span><span class="s">&quot;x&quot;</span><span
class="p">,</span> <span class="s">&quot;http://example.org&quot;</span><span
class="p">);</span>
+
+<span class="c1">// Set a Literal</span>
+<span class="n">pss</span><span class="p">.</span><span class="n">setLiteral</span><span
class="p">(</span><span class="s">&quot;x&quot;</span><span
class="p">,</span> <span class="mh">1234</span><span class="p">);</span>
+<span class="n">pss</span><span class="p">.</span><span class="n">setLiteral</span><span
class="p">(</span><span class="s">&quot;x&quot;</span><span
class="p">,</span> <span class="n">true</span><span class="p">);</span>
+<span class="n">pss</span><span class="p">.</span><span class="n">setLiteral</span><span
class="p">(</span><span class="s">&quot;x&quot;</span><span
class="p">,</span> <span class="s">&quot;value&quot;</span><span
class="p">);</span>
+</pre></div>
+
+
+<p>Where you set a value for a variable you have already set the existing value is
overwritten.  Setting any value
+to <code>null</code> has the same effect as calling <code>clearParam("varname")</code></p>
+<p>If you have the value already as a <code>RDFNode</code> or <code>Node</code>
instance you can call the <code>setParam()</code> method instead e.g.</p>
+<div class="codehilite"><pre><span class="c1">// Set a Node</span>
+<span class="n">Node</span> <span class="n">n</span> <span class="o">=</span>
<span class="n">NodeFactory</span><span class="p">.</span><span
class="n">createIRI</span><span class="p">(</span><span class="s">&quot;http://example.org&quot;</span><span
class="p">);</span>
+<span class="n">pas</span><span class="p">.</span><span class="n">setParam</span><span
class="p">(</span><span class="s">&quot;x&quot;</span><span
class="p">,</span> <span class="n">n</span><span class="p">);</span>
+</pre></div>
+
+
+<h4 id="positional-parameters">Positional Parameters</h4>
+<p>You can use JDBC style positional parameters if you prefer, a JDBC style
+parameter is a single <code>?</code> followed by whitespace or certain
+punctuation characters (currently <code>; , .</code>). Positional parameters
+have a unique index which reflects the order in which they appear in the
+string. Positional parameters use a zero based index.</p>
+<h4 id="buffer-usage">Buffer Usage</h4>
+<p>Additionally you may use this purely as a <code>StringBuffer</code>
+replacement for creating queries since it provides a large variety of
+convenience methods for appending things either as-is or as nodes (which
+causes appropriate formatting to be applied).</p>
 <h3 id="warnings">Warnings</h3>
 <ol>
 <li>Note that this class does not in any way check that your command is



Mime
View raw message