jena-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rve...@apache.org
Subject svn commit: r1571650 - /jena/site/trunk/content/documentation/query/parameterized-sparql-strings.mdtext
Date Tue, 25 Feb 2014 11:21:06 GMT
Author: rvesse
Date: Tue Feb 25 11:21:06 2014
New Revision: 1571650

URL: http://svn.apache.org/r1571650
Log:
Complete example for ParameterizedSparqlString

Modified:
    jena/site/trunk/content/documentation/query/parameterized-sparql-strings.mdtext

Modified: jena/site/trunk/content/documentation/query/parameterized-sparql-strings.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/query/parameterized-sparql-strings.mdtext?rev=1571650&r1=1571649&r2=1571650&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/query/parameterized-sparql-strings.mdtext (original)
+++ jena/site/trunk/content/documentation/query/parameterized-sparql-strings.mdtext Tue Feb
25 11:21:06 2014
@@ -64,6 +64,10 @@ Which based on the calls so far would pr
       OPTIONAL { ?s rdfs:label ?label . }
     }
 
+Note that the state of the instance returned by `toString()` will include any injected values.
 Part of what the `toString()` method
+does is check that your command is not subject to SPARQL injection attacks so in some cases
where a possible
+injection is detected an `ARQException` will be thrown.
+
 [1]: http://jena.apache.org/documentation/javadoc/arq/com/hp/hpl/jena/query/ParameterizedSparqlString.html
 
 ### Injecting Values
@@ -94,7 +98,7 @@ Variables parameters are set via the var
     pss.setLiteral("x", "value");
 
 Where you set a value for a variable you have already set the existing value is overwritten.
 Setting any value
-to `null` has the same effect as calling `clearParam("varname")`
+to `null` has the same effect as calling the `clearParam("x")` method
 
 If you have the value already as a `RDFNode` or `Node` instance you can call the `setParam()`
method instead e.g.
 
@@ -104,43 +108,77 @@ If you have the value already as a `RDFN
 
 #### Positional Parameters
 
-You can use JDBC style positional parameters if you prefer, a JDBC style
-parameter is a single `?` followed by whitespace or certain
-punctuation characters (currently `; , .`). Positional parameters
-have a unique index which reflects the order in which they appear in the
-string. Positional parameters use a zero based index.
+You can use JDBC style positional parameters if you prefer, a JDBC style parameter is a single
`?` followed by 
+whitespace or certain punctuation characters (currently `; , .`). Positional parameters have
a unique index which 
+reflects the order in which they appear in the string. Note that positional parameters use
a zero based index.
+
+Positional parameters are set via the various `setX()` methods which take an `int` as their
first argument e.g.
+
+    // Set an IRI
+    pss.setIri(0, "http://example.org");
+    
+    // Set a Literal
+    pss.setLiteral(0, 1234);
+    pss.setLiteral(0, true);
+    pss.setLiteral(0, "value");
+
+Where you set a value for a variable you have already set the existing value is overwritten.
 Setting any value
+to `null` has the same effect as calling the `clearParam(0)` method
+
+If you have the value already as a `RDFNode` or `Node` instance you can call the `setParam()`
method instead e.g.
+
+    // Set a Node
+    Node n = NodeFactory.createIRI("http://example.org");
+    pas.setParam(0, n);
+
+#### Non-existent parameters
+
+Where you try to set a variable/positional parameter that does not exist there will be no
feedback that the parameter
+does not exist, however the value set will not be included in the string produced when calling
the `toString()` method.
 
 #### Buffer Usage
 
-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).
-
-### Warnings
-
-1.  Note that this class does not in any way check that your command is
-    syntactically correct until such time as you try and parse it as a
-    <code>Query</code> or <code>UpdateRequest</code>.
-2.  Also note that injection is done purely based on textual
-    replacement, it does not understand or respect variable scope in any
-    way. For example if your command text contains sub queries you
-    should ensure that variables within the sub query which you don't
-    want replaced have distinct names from those in the outer query you
-    do want replaced (or vice versa)
+Additionally you may use this purely as a `StringBuffer` replacement for creating commands
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).
+
+For example we could add an `ORDER BY` clause to our earlier example like so:
+
+    // Add ORDER BY clause
+    pss.append("ORDER BY ?s");
+
+Be aware that the basic `append()` methods append the given value as-is without any special
formatting applied, if you
+wanted to use the value being appended as a constant in the SPARQL query the you should use
the appropriate `appendLiteral()`,
+`appendIri()` or `appendNode()` method e.g.
+
+    // Add a LIMIT clause
+    pss.append("LIMIT ");
+    pss.appendLiteral(50);
+
+#### Getting a Query/Update
+
+Once you've prepared your command you should then call the `asQuery()` or `asUpdate()` method
to get it as a `Query`
+or `UpdateRequest` object as appropriate.  Doing this calls `toString()` to produce the final
version of your command with
+all values injected and runs it through the appropriate parser (either `QueryFactory` or
`UpdateFactory`).
+
+You can then use the returned `Query` or `UpdateRequest` object as you would normally to
make a query/update.
 
 ### SPARQL Injection Notes
 
-While this class was in part designed to prevent SPARQL injection it is
-by no means foolproof because it works purely at the textual level. The current
-version of the code addresses some possible attack vectors that the
-developers have identified but we do not claim to be sufficiently devious to
-have thought of and prevented every possible attack vector.
-
- Therefore we <strong>strongly</strong> recommend that users concerned about
- SPARQL Injection attacks perform their own validation on provided parameters
- and test their use of this class themselves prior to its use in any security
- conscious deployment. We also recommend that users do not use easily
- guess-able variable names for their parameters as these can allow a chained
- injection attack though generally speaking the code should prevent these.
+First a couple of warnings:
+
+1.  This class does not in any way check that your command is syntactically correct until
such time as you try and parse 
+it as a `Query` or `UpdateRequest`.
+2.  Injection is done purely based on textual replacement, it does not understand or respect
variable scope in any
+way. For example if your command text contains sub queries you should ensure that variables
within the sub query
+which you don't want replaced have distinct names from those in the outer query you do want
replaced (or vice versa)
+
+While this class was in part designed to prevent SPARQL injection it is by no means foolproof
because it works purely 
+at the textual level. The current version of the code addresses some possible attack vectors
that the developers have 
+identified but we do not claim to be sufficiently devious to have thought of and prevented
every possible attack vector.
+
+Therefore we <strong>strongly</strong> recommend that users concerned about SPARQL
Injection attacks perform 
+their own validation on provided parameters and test their use of this class themselves prior
to its use in any security
+conscious deployment. We also recommend that users do not use easily  guess-able variable
names for their parameters
+as these can allow a chained injection attack though generally speaking the code should prevent
these.
  
\ No newline at end of file



Mime
View raw message