Oracle® XML Developer's Kit Programmer's Guide
10g Release 2 (10.1.2) Part No. B14033-01 |
|
Previous |
Next |
This chapter contains these topics:
Note: Use the new unified C API for new XDK and Oracle XML DB applications. The old C functions are deprecated and supported only for backward compatibility, but will not be enhanced. They will be removed in a future release.The new C API is described in Chapter 14, "XML Parser for C". |
The Oracle XVM Package implements the XSL Transformation (XSLT) language as specified in the W3C Recommendation of 16 November 1999. The package includes XSLT Compiler and XSLT Virtual Machine (XVM). The implementation by Oracle of the XSLT compiler and the XVM enables compilation of XSLT (Version 1.0) into bytecode format, which is executed by the virtual machine. XSLT Virtual Machine is the software implementation of a "CPU" designed to run compiled XSLT code. The virtual machine assumes a compiler compiling XSLT stylesheets to a sequence of bytecodes or machine instructions for the "XSLT CPU". The bytecode program is a platform-independent sequence of 2-byte units. It can be stored, cached and run on different XVMs. The XVM uses the bytecode programs to transform instance XML documents. This approach clearly separates compile-time from run-time computations and specifies a uniform way of exchanging data between instructions. The benefits of this approach are:
An XSLT stylesheet can be compiled, saved in a file, and re-used often, even on different platforms.
The XVM is significantly faster and uses less memory than other XSL processors.
The bytecodes are not language-dependent. There is no difference between code generated from a C or C++ XSLT compiler.
A typical scenario of using the package APIs has the following steps:
Create and use an XML meta-context object.
xctx = XmlCreate(&err,...);
Create and use an XSLT compiler object.
comp = XmlXvmCreateComp(xctx);
Compile an XSLT stylesheet or XPath expression and store or cache the resulting bytecode.
code = XmlXvmCompileFile(comp, xslFile, baseuri, flags, &err);
or
code = XmlXvmCompileDom (comp, xslDomdoc, flags, &err);
or
code = XmlXvmCompileXPath (comp, xpathexp, namespaces, &err);
Create and use an XVM object. The explicit stack size setting is needed when XVM terminates with a "Stack Overflow" message or when smaller memory footprints are required. See XmlXvmCreate()
.
vm = XmlXvmCreate(xctx, "StringStack", 32, "NodeStack", 24, NULL);
Set the output (optional). Default is a stream.
err = XmlXvmSetOutputDom (vm, NULL);
or
err = XmlXvmSetOutputStream(vm, &xvm_stream);
or
err = XmlXvmSetOutputSax(vm, &xvm_callback, NULL);
Set a stylesheet bytecode to the XVM object. Can be repeated with other bytecode.
len = XmlXvmGetBytecodeLength(code, &err); err = XmlXvmSetBytecodeBuffer(vm, code, len);
or
err = XmlXvmSetBytecodeFile (vm, xslBytecodeFile);
Transform an instance XML document or evaluate a compiled XPath expression. Can be repeated with the same or other XML documents.
err = XmlXvmTransformFile(vm, xmlFile, baseuri);
or
err = XmlXvmTransformDom (vm, xmlDomdoc);
or
obj = (xvmobj*)XmlXvmEvaluateXPath (vm, code, 1, 1, node);
Get the output tree fragment (if DOM output is set at step 5).
node = XmlXvmGetOutputDom (vm);
Delete the objects.
XmlXvmDestroy(vm); XmlXvmDestroyComp(comp); XmlDestroy(xctx);
The XVM processor is accessed from the command-line this way:
xvm
Usage:
xvm options xslfile xmlfile
xvm options xpath xmlfile
Options:
-c Compile xslfile. The bytecode is in "xmlfile.xvm". -ct Compile xslfile and transform xmlfile. -t Transform xmlfile using bytecode from xslfile. -xc Compile xpath. The bytecode is in "code.xvm". -xct Compile and evaluate xpath with xmlfile. -xt Evaluate XPath bytecode from xpath with xmlfile.
Examples:
xvm -ct db.xsl db.xml xvm -t db.xvm db.xml xvm -xct "doc/employee[15]/family" db.xml
The Oracle XSL/XPath Package implements the XSL Transformation (XSLT) language as specified in the W3C Recommendation of 16 November 1999. The package includes XSL Processor and XPath Processor. The Oracle implementation of XSL processor follows the more common design approach, which melts 'compiler' and 'processor' into one object.
A typical scenario of using the package APIs has the following steps:
Create and use an XML meta-context object.
xctx = XmlCreate(&err,...);
Parse the XSLT stylesheet.
xslDomdoc = XmlLoadDom(xctx, &err, "file", xslFile, "base_uri", baseuri, NULL);
Create an XSL Processor for the stylesheet
xslproc = XmlXslCreate (xctx, xslDomdoc, baseuri, &err);
Parse the instance XML document.
xmlDomdoc = XmlLoadDom(xctx, &err, "file", xmlFile, "base_uri", baseuri, NULL);
Set the output (optional). Default is DOM.
err = XmlXslSetOutputStream(xslproc, &stream);
Transform the XML document. This step can be repeated with the same or other XML documents.
err = XmlXslProcess (xslproc, xmlDomdoc, FALSE);
Get the output (if DOM).
node = XmlXslGetOutput(xslproc);
Delete objects.
XmlXslDestroy(xslproc); XmlDestroy(xctx);
A typical scenario of using the package APIs has the following steps:
Create and use an XML meta-context object.
xctx = XmlCreate(&err,...);
Parse the XML document or get the current node from already existing DOM.
node = XmlLoadDom(xctx, &err, "file", xmlFile, "base_uri", baseuri, NULL);
Create an XPath processor.
xptproc = XmlXPathCreateCtx(xctx, NULL, node, 0, NULL);
Parse the XPath expression.
exp = XmlXPathParse (xptproc, xpathexpr, &err);
Evaluate the XPath expression.
obj = XmlXPathEval(xptproc, exp, &err);
Delete the objects.
XmlXPathDestroyCtx (xptproc); XmlDestroy(xctx);
The Oracle XSL processor for C can be called as an executable by invoking bin/xsl:
xsl [switches] stylesheet instance or xsl -f [switches] [document filespec]
If no style sheet is provided, no output is generated. If there is a style sheet, but no output file, output goes to stdout
.
Table 15-1 lists the command line options.
Table 15-1 XSLT Processor for C: Command Line Options
Option | Description |
---|---|
-B BaseUri
|
Set the Base URI for XSLT processor: BaseUri of http://pqr/xsl.txt resolves pqr.txt to http://pqr/pqr.txt
|
-e encoding
|
Specify default input file encoding (-ee to force).
|
-E encoding
|
Specify DOM or SAX encoding. |
-f |
File - interpret as filespec, not URI. |
-G xptrexprs
|
Evaluates XPointer schema examples given in a file. |
-h |
Help - show this usage. (Use -hh for more options.)
|
-hh |
Show complete options list. |
-i n
|
Number of times to iterate the XSLT processing. |
-l language
|
Language for error reporting. |
-o XSLoutfile
|
Specifies output file of XSLT processor. |
-v |
Version - display parser version then exit. |
-V var value
|
Test top-level variables in C XSLT. |
-w |
Whitespace - preserve all whitespace. |
-W |
Warning - stop parsing after a warning. |
Oracle XSL Processor for C is provided with the database and the Application Server. It is also available for download from the OTN site:
$ORACLE_HOME/xdk/demo/c/parser/
directory contains several XML applications to illustrate how to use the XSLT for C.
Table 15-2 lists the files in that directory:
Table 15-2 XSLT for C Demo Files
Sample File Name | Description |
---|---|
|
Source for XSLSample program |
|
Expected output from XSLSample |
|
XML file that can be used with XSLSample |
i |
Stylesheet that can be used with XSLSample |
|
XML version of Shakespeare's play |
|
Sample usage of XSLT Virtual Machine and compiler. It takes two filenames as input - XML file and XSL stylesheet file. |
|
Sample usage of XSLT Virtual Machine and compiler. It takes XML file name and XPath expression as input. Generates the result of the evaluated XPath expression.
|
|
Sample usage of XSL/XPath processor. It takes XML file name and XPath expression as input. Generates the result of the evaluated XPath expression.
|
Change directories to the demo directory and read the README file. This will explain how to build the sample programs according to your operating system.
Here is the usage of XSLT processor sample XSLSample
, which takes two files as input, the XML file and the XSL stylesheet:
XSLSample xmlfile xslss