com.hp.hpl.jena.query
Class ParameterizedSparqlString

java.lang.Object
  extended by com.hp.hpl.jena.query.ParameterizedSparqlString
All Implemented Interfaces:
PrefixMapping

public class ParameterizedSparqlString
extends Object
implements PrefixMapping

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

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

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

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

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


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(String var)
          Clears the value for a parameter so the given variable will not have a value injected
 void clearParams()
          Clears all values
 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
 Map<String,String> getNsPrefixMap()
           
 String getNsPrefixURI(String prefix)
           
 String getNsURIPrefix(String uri)
           
 Node getParam(String var)
          Gets the current value for a parameter
 Iterator<String> getVars()
          Gets the variables which are currently treated as parameters (i.e.
 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(String var, org.apache.jena.iri.IRI iri)
          Sets a Parameter to an IRI
 void setIri(String var, String iri)
          Sets a Parameter to an IRI
 void setIri(String var, URL url)
          Sets a Parameter to an IRI
 void setLiteral(String var, boolean value)
          Sets a Parameter to a boolean literal
 void setLiteral(String var, Calendar dt)
          Sets a Parameter to a date time literal
 void setLiteral(String var, double d)
          Sets a Parameter to a double literal
 void setLiteral(String var, float f)
          Sets a Parameter to a float literal
 void setLiteral(String var, int i)
          Sets a Parameter to an integer literal
 void setLiteral(String var, Literal lit)
          Sets a Parameter to a Literal
 void setLiteral(String var, long l)
          Sets a Parameter to an integer literal
 void setLiteral(String var, String value)
          Seta a Parameter to a literal
 void setLiteral(String var, String value, RDFDatatype datatype)
          Sets a Parameter to a typed literal
 void setLiteral(String var, String value, String lang)
          Sets a 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(String var, Node n)
          Sets a Parameter
 void setParam(String var, RDFNode n)
          Sets a Parameter
 void setParams(QuerySolutionMap map)
          Sets the Parameters
 String shortForm(String uri)
           
 String toString()
          The toString() method is where the actual magic happens, the original command text is always preserved and we just generated a temporary command string by inserting the defined namespace prefixes at the start of the command and injecting the set parameters into a copy of that base 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

ParameterizedSparqlString

public ParameterizedSparqlString(String command,
                                 QuerySolutionMap map,
                                 String base,
                                 PrefixMapping prefixes)
Creates a new parameterized string

Parameters:
command - Raw Command Text
map - Initial Parameters to inject
base - Base URI
prefixes - Prefix Mapping

ParameterizedSparqlString

public ParameterizedSparqlString(String command,
                                 QuerySolutionMap map,
                                 String base)
Creates a new parameterized string

Parameters:
command - Raw Command Text
map - Initial Parameters to inject
base - Base URI

ParameterizedSparqlString

public ParameterizedSparqlString(String command,
                                 QuerySolutionMap map,
                                 PrefixMapping prefixes)
Creates a new parameterized string

Parameters:
command - Raw Command Text
map - Initial Parameters to inject
prefixes - Prefix Mapping

ParameterizedSparqlString

public ParameterizedSparqlString(String command,
                                 QuerySolutionMap map)
Creates a new parameterized string

Parameters:
command - Raw Command Text
map - Initial Parameters to inject

ParameterizedSparqlString

public ParameterizedSparqlString(String command,
                                 String base,
                                 PrefixMapping prefixes)
Creates a new parameterized string

Parameters:
command - Raw Command Text
base - Base URI
prefixes - Prefix Mapping

ParameterizedSparqlString

public ParameterizedSparqlString(String command,
                                 PrefixMapping prefixes)
Creates a new parameterized string

Parameters:
command - Raw Command Text
prefixes - Prefix Mapping

ParameterizedSparqlString

public ParameterizedSparqlString(String command,
                                 String base)
Creates a new parameterized string

Parameters:
command - Raw Command Text
base - Base URI

ParameterizedSparqlString

public ParameterizedSparqlString(String command)
Creates a new parameterized string

Parameters:
command - Raw Command Text

ParameterizedSparqlString

public ParameterizedSparqlString(QuerySolutionMap map,
                                 PrefixMapping prefixes)
Creates a new parameterized string

Parameters:
map - Initial Parameters to inject
prefixes - Prefix Mapping

ParameterizedSparqlString

public ParameterizedSparqlString(QuerySolutionMap map)
Creates a new parameterized string

Parameters:
map - Initial Parameters to inject

ParameterizedSparqlString

public ParameterizedSparqlString(PrefixMapping prefixes)
Creates a new parameterized string

Parameters:
prefixes - Prefix Mapping

ParameterizedSparqlString

public ParameterizedSparqlString()
Creates a new parameterized string with an empty command text

Method Detail

setCommandText

public void setCommandText(String command)
Sets the command text, overwriting any existing command text. If you want to append to the command text use one of the append(String), appendIri(String), appendLiteral(String) or appendNode(Node) methods instead


append

public void append(String text)
Appends some text to the existing command text

Parameters:
text - Text to append

append

public void append(char c)
Appends a character to the existing command text

Parameters:
c - Character to append

append

public 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

Parameters:
b - Boolean to append

append

public 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

Parameters:
d - Double to append

append

public 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

Parameters:
f - Float to append

append

public 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

Parameters:
i - Integer to append

append

public 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

Parameters:
l - Long to append

append

public void append(Object obj)
Appends an object to the existing command text

Parameters:
obj - Object to append

appendNode

public void appendNode(Node n)
Appends a Node to the command text as a constant using appropriate formatting

Parameters:
n - Node to append

appendNode

public void appendNode(RDFNode n)
Appends a Node to the command text as a constant using appropriate formatting

Parameters:
n - Node to append

appendIri

public void appendIri(String uri)
Appends a URI to the command text as a constant using appropriate formatting

Parameters:
uri - URI to append

appendIri

public void appendIri(org.apache.jena.iri.IRI iri)
Appends an IRI to the command text as a constant using appropriate formatting

Parameters:
iri - IRI to append

appendLiteral

public void appendLiteral(String value)
Appends a simple literal as a constant using appropriate formatting

Parameters:
value - Lexical Value

appendLiteral

public 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

Parameters:
value - Lexical Value
lang - Language

appendLiteral

public void appendLiteral(String value,
                          RDFDatatype datatype)
Appends a Typed Literal to the command text as a constant using appropriate formatting

Parameters:
value - Lexical Value
datatype - Datatype

appendLiteral

public void appendLiteral(boolean b)
Appends a boolean to the command text as a constant using appropriate formatting

Parameters:
b - Boolean to append

appendLiteral

public void appendLiteral(int i)
Appends an integer to the command text as a constant using appropriate formatting

Parameters:
i - Integer to append

appendLiteral

public void appendLiteral(long l)
Appends a long to the command text as a constant using appropriate formatting

Parameters:
l - Long to append

appendLiteral

public void appendLiteral(float f)
Appends a float to the command text as a constant using appropriate formatting

Parameters:
f - Float to append

appendLiteral

public void appendLiteral(double d)
Appends a double to the command text as a constant using appropriate formatting

Parameters:
d - Double to append

appendLiteral

public void appendLiteral(Calendar dt)
Appends a date time to the command text as a constant using appropriate formatting

Parameters:
dt - Date Time to append

getCommandText

public String getCommandText()
Gets the basic Command Text

Note: This will not reflect any injected parameters, to see the command with injected parameters invoke the toString() method


setBaseUri

public void setBaseUri(String base)
Sets the Base URI which will be prepended to the query/update


getBaseUri

public String getBaseUri()
Gets the Base URI which will be prepended to a query


setParams

public void setParams(QuerySolutionMap map)
Sets the Parameters

Parameters:
map - Parameters

setParam

public void setParam(String var,
                     Node n)
Sets a Parameter

Parameters:
var - Variable
n - Value

Setting a parameter to null is equivalent to calling clearParam(String) for the given variable


setParam

public void setParam(String var,
                     RDFNode n)
Sets a Parameter

Parameters:
var - Variable
n - Value

Setting a parameter to null is equivalent to calling clearParam(String) for the given variable


setIri

public void setIri(String var,
                   String iri)
Sets a Parameter to an IRI

Parameters:
var - Variable
iri - IRI

Setting a parameter to null is equivalent to calling clearParam(String) for the given variable


setIri

public void setIri(String var,
                   org.apache.jena.iri.IRI iri)
Sets a Parameter to an IRI

Parameters:
var - Variable
iri - IRI

Setting a parameter to null is equivalent to calling clearParam(String) for the given variable


setIri

public void setIri(String var,
                   URL url)
Sets a Parameter to an IRI

Parameters:
var - Variable
url - URL used as IRI

Setting a parameter to null is equivalent to calling clearParam(String) for the given variable


setLiteral

public void setLiteral(String var,
                       Literal lit)
Sets a Parameter to a Literal

Parameters:
var - Variable
lit - Value

Setting a parameter to null is equivalent to calling clearParam(String) for the given variable


setLiteral

public void setLiteral(String var,
                       String value)
Seta a Parameter to a literal

Parameters:
var - Variable
value - Lexical Value

Setting a parameter to null is equivalent to calling clearParam(String) for the given variable


setLiteral

public void setLiteral(String var,
                       String value,
                       String lang)
Sets a Parameter to a literal with a language

Parameters:
var - Variable
value - Lexical Value
lang - Language

Setting a parameter to null is equivalent to calling clearParam(String) for the given variable


setLiteral

public void setLiteral(String var,
                       String value,
                       RDFDatatype datatype)
Sets a Parameter to a typed literal

Parameters:
var - Variable
value - Lexical Value
datatype - Datatype

Setting a parameter to null is equivalent to calling clearParam(String) for the given variable


setLiteral

public void setLiteral(String var,
                       boolean value)
Sets a Parameter to a boolean literal

Parameters:
var - a variable, by name.
value - boolean

setLiteral

public void setLiteral(String var,
                       int i)
Sets a Parameter to an integer literal

Parameters:
var - Variable
i - Integer Value

setLiteral

public void setLiteral(String var,
                       long l)
Sets a Parameter to an integer literal

Parameters:
var - Variable
l - Integer Value

setLiteral

public void setLiteral(String var,
                       float f)
Sets a Parameter to a float literal

Parameters:
var - Variable
f - Float value

setLiteral

public void setLiteral(String var,
                       double d)
Sets a Parameter to a double literal

Parameters:
var - Variable
d - Double value

setLiteral

public void setLiteral(String var,
                       Calendar dt)
Sets a Parameter to a date time literal

Parameters:
var - Variable
dt - Date Time value

getParam

public Node getParam(String var)
Gets the current value for a parameter

Parameters:
var - Variable
Returns:
Current value or null if not set

getVars

public Iterator<String> getVars()
Gets the variables which are currently treated as parameters (i.e. have values set for them)


clearParam

public void clearParam(String var)
Clears the value for a parameter so the given variable will not have a value injected

Parameters:
var - Variable

clearParams

public void clearParams()
Clears all values


toString

public String toString()
The toString() method is where the actual magic happens, the original command text is always preserved and we just generated a temporary command string by inserting the defined namespace prefixes at the start of the command and injecting the set parameters into a copy of that base string and return the resulting command.

This class makes no guarantees about the validity of the returned string for use as a SPARQL Query or Update, for example if a parameter was injected which was mentioned in the SELECT variables list you'd have a syntax error when you try to parse the query

Overrides:
toString in class Object

asQuery

public Query asQuery()
              throws QueryException
Attempts to take the command text with parameters injected from the toString() method and parse it as a Query

Returns:
Query if the command text is a valid SPARQL query
Throws:
QueryException - Thrown if the command text does not parse

asUpdate

public UpdateRequest asUpdate()
Attempts to take the command text with parameters injected from the toString() method and parse it as a UpdateRequest

Returns:
Update if the command text is a valid SPARQL Update request (one/more update commands)

copy

public ParameterizedSparqlString copy()
Makes a full copy of this parameterized string

Returns:
Copy of the string

copy

public ParameterizedSparqlString copy(boolean copyParams)
Makes a copy of the command text, base URI and prefix mapping and optionally copies parameter values

Parameters:
copyParams - Whether to copy parameters
Returns:
Copy of the string

copy

public ParameterizedSparqlString copy(boolean copyParams,
                                      boolean copyBase,
                                      boolean copyPrefixes)
Makes a copy of the command text and optionally copies other aspects

Parameters:
copyParams - Whether to copy parameters
copyBase - Whether to copy the Base URI
copyPrefixes - Whether to copy the prefix mappings
Returns:
Copy of the string

setNsPrefix

public PrefixMapping setNsPrefix(String prefix,
                                 String uri)
Specified by:
setNsPrefix in interface PrefixMapping

removeNsPrefix

public PrefixMapping removeNsPrefix(String prefix)
Specified by:
removeNsPrefix in interface PrefixMapping

setNsPrefixes

public PrefixMapping setNsPrefixes(PrefixMapping other)
Specified by:
setNsPrefixes in interface PrefixMapping

setNsPrefixes

public PrefixMapping setNsPrefixes(Map<String,String> map)
Specified by:
setNsPrefixes in interface PrefixMapping

withDefaultMappings

public PrefixMapping withDefaultMappings(PrefixMapping map)
Specified by:
withDefaultMappings in interface PrefixMapping

getNsPrefixURI

public String getNsPrefixURI(String prefix)
Specified by:
getNsPrefixURI in interface PrefixMapping

getNsURIPrefix

public String getNsURIPrefix(String uri)
Specified by:
getNsURIPrefix in interface PrefixMapping

getNsPrefixMap

public Map<String,String> getNsPrefixMap()
Specified by:
getNsPrefixMap in interface PrefixMapping

expandPrefix

public String expandPrefix(String prefixed)
Specified by:
expandPrefix in interface PrefixMapping

shortForm

public String shortForm(String uri)
Specified by:
shortForm in interface PrefixMapping

qnameFor

public String qnameFor(String uri)
Specified by:
qnameFor in interface PrefixMapping

lock

public PrefixMapping lock()
Specified by:
lock in interface PrefixMapping

samePrefixMappingAs

public boolean samePrefixMappingAs(PrefixMapping other)
Specified by:
samePrefixMappingAs in interface PrefixMapping


Licenced under the Apache License, Version 2.0