27
PL/SQL XSLT Processing for XMLType

The Extensible Stylesheet Language (XSL) Package Processor APIs in the DBMS_XSLPROCESSOR Package enables PL/SQL developers to access the contents and structure of XML documents.

This chapter discusses the following topics:

• Description of DBMS_XSLPROCESSOR
• Subprograms of DBMS_XSLPROCESSOR

  See Also: Oracle9i XML Database Developer's Guide - Oracle XML DB Oracle9i Supplied PL/SQL Packages and Types Reference

---

DBMS_XSLPROCESSOR Package

---

Description of DBMS_XSLPROCESSOR

The Extensible Stylesheet Language Transformation (XSLT), describes rules for transforming a source tree into a result tree. A transformation expressed in XSLT is called a stylesheet. The transformation specified is achieved by associating patterns with templates defined in the stylesheet. A template is instantiated to create part of the result tree. This PL/SQL implementation of the XSL processor followed the W3C XSLT working draft (rev WD-xslt-19990813) and included the required behavior of an XSL processor in terms of how it must read XSLT stylesheets and the transformation it must effect.

The following is the default behavior for this PL/SQL XSL Processor:

• A result tree which can be accessed by DOM APIs is built
• Errors are not recorded unless an error log is specified; however, an application error will be raised if parsing fails

---

Subprograms of DBMS_XSLPROCESSOR

Table 27-1 Summary of Subprograms of DBMS_XSLPROCESSOR  

Subprogram	Description
newProcessor()	Returns a new processor instance.
processXSL()	Transforms an input XML document.
showWarnings()	Turns warnings on or off.
setErrorLog()	Sets errors to be sent to the specified file.
newStylesheet()	Creates a new stylesheet using the given input and reference URLs.
transformNode()	Transforms a node in a DOM tree using the given stylesheet.
selectNodes()	Selects nodes from a DOM tree that match the given pattern.
selectSingleNodes()	Selects the first node from the tree that matches the given pattern.
valueOf()	Retrieves the value of the first node from the tree that matches the given pattern
setParam()	Sets a top-level parameter in the stylesheet
removeParam()	Removes a top-level stylesheet parameter
resetParams()	Resets the top-level stylesheet parameters
freeStylesheet()	Frees a stylesheet object
freeProcessor()	Frees a processor object

newProcessor()

Description

Returns a new processor instance. This function must be called before the default behavior of Processor can be changed and if other processor methods need to be used.

Syntax

FUNCTION newProcessor RETURN Processor;

processXSL()

Description

Transforms input XML document. Any changes to the default processor behavior should be effected before calling this procedure. An application error is raised if processing fails. The options are described in the following table.

Syntax	Description
FUNCTION processXSL( p Processor, ss Stylesheet, xmldoc DOMDocument), RETURN DOMDocumentFragment;	Transforms input XML document using given DOMDocument and stylesheet, and returns the resultant document fragment.
FUNCTION processXSL( p Processor, ss Stylesheet, url VARCHAR2, RETURN DOMDocumentFragment;	Transforms input XML document using given document as URL and the stylesheet, and returns the resultant document fragment.
FUNCTION processXSL( p Processor, ss Stylesheet, clb CLOB) RETURN DOMDocumentFragment;	Transforms input XML document using given document as CLOB and the stylesheet, and returns the resultant document fragment.
PROCEDURE processXSL( p Processor, ss Stylesheet, xmldoc DOMDocument, dir VARCHAR2, fileName VARCHAR2);	Transforms input XML document using given DOMDocument and the stylesheet, and writes the output to the specified file.
PROCEDURE processXSL( p Processor, ss Stylesheet, url VARCHAR2, dir VARCHAR2, fileName VARCHAR2);	Transforms input XML document using given URL and the stylesheet, and writes the output to the specified file in a specified directory.
PROCEDURE processXSL( p Processor, ss Stylesheet, xmldoc DOMDocument, cl IN OUT CLOB);	Transforms input XML document using given DOMDocument and the stylesheet, and writes the output to a CLOB.
FUNCTION processXSL( p Processor, ss Stylesheet, xmldf DOMDocumentFragment) RETURN DOMDocumentFragment;	Transforms input XML DocumentFragment using given DOMDocumentFragment and the stylesheet, and returns the resultant document fragment.
PROCEDURE processXSL( p Processor, ss Stylesheet, xmldf DOMDocumentFragment, dir VARCHAR2, fileName VARCHAR2);	Transforms input XML DocumentFragment using given DOMDocumentFragment and the stylesheet, and writes the output to the specified file in a specified directory.
PROCEDURE processXSL( p Processor, ss Stylesheet, xmldf DOMDocumentFragment, buf IN OUT VARCHAR2);	Transforms input XML DocumentFragment using given DOMDocumentFragment and the stylesheet, and writes the output to a buffer.
PROCEDURE processXSL( p Processor, ss Stylesheet, xmldf DOMDocumentFragment, cl IN OUT CLOB);	Transforms input XML DocumentFragment using given DOMDocumentFragment and the stylesheet, and writes the output to a CLOB.

Parameter	IN / OUT	Description
p	(IN)	Processor instance.
ss	(IN)	Stylesheet instance.
xmldoc	(IN)	XML document being transformed.
url	(IN)	URL for the information being transformed.
clb	(IN)	CLOB containing information to be transformed.
dir	(IN)	Directory where processing output file is saved.
fileName	(IN)	Processing output file.
cl	(IN/OUT)	CLOB to which the processing output is saved.
buf	(IN/OUT)	Buffer to which the processing output is saved.
xmldf	(IN)	XML document fragment being transformed.

showWarnings()

Description

Turns warnings on (TRUE) or off (FALSE).

Syntax

PROCEDURE showWarnings( p Processor,
                        yes BOOLEAN);

Parameter	IN / OUT	Description
p	(IN)	Processor instance.
yes	(IN)	Mode to set: TRUE to show warnings, FALSE otherwise

setErrorLog()

Description

Sets errors to be sent to the specified file.

Syntax

PROCEDURE setErrorLog( p Processor,
                       fileName VARCHAR2);

Parameter	IN / OUT	Description
p	(IN)	Processor instance.
fileName	(IN)	complete path of the file to use as the error log.

newStylesheet()

Description

Creates and returns a new stylesheet instance. The options are described in the following table.

Syntax	Description
FUNCTION newStylesheet( xmldoc DOMDocument, ref VARCHAR2) RETURN Stylesheet;	Creates and returns a new stylesheet instance using the given DOMDocument and reference URLs.
FUNCTION newStylesheet( inp VARCHAR2, ref VARCHAR2) RETURN Stylesheet;	Creates and returns a new stylesheet instance using the given input and reference URLs.

Parameter	IN / OUT	Description
xmldoc	(IN)	DOMDocument to use for construction.
inp	(IN)	Input URL to use for construction.
ref	(IN)	Reference URL

transformNode()

Description

Transforms a node in a DOM tree using the given stylesheet, and returns the result of the transformation as a DOMDocumentFragment.

Syntax

FUNCTION transformNode( n DOMNode,
                        ss Stylesheet)
                        RETURN DOMDocumentFragment;

Parameter	IN / OUT	Description
n	(IN)	DOMNode to transform.
ss	(IN)	Stylesheet to use.

selectNodes()

Description

Selects nodes which match the given pattern from a DOM tree, and returns the result of the selection.

Syntax

FUNCTION selectNodes( n DOMNode,
                      pattern VARCHAR2)
                      RETURN DOMNodeList;

Parameter	IN / OUT	Description
n	(IN)	Root DOMNode of the tree.
pattern	(IN)	Pattern to use.

selectSingleNodes()

Description

Selects the first node from the tree that matches the given pattern, and returns that node.

Syntax

FUNCTION selectSingleNodes( n DOMNode,
                            pattern VARCHAR2)
                            RETURN DOMNode;

Parameter	IN / OUT	Description
n	(IN)	Root DOMNode of the tree.
pattern	(IN)	Pattern to use.

valueOf()

Description

Retrieves the value of the first node from the tree that matches the given pattern.

Syntax

PROCEDURE valueOf( n DOMNode,
                   pattern VARCHAR2,
                   val OUT VARCHAR2);

Parameter	IN / OUT	Description
n	(IN)	Root DOMNode of the tree.
pattern	(IN)	Pattern to use.
val	(OUT)	Retrieved value.

setParam()

Description

Sets a top level parameter in the stylesheet. The parameter value must be a valid XPath expression. Literal string values must be quoted.

Syntax

PROCEDURE setParam( ss Stylesheet,
                    name VARCHAR2,
                    value VARCHAR2);

Parameter	IN / OUT	Description
ss	(IN)	Stylesheet.
name	(IN)	Name of the parameter.
value	(IN)	Value of the parameter.

removeParam()

Description

Removes a top level stylesheet parameter.

Syntax

PROCEDURE removeParam( ss Stylesheet,
                       name VARCHAR2);

Parameter	IN / OUT	Description
ss	(IN)	Stylesheet.
name	(IN)	Name of the parameter.

resetParams()

Description

Resets the top-level stylesheet parameters.

Syntax

PROCEDURE resetParams( ss Stylesheet);

Parameter	IN / OUT	Description
ss	(IN)	Stylesheet.

freeStylesheet()

Description

Frees a Stylesheet object.

Syntax

PROCEDURE freestylesheet( ss Stylesheet);

Parameter	IN / OUT	Description
ss	(IN)	Stylesheet.

freeProcessor()

Description

Frees a Processor object.

Syntax

PROCEDURE freeProccessor( p Processor);

Parameter	IN / OUT	Description
p	(IN)	Processor.