XQueryProcessor Class Reference

An XQueryProcessor represents a factory to compile, load and execute queries. More...

#include <XQueryProcessor.h>

Public Member Functions
	XQueryProcessor ()
	Default constructor.
	XQueryProcessor (SaxonProcessor *p, std::string cwd="")
	Constructor with the SaxonProcessor supplied.
	XQueryProcessor (const XQueryProcessor &other)
	XQueryProcessor copy constructor.
XQueryProcessor *	clone ()
	Create a clone of this XQueryProcessor object with the same internal state, which can be used in separate threads.
void	setContextItem (XdmItem *value)
	Set the initial context item for the query as an XdmItem.
void	setOutputFile (const char *outfile)
	Set the output file where the query result is sent.
void	setContextItemFromFile (const char *filename)
	Set the context item for the query as a source document.
void	setParameter (const char *name, XdmValue *value, bool withParam=true)
	Set the value of a parameter used in the query.
void	setLanguageVersion (const char *version)
	Set the XQuery language version for the XQuery compiler.
void	setStreaming (bool option)
	Say whether the query should be compiled and evaluated to use streaming.
bool	isStreaming ()
	Ask whether the streaming option has been set.
bool	removeParameter (const char *name)
	Remove a parameter (name, value) pair.
void	setProperty (const char *name, const char *value)
	Set a configuration property specific to the XQuery processor in use.
const char *	getProperty (const char *name)
	Get the value of a configuration property specified on the XQuery processor in use.
void	clearParameters (bool deleteValues=false)
	Clear parameter values set.
void	clearProperties ()
	Clear configuration property values set.
void	setUpdating (bool updating)
	Say whether the query is allowed to be updating.
void	executeQueryToFile (const char *infilename, const char *ofilename, const char *query, const char *encoding=nullptr)
	Execute a query, and save the result to file.
XdmValue *	executeQueryToValue (const char *infilename, const char *query, const char *encoding=nullptr)
	Execute a query, returning the result as an XdmValue.
const char *	executeQueryToString (const char *infilename, const char *query, const char *encoding=nullptr)
	Execute a query, returning the result as a string.
XdmValue *	runQueryToValue ()
	Execute a query as already configured for this XQueryProcessor, returning the result as an XdmValue.
const char *	runQueryToString ()
	Execute a query as already configured for this XQueryProcessor, returning the result as a string.
void	runQueryToFile ()
	Execute a query as already configured for this XQueryProcessor, and save the result to file.
void	declareNamespace (const char *prefix, const char *uri)
	Declare a namespace binding as part of the static context for queries compiled using this XQueryCompiler.
XdmValue *	getParameter (const char *name, bool withParam=true)
	Get the value of a parameter.
std::map< std::string, XdmValue * > &	getParameters ()
	Get all parameters as a std::map.
std::map< std::string, std::string > &	getProperties ()
	Get all configuration properties specified on the processor as a std::map.
void	setQueryFile (const char *filename)
	Compile a query file.
void	setQueryContent (const char *content)
	Compile a query supplied as a string.
void	setQueryBaseURI (const char *baseURI)
	Set the static base URI for the query.
const char *	getQueryBaseURI ()
	Get the static base URI for the query.
void	setcwd (const char *cwd)
	Set the current working directory.
const char *	getcwd ()
	Get the current working directory set on this XQueryProcessor.
const char *	checkException ()
	Check for thrown exceptions.
bool	exceptionOccurred ()
	Deprecated.
void	exceptionClear ()
	Deprecated.
const char *	getErrorMessage ()
	Deprecated.
const char *	getErrorCode ()
	Deprecated.
SaxonApiException *	getException ()
	Deprecated.
SaxonProcessor *	getSaxonProcessor ()
	Get the SaxonProcessor which created this XQueryProcessor.

Detailed Description

An XQueryProcessor represents a factory to compile, load and execute queries.

Constructor & Destructor Documentation

XQueryProcessor() [1/3]

XQueryProcessor::XQueryProcessor

(

)

Default constructor.

Creates a Saxon-HE XQuery processor

XQueryProcessor() [2/3]

XQueryProcessor::XQueryProcessor	(	SaxonProcessor *	p,
		std::string	cwd = "" )

Constructor with the SaxonProcessor supplied.

Parameters

p	- pointer to the SaxonProcessor object
cwd	- the current working directory. Default is the empty string

XQueryProcessor() [3/3]

XQueryProcessor::XQueryProcessor

(

const XQueryProcessor &

other

)

XQueryProcessor copy constructor.

Parameters

other

- XQueryProcessor

Member Function Documentation

checkException()

const char * XQueryProcessor::checkException

(

)

Check for thrown exceptions.

Returns

The main exception message if any has been thrown otherwise return nullptr

clearParameters()

void XQueryProcessor::clearParameters

(

bool

deleteValues = false

)

Clear parameter values set.

Default behaviour (false) is to leave XdmValues in memory. Individual pointers to XdmValue objects have to be deleted in the calling program.

Parameters

deleteValues

- if true then XdmValues are deleted

clone()

XQueryProcessor * XQueryProcessor::clone

(

)

Create a clone of this XQueryProcessor object with the same internal state, which can be used in separate threads.

Returns

A new copy of this XQueryProcessor object

declareNamespace()

void XQueryProcessor::declareNamespace	(	const char *	prefix,
		const char *	uri )

Declare a namespace binding as part of the static context for queries compiled using this XQueryCompiler.

This binding may be overridden by a binding that appears in the query prolog. The namespace binding will form part of the static context of the query, but it will not be copied into result trees unless the prefix is actually used in an element or attribute name.

Parameters

prefix	- the namespace prefix. If the value is a zero-length string, this method sets the default namespace for elements and types.
uri	- the namespace URI. It is possible to specify a zero-length string to "undeclare" a namespace; in this case the prefix will not be available for use, except in the case where the prefix is also a zero length string, in which case the absence of a prefix implies that the name is in no namespace.

Exceptions

SaxonApiException

if either the prefix or uri is nullptr

exceptionClear()

void XQueryProcessor::exceptionClear

(

)

Deprecated.

Clear any thrown exceptions

Deprecated

From 12.1 this method is no longer used, since exceptions are now thrown.

exceptionOccurred()

bool XQueryProcessor::exceptionOccurred

(

)

Deprecated.

Checks for pending exceptions without creating a local reference to the exception object

Returns

True when there is a pending exception; otherwise false

Deprecated

From 12.1 this method is no longer used, since exceptions are now thrown.

executeQueryToFile()

void XQueryProcessor::executeQueryToFile	(	const char *	infilename,
		const char *	ofilename,
		const char *	query,
		const char *	encoding = nullptr )

Execute a query, and save the result to file.

Parameters

infilename	- the file name of the source document
ofilename	- the file name where results will be stored
query	- the query supplied as a string
encoding	- the encoding of the query string. If not specified then the platform default encoding is used.

Exceptions

SaxonApiException

executeQueryToString()

const char * XQueryProcessor::executeQueryToString	(	const char *	infilename,
		const char *	query,
		const char *	encoding = nullptr )

Execute a query, returning the result as a string.

Parameters

infilename	- the file name of the source document
query	- the query supplied as a string
encoding	- the encoding of the query string. If not specified then the platform default encoding is used.

Returns

The result of the query serialized to a string. A zero length string is returned if the query result is an empty sequence. The caller is responsible for memory deallocation using operator delete.

Exceptions

SaxonApiException

executeQueryToValue()

XdmValue * XQueryProcessor::executeQueryToValue	(	const char *	infilename,
		const char *	query,
		const char *	encoding = nullptr )

Execute a query, returning the result as an XdmValue.

Parameters

infilename	- the file name of the source document
query	- the query supplied as a string
encoding	- the encoding of the query string. If not specified then the platform default encoding is used.

Returns

The result of the query as an XdmValue. The caller is responsible for memory deallocation.

Exceptions

SaxonApiException

getcwd()

const char * XQueryProcessor::getcwd

(

)

Get the current working directory set on this XQueryProcessor.

Memory deallocation is handled internally.

Returns

Current working directory

getErrorCode()

const char * XQueryProcessor::getErrorCode

(

)

Deprecated.

Get the first error code if there are any errors. After the execution of the query there may be a number of errors reported against it.

Returns

The error code of the exception

Deprecated

From 12.1 this method is no longer used, since exceptions are now thrown.

getErrorMessage()

const char * XQueryProcessor::getErrorMessage

(

)

Deprecated.

Get the first error message if there are any errors. A query may have a number of errors reported against it.

Returns

The message of the exception

Deprecated

From 12.1 this method is no longer used, since exceptions are now thrown.

getException()

SaxonApiException * XQueryProcessor::getException

(

)

Deprecated.

Get the SaxonApiException object created when we have an error. After the execution of the query if there is an error then a SaxonApiException is created.

Returns

The SaxonApiException object if there is an exception thrown, or nullptr otherwise

Deprecated

From 12.1 this method is no longer used, since exceptions are now thrown.

getParameter()

XdmValue * XQueryProcessor::getParameter	(	const char *	name,
		bool	withParam = true )

Get the value of a parameter.

Parameters

name	- the name of the parameter
withParam	- internal use only

Returns

The value of the parameter as an XdmValue

getParameters()

std::map< std::string, XdmValue * > & XQueryProcessor::getParameters

(

)

Get all parameters as a std::map.

Returns

An std:map with key as string name mapped to XdmValue.

getProperties()

std::map< std::string, std::string > & XQueryProcessor::getProperties

(

)

Get all configuration properties specified on the processor as a std::map.

Returns

Map of (string, string) pairs

getProperty()

const char * XQueryProcessor::getProperty

(

const char *

name

)

Get the value of a configuration property specified on the XQuery processor in use.

Parameters

name	- the name of the property

Returns

Value of the property or nullptr if the property is not found. Memory deallocation is handled internally.

getQueryBaseURI()

const char * XQueryProcessor::getQueryBaseURI

(

)

Get the static base URI for the query.

Returns

the static base URI

isStreaming()

bool XQueryProcessor::isStreaming

(

)

Ask whether the streaming option has been set.

That is, whether subsequent calls on compile() will compile queries to be capable of executing in streaming mode.

Returns

True if the streaming option has been set.

removeParameter()

bool XQueryProcessor::removeParameter

(

const char *

name

)

Remove a parameter (name, value) pair.

Parameters

name	- the name of the parameter

Returns

Outcome of the removal

runQueryToFile()

void XQueryProcessor::runQueryToFile

(

)

Execute a query as already configured for this XQueryProcessor, and save the result to file.

All configuration properties must set in advance - for instance supplying the query and the context item, and the file name for the result output.

Exceptions

SaxonApiException

runQueryToString()

const char * XQueryProcessor::runQueryToString

(

)

Execute a query as already configured for this XQueryProcessor, returning the result as a string.

All configuration properties must set in advance - for instance supplying the query and the context item.

Returns

The result of the query serialized to a string. A zero length string is returned if the query result is an empty sequence. The caller is responsible for memory deallocation using operator delete.

Exceptions

SaxonApiException

runQueryToValue()

XdmValue * XQueryProcessor::runQueryToValue

(

)

Execute a query as already configured for this XQueryProcessor, returning the result as an XdmValue.

All configuration properties must set in advance - for instance supplying the query and the context item.

Returns

The result of the query as an XdmValue. The caller is responsible for memory deallocation.

Exceptions

SaxonApiException

setContextItem()

void XQueryProcessor::setContextItem

(

XdmItem *

value

)

Set the initial context item for the query as an XdmItem.

Parameters

value

- the initial context item, or nullptr if there is to be no initial context item

setContextItemFromFile()

void XQueryProcessor::setContextItemFromFile

(

const char *

filename

)

Set the context item for the query as a source document.

Parameters

filename

- the name of the source document

setcwd()

void XQueryProcessor::setcwd

(

const char *

cwd

)

Set the current working directory.

Parameters

cwd	- current working directory

setLanguageVersion()

void XQueryProcessor::setLanguageVersion

(

const char *

version

)

Set the XQuery language version for the XQuery compiler.

Parameters

version

- "3.1" or "4.0" in the current Saxon release.

setOutputFile()

void XQueryProcessor::setOutputFile

(

const char *

outfile

)

Set the output file where the query result is sent.

Parameters

outfile

- the name of the file where results will be stored

setParameter()

void XQueryProcessor::setParameter	(	const char *	name,
		XdmValue *	value,
		bool	withParam = true )

Set the value of a parameter used in the query.

Parameters

name	- the name of the parameter, as a string. For a namespaced name use clark notation i.e. "{uri}local"
value	- value of the query parameter, or nullptr to clear a previously set value
withParam	- internal use only

setProperty()

void XQueryProcessor::setProperty	(	const char *	name,
		const char *	value )

Set a configuration property specific to the XQuery processor in use.

XQueryProcessor: set serialization properties (names start with '!' i.e. name "!method" -> "xml"), 'o':outfile name, 's': source as file name 'q': query file name, 'q': current by name, 'qs': string form of the query, 'base': set the base URI of the query, 'dtd': set DTD validation 'on' or 'off'

Parameters

name	- the name of the property
value	- the value of the property

setQueryBaseURI()

void XQueryProcessor::setQueryBaseURI

(

const char *

baseURI

)

Set the static base URI for the query.

Parameters

baseURI

- the static base URI; or nullptr to indicate that no base URI is available

setQueryContent()

void XQueryProcessor::setQueryContent

(

const char *

content

)

Compile a query supplied as a string.

The supplied query is cached for later execution.

Parameters

content

- the query supplied as a character string

setQueryFile()

void XQueryProcessor::setQueryFile

(

const char *

filename

)

Compile a query file.

The supplied query is cached for later execution.

Parameters

filename

- the file name of the query document

setStreaming()

void XQueryProcessor::setStreaming

(

bool

option

)

Say whether the query should be compiled and evaluated to use streaming.

This affects subsequent calls on the compile() methods. This option requires Saxon-EE.

Parameters

option

if true, the compiler will attempt to compile a query to be capable of executing in streaming mode. If the query cannot be streamed, a compile-time exception is reported. In streaming mode, the source document is supplied as a stream, and no tree is built in memory. The default is false. When setStreaming(true) is specified, this has the additional side effect of setting the required context item type to "document-node()"

setUpdating()

void XQueryProcessor::setUpdating

(

bool

updating

)

Say whether the query is allowed to be updating.

XQuery update syntax will be rejected during query compilation unless this flag is set. XQuery Update is supported only under Saxon-EE.

Parameters

updating

- true if the query is allowed to use the XQuery Update facility (requires Saxon-EE). If set to false, the query must not be an updating query. If set to true, it may be either an updating or a non-updating query.

---

The documentation for this class was generated from the following files:

• /Users/debbie/Work/refactor/saxon12/libsaxonc/src/include/saxonc/XQueryProcessor.h
• /Users/debbie/Work/refactor/saxon12/libsaxonc/src/lib/XQueryProcessor.cpp