ParameterizedSparqlString (Apache Jena ARQ)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.hp.hpl.jena.query
Class ParameterizedSparqlString

java.lang.Object
  com.hp.hpl.jena.query.ParameterizedSparqlString

All Implemented Interfaces:: PrefixMapping

public class ParameterizedSparqlString
extends Object
implements PrefixMapping
extends Object
implements PrefixMapping

A Parameterized SPARQL String is a SPARQL query/update into which values may be injected.

Injecting Values

Values may be injected in several ways:

By treating a variable in the SPARQL string as a parameter
Using JDBC style positional parameters
Appending values directly to the command text being built

Variable Parameters

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.

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.

Buffer Usage

Additionally you may use this purely as a StringBuffer 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).

Intended Usage

The intended usage of this is where using a QuerySolutionMap as initial bindings is either inappropriate or not possible e.g.

Generating query/update strings in code without lots of error prone and messy string concatenation
Preparing a query/update for remote execution
Where you do not want to simply say some variable should have a certain value but rather wish to insert constants into the query/update in place of variables
Defending against SPARQL injection when creating a query/update using some external input, see SPARQL Injection notes for limitations.
Provide a more convenient way to prepend common prefixes to your query

This class is useful for preparing both queries and updates hence the generic name as it provides programmatic ways to replace variables in the query with constants and to add prefix and base declarations. A Query or UpdateRequest can be created using the asQuery() and asUpdate() methods assuming the command an instance represents is actually valid as a query/update.

Warnings

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 Query or UpdateRequest.
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)

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 strongly 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.

Nested Class Summary

Nested classes/interfaces inherited from interface com.hp.hpl.jena.shared.PrefixMapping
`PrefixMapping.Factory, PrefixMapping.IllegalPrefixException, PrefixMapping.JenaLockedException`

Field Summary

Fields inherited from interface com.hp.hpl.jena.shared.PrefixMapping
`Extended, Standard`

Constructor Summary
`ParameterizedSparqlString()` Creates a new parameterized string with an empty command text
`ParameterizedSparqlString(PrefixMapping prefixes)` Creates a new parameterized string
`ParameterizedSparqlString(QuerySolutionMap map)` Creates a new parameterized string
`ParameterizedSparqlString(QuerySolutionMap map, PrefixMapping prefixes)` Creates a new parameterized string
`ParameterizedSparqlString(String command)` Creates a new parameterized string
`ParameterizedSparqlString(String command, PrefixMapping prefixes)` Creates a new parameterized string
`ParameterizedSparqlString(String command, QuerySolutionMap map)` Creates a new parameterized string
`ParameterizedSparqlString(String command, QuerySolutionMap map, PrefixMapping prefixes)` Creates a new parameterized string
`ParameterizedSparqlString(String command, QuerySolutionMap map, String base)` Creates a new parameterized string
`ParameterizedSparqlString(String command, QuerySolutionMap map, String base, PrefixMapping prefixes)` Creates a new parameterized string
`ParameterizedSparqlString(String command, String base)` Creates a new parameterized string
`ParameterizedSparqlString(String command, String base, PrefixMapping prefixes)` Creates a new parameterized string

Method Summary
`void`	`append(boolean b)` Appends a boolean as-is to the existing command text, to ensure correct formatting when used as a constant consider using the `appendLiteral(boolean)` method
`void`	`append(char c)` Appends a character to the existing command text
`void`	`append(double d)` Appends a double as-is to the existing command text, to ensure correct formatting when used as a constant consider using the `appendLiteral(double)` method
`void`	`append(float f)` Appends a float as-is to the existing command text, to ensure correct formatting when used as a constant consider using the `appendLiteral(float)` method
`void`	`append(int i)` Appends an integer as-is to the existing command text, to ensure correct formatting when used as a constant consider using the `appendLiteral(int)` method
`void`	`append(long l)` Appends a long as-is to the existing command text, to ensure correct formatting when used as a constant consider using the `appendLiteral(long)` method
`void`	`append(Object obj)` Appends an object to the existing command text
`void`	`append(String text)` Appends some text to the existing command text
`void`	`appendIri(org.apache.jena.iri.IRI iri)` Appends an IRI to the command text as a constant using appropriate formatting
`void`	`appendIri(String uri)` Appends a URI to the command text as a constant using appropriate formatting
`void`	`appendLiteral(boolean b)` Appends a boolean to the command text as a constant using appropriate formatting
`void`	`appendLiteral(Calendar dt)` Appends a date time to the command text as a constant using appropriate formatting
`void`	`appendLiteral(double d)` Appends a double to the command text as a constant using appropriate formatting
`void`	`appendLiteral(float f)` Appends a float to the command text as a constant using appropriate formatting
`void`	`appendLiteral(int i)` Appends an integer to the command text as a constant using appropriate formatting
`void`	`appendLiteral(long l)` Appends a long to the command text as a constant using appropriate formatting
`void`	`appendLiteral(String value)` Appends a simple literal as a constant using appropriate formatting
`void`	`appendLiteral(String value, RDFDatatype datatype)` Appends a Typed Literal to the command text as a constant using appropriate formatting
`void`	`appendLiteral(String value, String lang)` Appends a literal with a lexical value and language to the command text as a constant using appropriate formatting
`void`	`appendNode(Node n)` Appends a Node to the command text as a constant using appropriate formatting
`void`	`appendNode(RDFNode n)` Appends a Node to the command text as a constant using appropriate formatting
`Query`	`asQuery()` Attempts to take the command text with parameters injected from the `toString()` method and parse it as a `Query`
`UpdateRequest`	`asUpdate()` Attempts to take the command text with parameters injected from the `toString()` method and parse it as a `UpdateRequest`
`void`	`clearParam(int index)` Clears the value for a positional parameter
`void`	`clearParam(String var)` Clears the value for a variable parameter so the given variable will not have a value injected
`void`	`clearParams()` Clears all values for both variable and positional parameters
`ParameterizedSparqlString`	`copy()` Makes a full copy of this parameterized string
`ParameterizedSparqlString`	`copy(boolean copyParams)` Makes a copy of the command text, base URI and prefix mapping and optionally copies parameter values
`ParameterizedSparqlString`	`copy(boolean copyParams, boolean copyBase, boolean copyPrefixes)` Makes a copy of the command text and optionally copies other aspects
`String`	`expandPrefix(String prefixed)`
`String`	`getBaseUri()` Gets the Base URI which will be prepended to a query
`String`	`getCommandText()` Gets the basic Command Text
`Iterator<Integer>`	`getEligiblePositionalParameters()` Gets the eligible positional parameters i.e.
`Map<String,String>`	`getNsPrefixMap()`
`String`	`getNsPrefixURI(String prefix)`
`String`	`getNsURIPrefix(String uri)`
`Node`	`getParam(int index)` Gets the current value for a positional parameter
`Node`	`getParam(String var)` Gets the current value for a variable parameter
`Map<Integer,Node>`	`getPositionalParameters()` Gets the map of currently set positional parameters, this will be an unmodifiable map
`Map<String,Node>`	`getVariableParameters()` Gets the map of currently set variable parameters, this will be an unmodifiable map
`Iterator<String>`	`getVars()` Deprecated.
`PrefixMapping`	`lock()`
`String`	`qnameFor(String uri)`
`PrefixMapping`	`removeNsPrefix(String prefix)`
`boolean`	`samePrefixMappingAs(PrefixMapping other)`
`void`	`setBaseUri(String base)` Sets the Base URI which will be prepended to the query/update
`void`	`setCommandText(String command)` Sets the command text, overwriting any existing command text.
`void`	`setIri(int index, org.apache.jena.iri.IRI iri)` Sets a positional parameter to an IRI
`void`	`setIri(int index, String iri)` Sets a positional parameter to an IRI
`void`	`setIri(int index, URL url)` Sets a positional parameter to an IRI
`void`	`setIri(String var, org.apache.jena.iri.IRI iri)` Sets a variable parameter to an IRI
`void`	`setIri(String var, String iri)` Sets a variable parameter to an IRI
`void`	`setIri(String var, URL url)` Sets a variable parameter to an IRI
`void`	`setLiteral(int index, boolean value)` Sets a positional parameter to a boolean literal
`void`	`setLiteral(int index, Calendar dt)` Sets a positional parameter to a date time literal
`void`	`setLiteral(int index, double d)` Sets a positional parameter to a double literal
`void`	`setLiteral(int index, float f)` Sets a positional parameter to a float literal
`void`	`setLiteral(int index, int i)` Sets a positional parameter to an integer literal
`void`	`setLiteral(int index, Literal lit)` Sets a positional parameter to a Literal
`void`	`setLiteral(int index, long l)` Sets a positional parameter to an integer literal
`void`	`setLiteral(int index, String value)` Sets a positional parameter to a literal
`void`	`setLiteral(int index, String value, RDFDatatype datatype)` Sets a positional arameter to a typed literal
`void`	`setLiteral(int index, String value, String lang)` Sets a positional parameter to a literal with a language
`void`	`setLiteral(String var, boolean value)` Sets a variable parameter to a boolean literal
`void`	`setLiteral(String var, Calendar dt)` Sets a variable parameter to a date time literal
`void`	`setLiteral(String var, double d)` Sets a variable parameter to a double literal
`void`	`setLiteral(String var, float f)` Sets a variable parameter to a float literal
`void`	`setLiteral(String var, int i)` Sets a variable parameter to an integer literal
`void`	`setLiteral(String var, Literal lit)` Sets a variable parameter to a Literal
`void`	`setLiteral(String var, long l)` Sets a variable parameter to an integer literal
`void`	`setLiteral(String var, String value)` Sets a variable parameter to a literal
`void`	`setLiteral(String var, String value, RDFDatatype datatype)` Sets a variable parameter to a typed literal
`void`	`setLiteral(String var, String value, String lang)` Sets a variable parameter to a literal with a language
`PrefixMapping`	`setNsPrefix(String prefix, String uri)`
`PrefixMapping`	`setNsPrefixes(Map<String,String> map)`
`PrefixMapping`	`setNsPrefixes(PrefixMapping other)`
`void`	`setParam(int index, Node n)` Sets a Positional Parameter
`void`	`setParam(int index, RDFNode n)` Sets a positional parameter
`void`	`setParam(String var, Node n)` Sets a variable parameter
`void`	`setParam(String var, RDFNode n)` Sets a variable parameter
`void`	`setParams(QuerySolutionMap map)` Sets the Parameters
`String`	`shortForm(String uri)`
`String`	`toString()` This method is where the actual work happens, the original command text is always preserved and we just generated a temporary command string by prepending the defined Base URI and namespace prefixes at the start of the command and injecting the set parameters into a copy of that base command string and return the resulting command.
`PrefixMapping`	`withDefaultMappings(PrefixMapping map)`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail