Namespace Xml
Class CXsltProcessor

class CXsltProcessor: public Sax::CXmlReader {
public:
    CXsltProcessor(CToolkitBase *pToolkitBase);
    ~CXsltProcessor();
public:
    void SetFeature(
        const WCHAR *pszName, bool bValue);
    bool GetFeature(const WCHAR *pszName);
    void SetProperty(
        const WCHAR *pszName, 
        CInterface *pValue);
    CInterface *GetProperty(const WCHAR *pszName);
    void SetEntityResolver(Sax::CEntityResolver *pResolver);
    Sax::CEntityResolver *GetEntityResolver();
    void SetDtdHandler(Sax::CDtdHandler *pHandler);
    Sax::CDtdHandler *GetDtdHandler();
    void SetContentHandler(Sax::CContentHandler *pHandler);
    Sax::CContentHandler *GetContentHandler();
    void SetErrorHandler(Sax::CErrorHandler *pHandler);
    Sax::CErrorHandler *GetErrorHandler();
    void Parse(Sax::CInputSource *pInput);
    void Parse(const WCHAR *pszSystemId);
public:
    void SetNamespaces(bool bNamespaces);
    bool GetNamespaces();
    void SetInputSource(Sax::CInputSource *pInputSource);
    Sax::CInputSource *GetInputSource();
    void Start();
public:
    void SetSourceUri(const WCHAR *pszUri);
    CString GetSourceUri();
    void SetSourceNode(Dom::INode *pNode);
    Dom::XNode GetSourceNode();
    void SetSourceDirect(bool bDirect);
    bool GetSourceDirect();
    void SetSourceReader(Sax::CXmlReader *pReader);
    Sax::CXmlReader *GetSourceReader();
public:
    void SetStylesheetUri(const WCHAR *pszUri);
    CString GetStylesheetUri();
    void SetStylesheetNode(Dom::INode *pNode);
    Dom::XNode GetStylesheetNode();
    void SetStylesheetReader(Sax::CXmlReader *pReader);
    Sax::CXmlReader *GetStylesheetReader();
    void SetStylesheet(CXsltStylesheet *pStylesheet);
    CXsltStylesheet *GetStylesheet();
public:
    void SetResultUri(const WCHAR *pszUri);
    CString GetResultUri();
    void SetResultNode(Dom::INode *pNode);
    Dom::XNode GetResultNode();
    void SetResultHandler(Sax::CContentHandler *pHandler);
    Sax::CContentHandler *GetResultHandler();
public:
    void ResetParam();
    void SetParam(const WCHAR *pszName, bool bValue);
    void SetParam(const WCHAR *pszName, double dblValue);
    void SetParam(const WCHAR *pszName, const WCHAR *pszValue);
public:
    void Reset();
    };
typedef XInterface<CXsltProcessor> XXsltProcessor;

The XSLT processor.

XSLT processor is designed to transform XML documents using the XSL Transformations (XSLT) Version 1.0 technology. At present, the toolkit's XSLT processor fully implements the W3C XSLT 1.0 recommendation, with the single exception of format-number function.

Before starting the XSLT processor, the application programmer must specify the following properties:

• a source XML document
• a XSLT stylesheet
• a transformation result destination

• as a URI referencing a source XML document, an XSLT stylesheet, or a transformation result destination (see Uri for details of the URI support)
• as a SAX2 reader providing content of a source XML document or an XSLT stylesheet, or a SAX2 content handler consuming the content of a transformation result
• as a DOM/XDM node (both DOM and XDM models are supported) serving as the root for the content of a source XML document, an XSLT stylesheet, or a transformation result

When the source document is specified as a DOM/XDM root node, the XSLT processor will by default create an internal duplicate image of the source XML content before starting transformation. This is needed to achieve the compliance with XSLT processing model (for example, to handle the whitespaces in the source document properly). Such duplication may be undesirable in some cases. To avoid it, the toolkit provides a separate "direct" mode, which allows dealing with the source documents represented using XDM data model. When a direct mode is specified, the XSLT engine acts directly on the supplied XDM document tree, without consuming extra time and memory for building the internal duplicate. Note that direct mode is not available for source documents represented using DOM data model.

XSLT processors can participate in SAX content event producer/consumer pipelines. This feature is implemented by subclassing the Sax::CXmlReader class. Each XSLT processor object implements therefore the standard SAX XML reader interface and can be used in contexts where XML readers are required. A SAX content handler, which will consume the result produced by the XSLT processor can be registered using the SAX SetContentHandler method; the effect is equivalent to setting the result content handler using the proprietary SetResultHandler method of the XSLT processor. Note that effectively an XSLT processor may serve as a filter placed between a SAX XML reader and a SAX content handler, although formally XSLT processor is not a SAX XML filter.

An application programmer may pass the list of stylesheet parameters to the transformation engine. These parameters will be assigned to the XSLT parameters specified via top-level xsl:param stylesheet elements. Each parameter passed to the transformation engine is identified by its name, which must be an XML QName . Parameter names defined by the application programmer are converted to XSLT expanded names using the namespace declarations on the root element of the stylesheet. Expanded names are used for mapping between parameter values passed to the transformation engine and top-level xsl:param stylesheet elements.

Since:

1.50.00

Version:

1.50.00

Author:

Alexey Gokhberg

See Also:

CToolkitBase, Sax::CXmlReader, Dom::INode

CXsltProcessor

CXsltProcessor(CToolkitBase *pToolkitBase);

Constructs the XSLT processor.

Parameters:

pToolkitBase - the master toolkit base

~CXsltProcessor

~CXsltProcessor();

Destroys the XSLT processor.

SetFeature

void SetFeature(
    const WCHAR *pszName, bool bValue);

Sets the state of a feature.

See Sax::CXmlReader::SetFeature for a detailed discussion concerning SAX reader features.

Parameters:

pszName - the feature name, which is a fully-qualified URI

bValue - the requested state of the feature ( true or false )

GetFeature

bool GetFeature(const WCHAR *pszName);

Looks up the value of a feature.

See Sax::CXmlReader::GetFeature for a detailed discussion concerning SAX reader features.

Parameters:

pszName - the feature name, which is a fully-qualified URI

Returns:

the current state of the feature ( true or false )

SetProperty

void SetProperty(
    const WCHAR *pszName, 
    CInterface *pValue);

Sets the value of a property.

See Sax::CXmlReader::SetProperty for a detailed discussion concerning SAX reader properties.

Parameters:

pszName - the property name, which is a fully-qualified URI

pValue - the requested value for the property, which is an interface pointer

GetProperty

CInterface *GetProperty(const WCHAR *pszName);

Looks up the value of a property.

See Sax::CXmlReader::GetProperty for a detailed discussion concerning SAX reader properties.

Parameters:

pszName - the property name, which is a fully-qualified URI

Returns:

the current value of the property, which is an interface pointer

SetEntityResolver

void SetEntityResolver(Sax::CEntityResolver *pResolver);

Allows an application to register an entity resolver.

Note that XSLT processors do not use entity resolvers, and this method is a stub implemented for the formal SAX compatibility only.

Parameters:

pResolver - the entity resolver

GetEntityResolver

Sax::CEntityResolver *GetEntityResolver();

Gets the current entity resolver.

Returns:

the current entity resolver, or NULL if none has been registered

SetDtdHandler

void SetDtdHandler(Sax::CDtdHandler *pHandler);

Allows an application to register a DTD event handler.

Note that XSLT processors do not generate DTD events, and this method is a stub implemented for the formal SAX compatibility only.

Parameters:

pHandler - the DTD handler

GetDtdHandler

Sax::CDtdHandler *GetDtdHandler();

Gets the current DTD handler.

Returns:

the current DTD handler, or NULL if none has been registered

SetContentHandler

void SetContentHandler(Sax::CContentHandler *pHandler);

Allows an application to register a content event handler.

This method is equivalent to the proprietary method SetResultHandler of the XSLT processor.

Parameters:

pHandler - the content handler

GetContentHandler

Sax::CContentHandler *GetContentHandler();

Gets the current content handler.

Returns:

the current content handler, or NULL if none has been registered

SetErrorHandler

void SetErrorHandler(Sax::CErrorHandler *pHandler);

Allows an application to register an error event handler.

Note that XSLT processors do not generate error events, and this method is a stub implemented for the formal SAX compatibility only.

Parameters:

pHandler - the error handler

GetErrorHandler

Sax::CErrorHandler *GetErrorHandler();

Gets the current error handler.

Returns:

the current error handler, or NULL if none has been registered

Parse

void Parse(Sax::CInputSource *pInput);

Parses an XML document.

Note that, although implementing SAX XML reader interface, XSLT processors are not true XML parsers, and this method is a stub implemented for the formal SAX compatibility only. When called, this method throws Sax::CSaxNotSupportedException .

Parameters:

pInput - the input source for the top-level of the XML document

Parse

void Parse(const WCHAR *pszSystemId);

Parses an XML document from a system identifier (URI).

Note that, although implementing SAX XML reader interface, XSLT processors are not true XML parsers, and this method is a stub implemented for the formal SAX compatibility only. When called, this method throws Sax::CSaxNotSupportedException .

Parameters:

pszSystemId - the system identifier (URI)

SetNamespaces

void SetNamespaces(bool bNamespaces);

Specifies whether content events generated by the reader provide namespace information.

Parameters:

bNamespaces - true if content events generated by this reader must provide namespace information; false otherwise

GetNamespaces

bool GetNamespaces();

Tests whether content events generated by the reader provide namespace information.

Returns:

true if content events generated by this reader provide namespace information; false otherwise

SetInputSource

void SetInputSource(Sax::CInputSource *pInputSource);

Sets the input source.

Note that, although implementing SAX XML reader interface, XSLT processors are not true XML parsers, and this method is a stub implemented for the formal SAX compatibility only. When called, this method throws Sax::CSaxNotSupportedException .

Parameters:

pInputSource - the input source

GetInputSource

Sax::CInputSource *GetInputSource();

Gets the current input source.

Note that, although implementing SAX XML reader interface, XSLT processors are not true XML parsers, and this method is a stub implemented for the formal SAX compatibility only. When called, this method throws Sax::CSaxNotSupportedException .

Returns:

the current input source, or NULL if none has been registered

Start

void Start();

Starts the XSLT processor.

When started, the XSLT processor will transform the specified source document using the specified stylesheet; the output will be transferred to the specified result destination.

SetSourceUri

void SetSourceUri(const WCHAR *pszUri);

Sets an URI for a source XML document.

This URI is used as a definitive specification of a source XML document unless a source XML reader or a source DOM/XDM node is specified, in which case the URI serves for diagnostic purposes only.

See Uri for details of the URI support.

Parameters:

pszUri - the source XML document URI

GetSourceUri

CString GetSourceUri();

Returns the URI for a source XML document

Returns:

the URI for a source XML document, or the empty string if none was specified

SetSourceNode

void SetSourceNode(Dom::INode *pNode);

Sets a root node for a source XML document.

This method invalidates previous setting for a source XML reader or a source DOM/XDM node, if any.

Both DOM and XDM document models are supported, unless direct processing mode is set with SetSourceDirect , in which case only XDM model is allowed.

The root node must be either a document or an element.

Parameters:

pNode - the root node for a source XML document

GetSourceNode

Dom::XNode GetSourceNode();

Returns the root node for a source XML document.

Returns:

the root node for a source XML document, or NULL if non was specified

SetSourceDirect

void SetSourceDirect(bool bDirect);

Enables/disables direct source mode.

In the direct mode, the XSLT processor avoids building of the internal representation of the source document, using the specified source XDM node directly. Direct source mode is ignored if the source document is specified using URI or XML reader. It is an error if direct source mode is specified for a source DOM node; this error is detected and reported when the processor is started.

Parameters:

bDirect - true to enable direct source mode; false to disable it

GetSourceDirect

bool GetSourceDirect();

Returns the direct source mode settings.

Returns:

true if direct source mode is enables; false otherwise

SetSourceReader

void SetSourceReader(Sax::CXmlReader *pReader);

Sets a SAX reader for a source XML document.

This method invalidates previous setting for a source XML reader or a source DOM/XDM node, if any.

Parameters:

pReader - the SAX reader for a source XML document

GetSourceReader

Sax::CXmlReader *GetSourceReader();

Returns the SAX reader for a source XML document.

Returns:

the SAX reader for a source XML document, or NULL is none was specified

SetStylesheetUri

void SetStylesheetUri(const WCHAR *pszUri);

Sets an URI for an XSLT stylesheet.

This URI is used as a definitive specification of an XSLT stylesheet unless a stylesheet XML reader or a stylesheet DOM/XDM node is specified, in which case the URI serves for diagnostic purposes only.

See Uri for details of the URI support.

Parameters:

pszUri - the stylesheet URI

GetStylesheetUri

CString GetStylesheetUri();

Returns the URI for an XSLT stylesheet

Returns:

the URI for an XSLT stylesheet, or the empty string if none was specified

SetStylesheetNode

void SetStylesheetNode(Dom::INode *pNode);

Sets a root node for an XSLT stylesheet.

This method invalidates previous setting for a stylesheet XML reader, a stylesheet DOM/XDM node, or a precompiled stylesheet object, if any.

Both DOM and XDM document models are supported. The root node must be either a document or an element corresponding to a stylesheet root.

Parameters:

pNode - the root node for an XSLT stylesheet

GetStylesheetNode

Dom::XNode GetStylesheetNode();

Returns the root node for an XSLT stylesheet.

Returns:

the root node for an XSLT stylesheet, or NULL if none was specified

SetStylesheetReader

void SetStylesheetReader(Sax::CXmlReader *pReader);

Sets an XML reader for an XSLT stylesheet.

This method invalidates previous setting for a stylesheet XML reader, a stylesheet DOM/XDM node, or a precompiled stylesheet object, if any.

Parameters:

pReader - the XML reader for an XSLT stylesheet

GetStylesheetReader

Sax::CXmlReader *GetStylesheetReader();

Returns the XML reader for an XSLT stylesheet.

Returns:

the XML reader for an XSLT stylesheet, or NULL if none was specified

SetStylesheet

void SetStylesheet(CXsltStylesheet *pStylesheet);

Sets a precompiled XSLT stylesheet object.

This method invalidates previous setting for a stylesheet XML reader, a stylesheet DOM/XDM node, or a precompiled stylesheet object, if any.

Parameters:

pStylesheet - the precompiled stylesheet object

GetStylesheet

CXsltStylesheet *GetStylesheet();

Returns the precompiled XSLT stylesheet object.

Returns:

the precompiled XSLT stylesheet object, or NULL if none was specified

SetResultUri

void SetResultUri(const WCHAR *pszUri);

Sets an URI for a transformation result destination.

This URI is used as a definitive specification of a transformation result destination unless a result XML reader or a result DOM/XDM node is specified, in which case the URI serves for diagnostic purposes only.

See Uri for details of the URI support.

Parameters:

pszUri - the URI for a transformation result destination

GetResultUri

CString GetResultUri();

Returns the URI for a transformation result destination.

Returns:

the URI for a transformation result destination, or NULL if none was specified

SetResultNode

void SetResultNode(Dom::INode *pNode);

Sets a root node for a transformation result.

The transformation result will be converted to a newly constructed sub-tree built under the specified root node. In particular, if an empty document node is specified as the root, the entire document tree will be built as the result of transformation. The root node must be allowed to hold a type of content produced as the result of transformation.

This method invalidates previous setting for a result content handler or a result DOM/XDM node, if any.

Both DOM and XDM document models are supported.

Parameters:

pNode - the root node for a transformation result

GetResultNode

Dom::XNode GetResultNode();

Returns the root node for a transformation result.

Returns:

the root node for a transformation result, or NULL if none was specified

SetResultHandler

void SetResultHandler(Sax::CContentHandler *pHandler);

Sets a content handler for a transformation result.

This method invalidates previous setting for a result content handler or a result DOM/XDM node, if any.

This method is equivalent to the standard SAX method SetContentHandler .

Parameters:

pHandler - the content handler for a transformation result

GetResultHandler

Sax::CContentHandler *GetResultHandler();

Returns the content handler for a transformation result.

Returns:

the content handler for a transformation result, or NULL if none was specified

ResetParam

void ResetParam();

Makes the list of stylesheet parameters empty.

SetParam

void SetParam(const WCHAR *pszName, bool bValue);

Adds a boolean value to the list of stylesheet parameters.

Parameters:

pszName - the qualified name of the parameter

bValue - the boolean parameter value

SetParam

void SetParam(const WCHAR *pszName, double dblValue);

Adds a number value to the list of stylesheet parameters.

Parameters:

pszName - the qualified name of the parameter

dblValue - the number parameter value

SetParam

void SetParam(const WCHAR *pszName, const WCHAR *pszValue);

Adds a string value to the list of stylesheet parameters.

Parameters:

pszName - the qualified name of the parameter

pszValue - the string parameter value

Reset

void Reset();

Invalidates all XSLT processor properties describing a source XML document, an XSLT stylesheet, a transformation result destination, and stylesheet parameters.