Xslt30Processor Class Reference

An Xslt30Processor represents a factory to compile, load and execute stylesheets. More...

#include <Xslt30Processor.h>

Public Member Functions
	Xslt30Processor ()
	Default constructor.
	Xslt30Processor (SaxonProcessor *proc, std::string cwd="")
	Constructor with the SaxonProcessor supplied.
	Xslt30Processor (const Xslt30Processor &other)
	Xslt30Processor copy constructor.
SaxonProcessor *	getSaxonProcessor ()
	Get the SaxonProcessor object.
void	setcwd (const char *cwd)
	Set the current working directory (cwd).
const char *	getcwd ()
	Get the current working directory (cwd).
void	useSchema (XsdSchema *schema, const char *role="")
	Set the XsdSchema to be used with this Xslt30Processor.
void	setSchemaAware (bool schemaAware)
	Say that the stylesheet must be compiled to be schema-aware, even if it contains no xsl:import-schema declarations.
bool	isSchemaAware ()
void	setBaseOutputURI (const char *baseURI)
	Set the base output URI.
void	setJustInTimeCompilation (bool jit)
	Say whether just-in-time compilation of template rules should be used.
bool	getJustInTimeCompilation ()
	Get the status of the just-in-time compilation flag.
void	setTargetEdition (const char *edition)
	Set the target edition under which the stylesheet will be executed.
void	setXsltLanguageVersion (const char *version)
	Set the XSLT (and XPath) language level to be supported by the processor.
void	setFastCompilation (bool fast)
	Request fast compilation.
void	setRelocatable (bool relocatable)
	Indicate that packages compiled by this processor are deployable to a different location.
void	setParameter (const char *name, XdmValue *value)
	Set the value of a stylesheet parameter.
XdmValue *	getParameter (const char *name)
	Get the value of a stylesheet parameter.
bool	removeParameter (const char *name)
	Remove a parameter (name, value) pair from a stylesheet.
std::map< std::string, XdmValue * > &	getParameters ()
	Get all parameters as a std::map.
void	clearParameters (bool deleteValues=false)
	Clear stylesheet parameter values set.
char **	createCharArray (int len)
	Utility method for working with SaxonC on Python - internal use only.
void	deleteXdmValueArray (XdmValue **arr, int len)
	Utility method for Python API - internal use only.
void	transformFileToFile (const char *sourcefile, const char *stylesheetfile, const char *outputfile)
	Perform a one shot transformation.
const char *	transformFileToString (const char *sourcefile, const char *stylesheetfile)
	Perform a one shot transformation.
XdmValue *	transformFileToValue (const char *sourcefile, const char *stylesheetfile)
	Perform a one shot transformation.
void	importPackage (const char *packageFile)
	Import a library package.
XsltExecutable *	compileFromFile (const char *stylesheet)
	Compile a stylesheet file.
XsltExecutable *	compileFromString (const char *stylesheet, const char *encoding=nullptr)
	Compile a stylesheet supplied as a string.
XsltExecutable *	compileFromAssociatedFile (const char *sourceFile)
	Compile a stylesheet as referenced in a specified XML document via the xml-stylesheet processing instruction.
void	compileFromStringAndSave (const char *stylesheet, const char *filename, const char *encoding=nullptr)
	Compile a stylesheet received as a string and save to an exported file (SEF).
void	compileFromFileAndSave (const char *xslFilename, const char *filename)
	Compile a stylesheet received as a file and save to an exported file (SEF).
void	compileFromXdmNodeAndSave (XdmNode *node, const char *filename)
	Compile a stylesheet received as an XdmNode.
XsltExecutable *	compileFromXdmNode (XdmNode *node)
	Compile a stylesheet received as an XdmNode.

Friends
class	XsltExecutable

Detailed Description

An Xslt30Processor represents a factory to compile, load and execute stylesheets.

It is possible to cache the context and the stylesheet in the Xslt30Processor.

Constructor & Destructor Documentation

Xslt30Processor() [1/3]

Xslt30Processor::Xslt30Processor

(

)

Default constructor.

Creates a Saxon-HE XSLT processor

Exceptions

SaxonApiException

Xslt30Processor() [2/3]

Xslt30Processor::Xslt30Processor	(	SaxonProcessor *	proc,
		std::string	cwd = "" )

Constructor with the SaxonProcessor supplied.

Parameters

proc	- pointer to the SaxonProcessor object
cwd	- the current working directory

Exceptions

SaxonApiException

Xslt30Processor() [3/3]

Xslt30Processor::Xslt30Processor

(

const Xslt30Processor &

other

)

Xslt30Processor copy constructor.

Parameters

other

- Xslt30Processor

Member Function Documentation

clearParameters()

void Xslt30Processor::clearParameters

(

bool

deleteValues = false

)

Clear stylesheet 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

compileFromAssociatedFile()

XsltExecutable * Xslt30Processor::compileFromAssociatedFile

(

const char *

sourceFile

)

Compile a stylesheet as referenced in a specified XML document via the xml-stylesheet processing instruction.

Note: the term "compile" here indicates that the stylesheet is converted into an executable form. The compilation uses a snapshot of the properties of the Xslt30Processor at the time this method is invoked.

Parameters

sourceFile

- the file name of the XML document

Returns

An XsltExecutable, which represents the compiled stylesheet. The XsltExecutable is immutable and thread-safe; it may be used to run multiple transformations, in series or concurrently. The caller is responsible for memory deallocation using delete.

Exceptions

SaxonApiException

if the compilation of the stylesheet fails

compileFromFile()

XsltExecutable * Xslt30Processor::compileFromFile

(

const char *

stylesheet

)

Compile a stylesheet file.

Note: the term "compile" here indicates that the stylesheet is converted into an executable form. The compilation uses a snapshot of the properties of the Xslt30Processor at the time this method is invoked.

Parameters

stylesheet

- the file name of the stylesheet document

Returns

An XsltExecutable, which represents the compiled stylesheet. The XsltExecutable is immutable and thread-safe; it may be used to run multiple transformations, in series or concurrently. The caller is responsible for memory deallocation using delete.

Exceptions

SaxonApiException

if the compilation of the stylesheet fails

compileFromFileAndSave()

void Xslt30Processor::compileFromFileAndSave	(	const char *	xslFilename,
		const char *	filename )

Compile a stylesheet received as a file and save to an exported file (SEF).

The compiled stylesheet is saved as SEF to file store.

Parameters

xslFilename	- file name of the stylesheet
filename	- the file to which the compiled package should be saved

Exceptions

SaxonApiException

if the compilation of the stylesheet fails

compileFromString()

XsltExecutable * Xslt30Processor::compileFromString	(	const char *	stylesheet,
		const char *	encoding = nullptr )

Compile a stylesheet supplied as a string.

Note: the term "compile" here indicates that the stylesheet is converted into an executable form. The compilation uses a snapshot of the properties of the Xslt30Processor at the time this method is invoked.

Parameters

stylesheet	- the stylesheet as a lexical string representation
encoding	- the encoding of the stylesheet string. If not specified then the platform default encoding is used.

Returns

An XsltExecutable, which represents the compiled stylesheet. The XsltExecutable is immutable and thread-safe; it may be used to run multiple transformations, in series or concurrently. The caller is responsible for memory deallocation using delete.

Exceptions

SaxonApiException

if the compilation of the stylesheet fails

compileFromStringAndSave()

void Xslt30Processor::compileFromStringAndSave	(	const char *	stylesheet,
		const char *	filename,
		const char *	encoding = nullptr )

Compile a stylesheet received as a string and save to an exported file (SEF).

The compiled stylesheet is saved as SEF to file store.

Parameters

stylesheet	- the stylesheet as a lexical string representation
filename	- the file to which the compiled package should be saved
encoding	- the string encoding of the filename. Defaults to JVM default

Exceptions

SaxonApiException

if the compilation of the stylesheet fails

compileFromXdmNode()

XsltExecutable * Xslt30Processor::compileFromXdmNode

(

XdmNode *

node

)

Compile a stylesheet received as an XdmNode.

Note: the term "compile" here indicates that the stylesheet is converted into an executable form. The compilation uses a snapshot of the properties of the Xslt30Processor at the time this method is invoked.

Parameters

node	- the XdmNode object for the stylesheet

Returns

An XsltExecutable, which represents the compiled stylesheet. The XsltExecutable is immutable and thread-safe; it may be used to run multiple transformations, in series or concurrently. The caller is responsible for memory deallocation using delete.

Exceptions

SaxonApiException

if the compilation of the stylesheet fails

compileFromXdmNodeAndSave()

void Xslt30Processor::compileFromXdmNodeAndSave	(	XdmNode *	node,
		const char *	filename )

Compile a stylesheet received as an XdmNode.

The compiled stylesheet is cached and available for execution later.

Parameters

node	- the XdmNode object for the stylesheet
filename	- the file to which the compiled package should be saved

Exceptions

SaxonApiException

if the compilation of the stylesheet fails

deleteXdmValueArray()

void Xslt30Processor::deleteXdmValueArray ( XdmValue ** arr, int len )

inline

Utility method for Python API - internal use only.

This method deletes a XdmValue pointer array

Parameters

arr	- XdmValue pointer array
len	- length of the array

getcwd()

const char * Xslt30Processor::getcwd

(

)

Get the current working directory (cwd).

Memory deallocation is handled internally. The cwd is used to set the base URI is part of the static context, and is used to resolve any relative URIs appearing within XSLT.

Returns

Current working directory

getJustInTimeCompilation()

bool Xslt30Processor::getJustInTimeCompilation

(

)

Get the status of the just-in-time compilation flag.

Recommendation: disable this option unless you are confident that the stylesheet you are compiling is error-free.

Returns

Status of the just-in-time compilation flag

getParameter()

XdmValue * Xslt30Processor::getParameter

(

const char *

name

)

Get the value of a stylesheet parameter.

Parameters

name	- the name of the stylesheet parameter

Returns

The value of the parameter as an XdmValue

getParameters()

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

(

)

Get all parameters as a std::map.

Please note that the key name has been prefixed with 'param:', for example 'param:name'

Returns

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

getSaxonProcessor()

SaxonProcessor * Xslt30Processor::getSaxonProcessor

(

)

Get the SaxonProcessor object.

Returns

Pointer to the SaxonProcessor object

importPackage()

void Xslt30Processor::importPackage

(

const char *

packageFile

)

Import a library package.

Calling this method makes the supplied package available for reference in the xsl:use-package declarations of subsequent compilations performed using this Xslt30Processor.

Parameters

packageFile

- the file name of the package to be imported, which should be supplied as an SEF. If relative, the file name of the SEF is resolved against the cwd, which is set using setcwd().

removeParameter()

bool Xslt30Processor::removeParameter

(

const char *

name

)

Remove a parameter (name, value) pair from a stylesheet.

Parameters

name	- the name of the stylesheet parameter

Returns

Outcome of the removal

setBaseOutputURI()

void Xslt30Processor::setBaseOutputURI

(

const char *

baseURI

)

Set the base output URI.

The base output URI is used for resolving relative URIs in the href attribute of the xsl:result-document instruction; it is accessible to XSLT stylesheet code using the XPath current-output-uri() function

Parameters

baseURI

- the base output URI

setcwd()

void Xslt30Processor::setcwd

(

const char *

cwd

)

Set the current working directory (cwd).

This method also applies to the static base URI for XSLT stylesheets when supplied as lexical string. The cwd is used to set the base URI is part of the static context, and is used to resolve any relative URIs appearing within XSLT.

Parameters

cwd	- current working directory

setFastCompilation()

void Xslt30Processor::setFastCompilation

(

bool

fast

)

Request fast compilation.

Fast compilation will generally be achieved at the expense of run-time performance and quality of diagnostics. Fast compilation is a good trade-off if (a) the stylesheet is known to be correct, and (b) once compiled, it is only executed once against a document of modest size.

Fast compilation may result in static errors going unreported, especially if they occur in code that is never executed.

The current implementation is equivalent to switching off all optimizations other than just-in-time compilation of template rules. Setting this option, however, indicates an intent rather than a mechanism, and the implementation details may change in future to reflect the intent.

Parameters

fast	- set to true to request fast compilation; set to false to revert to the optimization options defined in the Configuration.

setJustInTimeCompilation()

void Xslt30Processor::setJustInTimeCompilation

(

bool

jit

)

Say whether just-in-time compilation of template rules should be used.

Recommendation: disable this option unless you are confident that the stylesheet you are compiling is error-free.

Parameters

jit

- true if just-in-time compilation is to be enabled. With this option enabled, static analysis of a template rule is deferred until the first time that the template is matched. This can improve performance when many template rules are rarely used during the course of a particular transformation; however, it means that static errors in the stylesheet will not necessarily cause the compile(Source) method to throw an exception (errors in code that is actually executed will still be notified to the registered ErrorListener or ErrorList, but this may happen after the compile(Source) method returns). This option is enabled by default in Saxon-EE, and is not available in Saxon-HE or Saxon-PE.

setParameter()

void Xslt30Processor::setParameter	(	const char *	name,
		XdmValue *	value )

Set the value of a stylesheet parameter.

Static (compile-time) parameters must be provided using this method, prior to stylesheet compilation. Non-static parameters may also be provided using this method if their values will not vary from one transformation to another.

Parameters

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

setRelocatable()

void Xslt30Processor::setRelocatable

(

bool

relocatable

)

Indicate that packages compiled by this processor are deployable to a different location.

Say whether any package produced by this compiler can be deployed to a different location, with a different base URI.

Parameters

relocatable

- if true then static-base-uri() represents the deployed location of the package, rather than its compile time location

setSchemaAware()

void Xslt30Processor::setSchemaAware

(

bool

schemaAware

)

Say that the stylesheet must be compiled to be schema-aware, even if it contains no xsl:import-schema declarations.

By default a stylesheet is treated as schema-aware only if it contains one or more xsl:import-schema declarations. If it is not schema-aware, then all input documents must be untyped, and validation of temporary trees is disallowed (though validation of the final result tree is permitted). Setting the argument to true means that schema-aware code will be compiled regardless.

Setting the value to true has no effect (it is not an error) if the configuration does not support schema processing. (Schema processing requires a Saxon-EE license.)

Parameters

schemaAware

true if expressions are to be schema-aware, false otherwise

Exceptions

SaxonApiException

if schema-awareness is requested when this is not a licensed Saxon-EE configuration.

Since

13.

setTargetEdition()

void Xslt30Processor::setTargetEdition

(

const char *

edition

)

Set the target edition under which the stylesheet will be executed.

Parameters

edition

- the Saxon edition for the run-time environment. One of "EE", "PE", "HE", or "JS", "JS2", or "JS3".

setXsltLanguageVersion()

void Xslt30Processor::setXsltLanguageVersion

(

const char *

version

)

Set the XSLT (and XPath) language level to be supported by the processor.

Set the value to "4.0" to enable support for experimental features defined in the XSLT 4.0 proposal (which is likely to change before it stabilizes).

Parameters

version

- the language level to be supported. The values "3.0" and "4.0" are recognized

transformFileToFile()

void Xslt30Processor::transformFileToFile	(	const char *	sourcefile,
		const char *	stylesheetfile,
		const char *	outputfile )

Perform a one shot transformation.

The result is stored in the specified output file.

Parameters

sourcefile	- the file name of the source document
stylesheetfile	- the file name of the stylesheet document
outputfile	- the file name where results will be stored

Exceptions

SaxonApiException

if the transformation fails

transformFileToString()

const char * Xslt30Processor::transformFileToString	(	const char *	sourcefile,
		const char *	stylesheetfile )

Perform a one shot transformation.

The result is returned as a string.

Parameters

sourcefile	- the file name of the source document
stylesheetfile	- the file name of the stylesheet document

Returns

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

Exceptions

SaxonApiException

if the transformation fails

transformFileToValue()

XdmValue * Xslt30Processor::transformFileToValue	(	const char *	sourcefile,
		const char *	stylesheetfile )

Perform a one shot transformation.

The result is returned as an XdmValue

Parameters

sourcefile	- the file name of the source document
stylesheetfile	- the file name of the stylesheet document

Returns

The result of the transformation as an XdmValue. The caller is responsible for memory deallocation using delete.

Exceptions

SaxonApiException

if the transformation fails

useSchema()

void Xslt30Processor::useSchema	(	XsdSchema *	schema,
		const char *	role = "" )

Set the XsdSchema to be used with this Xslt30Processor.

Set the XsdSchema to be used with this Xslt30Processor for a schema-aware transformation (requires SaxonC-EE). Equivalent to useSchema("", schema)

Parameters

schema	the schema to be imported
role	the schema role. Set this to "" (an empty string) or to null for the default (unnamed) schema role. If a role name is specified then the supplied schema is ignored unless the stylesheet actually contains an xsl:import-schema declaration for this schema role.

Since

13.0

---

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

• /Users/debbie/Work/refactor/saxondev/libsaxonc/src/include/saxonc/Xslt30Processor.h
• /Users/debbie/Work/refactor/saxondev/libsaxonc/src/lib/Xslt30Processor.cpp