






















|
| |
To perform a transformation, use one of the
XalanTransformer
transform() methods. The transformation requires an XML source
document and an XSL stylesheet. Both of these objects may be
represented by instances of
XSLTInputSource
. You can construct an XSLTInputSource with a string (the
system ID for a file or URI), an input stream, or a DOM.
If you are using an XSL stylesheet to perform a series of
transformations, you can improve performance by calling transform()
with a compiled stylesheet, an instance of
XalanCompiledStylesheet. If you are transforming an XML
source more than once, you should call transform() with a parsed XML
source, an instance of
XalanParsedSource. See Performing
a series of transformations.
If you XML source document contains a stylesheet Processing
Instruction (PI), you do not need to include a stylesheet object
when you call transform().
The transformation output is represented by an
XSLTResultTarget
, which you can set up to refer to an output stream, the
system ID for a file or URI, or a Formatter for one of the various
styles of DOM output.
For detailed API documentation, see
Xalan-C++ API. For an overview
of the command-line utility, see
Command-Line Utility.
|
 |  |  |  | Basic usage patten with the XalanTransformer C++ API |  |  |  |  |
| |
Using XalanTransformer and the C++ API, you can perform one or more transformations as described in the following steps.
 |
For a working sample that illustrates these steps, see the XalanTransform sample.
|
 |  |  |  | 4. Create a XalanTransformer. |  |  |  |  |
| |
 |  |  |  |
XalanTransformer theXalanTransformer;
|  |  |  |  |
|
 |  |  |  | 5. Perform each transformation. |  |  |  |  |
| |
You can explicitly instantiate
XSLTInputSource
objects for the XML source document and XSL stylesheet,
and an
XSLTResultTarget object for the output, and then call
XalanTransformer
transform() with those objects as parameters. For example:
 |  |  |  |
XSLTInputSource xmlIn("foo.xml");
XSLTInputSource xslIn("foo.xsl");
XSLTResultTarget xmlOut("foo-out.xml");
int theResult =
theXalanTransformer.transform(xmlIn,xslIn,xmlOut)
|  |  |  |  |
Alternatively, you can call transform() with the strings (system
identifiers), streams, and/or DOMs that the compiler needs to
implicitly construct the
XSLTInputSource
and
XSLTResultTarget objects. For example:
 |  |  |  |
const char* xmlIn = "foo.xml";
const char* xslIn = "foo.xsl";
const char* xmlOut = "foo-out.xml";
int theResult =
theXalanTransformer.transform(xmlIn,xslIn,xmlOut)
|  |  |  |  |
Keep in mind that
XSLTInputSource and
XSLTResultTarget
provide a variety of single-argument constructors that you
can use in this manner:
XSLTInputSource(const char* systemID);
XSLTInputSource(const XMLCh* systemID);//Unicode chars
XSLTInputSource(istream* stream);
XSLTInputSource(XalanNode* node);
XSLTResultTarget(char* fileName);
XSLTResultTarget(XalanDOMString& fileName);
XSLTResultTarget(ostream* stream);
XSLTResultTarget(ostream& stream);
XSLTResultTarget(Writer* characterStream);
XSLTResultTarget(XalanDocument* document);
XSLTResultTarget(XalanDocumentFragment* documentFragment);
XSLTResultTarget(XalanElement* element);
XSLTResultTarget(FormatterListener& flistener);
 |
Each transform() method returns an integer code, 0 for success. If
an error occurs, you can use the getLastError() method to return
a pointer to the error message.
|
|
|
 |  |  |  | Setting stylesheet parameters |  |  |  |  |
| |
An XSL stylesheet can include parameters that are set at run time
before a transformation takes place. When we generate the HTML
documents that make up the Xalan doc set, for example, we send the
stylesheet an id parameter along with each XML source document. The
id identifies that document and enables the stylesheet to integrate
it into the overall doc set.
To set a stylesheet parameter, use the
XalanTransformer
setStylesheetParam() method. The setStytlesheetParam() method
takes two arguments: the parameter name and the expression. For example:
 |  |  |  |
const XalanDOMString key("param1");
const XalanDOMString expression("'Hello World'");
theXalanTransformer.setStylesheetParam(key, expression);
// foo.xsl defines a stylesheet parameter named param1.
theXalanTransformer.transform("foo.xml","foo.xsl","foo-out.xml")
|  |  |  |  |
 |
If the expression is a string, enclose it in single quotes to make
it a string expression.
|
You can include the -param flag with two arguments when you call
the command line utility. The first
argument is the parameter name or key, and the second argument is
the string expression (in single quotes). For example:
Xalan -p param1 'boo' foo.xml foo.xsl
or
testXSLT -in foo.xml -xsl foo.xsl -param param1 'boo'
If the string expression includes spaces or other characters that
the shell intercepts, first enclose the string in single quotes
so Xalan-C++ interprets it as a string expression, and then enclose
the resulting string in double quotes so the shell interprets it as
a single argument. For example:
Xalan -p "'hello there'" foo.xml foo.xsl
or
testXSLT -in foo.xml -xsl foo.xsl -param param1 "'hello there'"
The
UseStylesheetParam sample application also uses a
command-line parameter.
|
 |  |  |  | Performing a series of transformations |  |  |  |  |
| |
Before Xalan performs a standard transformation, it must parse the
XML document and compile the XSL stylesheet into binary
representations. If you plan to use the same XML document or
stylesheet in a series of transformations, you can improve performance
by parsing the XML document or compiling the stylesheet once and using
the binary representation when you call transform().
XalanTransformer
includes methods for creating compiled stylesheets and
parsed XML documents: the compileStylesheet() method returns a
pointer to a
XalanCompiledStylesheet; the parseSource() method returns a
pointer to a
XalanParsedSource.
 |
In the case of failure, both methods return 0.
|
Example using a XalanCompiledStylesheet to perform multiple
transformations:
 |  |  |  |
XalanCompiledStylesheet* compiledStylesheet = 0;
compiledStylesheet = theXalanTransformer.compileStylesheet("foo.xsl");
assert(compiledStylesheet!=0);
theXalanTransformer.transform("foo1.xml", *compiledStylesheet, "foo1.out.");
theXalanTransformer.transform("foo2.xml", *compiledStylesheet, "foo2.out");
...
|  |  |  |  |
For a working sample, see the
CompileStylesheet
sample.
Example using a XalanParsedSource for multiple transformations:
 |  |  |  |
XalanParsedSource* parsedXML = 0;
parsedXML = theXalanTransformer.parseSource("foo.xml");
assert(parsedXML!=0);
theXalanTransformer.transform(*parsedXML, "foo1.xsl", "foo-xsl1.out");
theXalanTransformer.transform(*parsedXML, "foo2.xsl", "foo-xsl2.out");
...
|  |  |  |  |
For a sample that uses both a parsed XML source and a compiled
stylesheet, see ThreadSafe
.
|
 |  |  |  | Working with DOM input and output |  |  |  |  |
| |
You can set up an
XSLTResultTarget to produce a DOM when you perform a
transformation. You can also use a DOM as input for a transformation.
The following code fragment illustrates the procedures for working
with DOM output :
 |  |  |  |
// Use the Xerces DOM parser to create a DOMDocument.
#include <xercesc/dom/DOMDocument.hpp>
#include <xercesc/dom/DOMImplementation.hpp>
#include <xalanc/XMLSupport/FormatterToXML.hpp>
#include <xalanc/XMLSupport/XalanTransformer.hpp>
XALAN_USING_XERCES(DOMDocument)
XALAN_USING_XERCES(DOMImplementation)
XALAN_USING_XALAN(FormatterToXML)
XALAN_USING_XALAN(XalanTransformer)
// If you want to produce DOM output, create an empty Xerces Document
// to contain the transformation output.
DOMDocument * theDOM =
DOMImplementation::getImplementation()->createDocument();
// Now create a FormatterListener which can be used by the transformer
// to send each output node to the new Xerces document
FormatterToXercesDOM theFormatter(theDOM);
// Now do the transform as normal
XalanTransformer theXalanTransformer
int theResult = theXalanTransformer.transform(
"foo.xml",
"foo.xsl",
theFormatter);
...
// After you perform the transformation, the DOMDocument contains
// the output.
|  |  |  |  |
 |
You can also follow the same process but use a
FormatterToDeprecatedXercesDOM if you require a DOM_Document
output. However this is discouraged, as support for the deprecated
DOM may be removed in future releases of Xalan-C++
|
If you want to use a Xerces DOM object as input for a transformation without wrapping the DOM in a XercesParserLiaison, see passing in a Xerces DOM.
| |
Performance is much better when Xalan-C++ uses native source tree handling rather than interacting with the Xerces DOMParser.
If you are using the deprecated DOM, the Xerces DOMParser by default,
creates a DOM_XMLDecNode in the DOM tree to represent the XML
declaration. The Xalan bridge for the Xerces DOM does not support
this non-standard node type. Accordingly, you must call
DOMParser::setToCreateXMLDeclTypeNode(false) before you
parse the XML file. If not, the behavior is undefined, and your
application may crash.
|
 |  |  |  | Passing in a Xerces DOM to a transformation |  |  |  |  |
| |
You may want to use a Xerces DOM that was created without using the XalanTransformer class. As the following code snippet illustrates, you can use XercesDOMWrapperParsedSource to pass in a Xerces DOM as the source for an XSL transformation.
 |  |  |  |
#include <xercesc/parsers/DOMParser.hpp>
#include <xalanc/XalanTransformer/XercesDOMWrapperParsedSource.hpp>
void parseWithXerces(XalanTransformer &xalan,
const XSLTInputSource &xmlInput,
const XalanCompiledStylesheet* styleSheer,
const XSLTResultTarget &output,
XMLFileReporter &logFile)
{
XercesDOMParser theParser;
// Turn on validatiion and namespace support.
theParser.setDoValidation(true);
theParser.setDoNamespaces(true);
// Parse the document
theParser.parse(xmlInput);
DOMDocument *theDOM = theParser.getDocument();
theDOM->normalize();
XercesDOMSupport theDOMSupport;
XercesParserLiaison theParserLiaison;
// Use the DOM to create a XercesDOMWrapperParsedSource,
// which you can pass to the transform method.
try
{
const XercesDOMWrapperParsedSource parsedSource(
theDOM,
theParserLiaison,
theDOMSupport,
XalanDOMString(xmlInput.getSystemId()));
xalan.transform(parsedSource, stylesheet, output);
}
catch (....)
{
...
}
}
|  |  |  |  |
|
|
| |
TraceListener is a debugging abstract base class implemented by TraceListenerDefault. You can use TraceListener to trace any combination of the following:
- Calls to templates
- Calls to template children
- Selection events
- Result tree generation events
To construct a TraceListener with TraceListenerDefault, you need a PrintWriter and a boolean for each of these four tracing options. You can then use the XSLTEngimeImpl setTraceSelects and addTraceListener methods to add the TraceListener to an XSLTProcessor. See the TraceListen sample application.
The testXSLT command-line utility and TraceListen both use TraceListenerDefault to write events to the screen.
|
| |
You can use the International Components for Unicode (ICU) to extend support for encoding, number formatting, and sorting.
- Encoding
Xerces-C++ and Xalan-C++ use UTF-16 encoding to work with Unicode data.
If you integrate the ICU with Xerces-C++, both Xerces-C++ and Xalan-C++ use ICU support for
input and output transcoding.
- format-number()
This XSLT function includes two or three arguments (the third is
optional): number, format pattern, and decimal-format name. Xalan-C++ ignores the format
pattern and optional decimal-format name. If you install ICU support for format-number(),
this function is fully supported with all its arguments.
- xsl:sort
If you install ICU support for xml:sort, Xalan-C++ implements Unicode-style collation.
If you choose to build Xalan with ICU, you will need to rebuild Xerces with ICU as well.
To get the ICU:
- Download and unzip the International Components for Unicode(ICU) 2.6.1 source files from the IBM
developerWorks open source zone.
- Do an ICU build -- see the Windows NT or Unix build instructions in the readme.html that
accompanies the download.
Important For Windows, be sure to install the ICU on the same drive and at
the same level as Xalan-C++ and Xerces-C++.
- Set the ICU_DATA environment variable as indicated in the readme.html.
 |  |  |  | Enabling ICU support for number formatting and sorting |  |  |  |  |
| |
If you only want to use the ICU to support number formatting and sorting, you do not need to integrate the ICU with Xalan-C++, but you must do the following in the application where you
want to enable ICU support:
- Include the ICUBridge headers.
- Substitute ICU support for format-number(), xsl:number, and/or xsl:sort.
- Rebuild the Xalan library to include the ICUBridge.
ICUBridge
All Xalan-C++ references to ICU are centralized in the ICUBridge module, which supplies the infrastructure for enabling ICU support for number formatting and sorting.
 |  |  |  |
#include <xalanc/ICUBridge/ICUBridge.hpp>
#include <xalanc/ICUBridge/FunctionICUFormatNumber.hpp>
#include <xalanc/ICUBridge/ICUXalanNumberFormatFactory.hpp>
#include <xalanc/ICUBridge/ICUBridgeCollationCompareFunctor.hpp>
|  |  |  |  |
For Windows, do a clean build of the Xalan library using the "AllInOneWithICU" project.
For UNIX:
- Define the XALAN_USE_ICU environment variable.
- Set the XALANROOT environment variable to the path to to the ICU root (unless you have copied the ICU library to
/usr/lib).
- Rebuild the Xalan library (libxerces-c2_4_0.so for Linux, libxerces-c2_4_0.a for AIX,
libxerces-c2_4_0.sl for HP-UX 11, and libxerces-c2_4_0.so for Solaris).
- Be sure the Xalan library is on the library path (LD_LIBRARY_PATH for Red Hat Linux, LIBPATH for AIX, SHLIB_PATH for HP-UX 11, LD_LIBRARY_PATH for Solaris).
 |
The command you use for setting environment variables depends on the shell you are
using.
For Bourne Shell, K Shell, or Bash use export ENVAR="val"
For C Shell, use setenv ENVAR "val"
where ENVAR is the environment variable name and val is the environment variable
setting. You can check the setting of an environment variable with echo $ENVAR To define XALAN_USE_ICU, set its value to "1".
|
Number formatting
To enable ICU support for the XSLT format-number() function, do
the following:
 |  |  |  |
// Install ICU support for the format-number() function.
FunctionICUFormatNumber::FunctionICUFormatNumberInstaller theInstaller;
|  |  |  |  |
Sorting
To enable ICU support for xsl:sort, do the following:
 |  |  |  |
// Set up a StylesheetExecutionContextDefault object
// (named theExecutionContext in the following fragment),
// and install the ICUCollationCompareFunctor.
ICUBridgeCollationCompareFunctor theICUFunctor;
theExecutionContext.installCollationCompareFunctor(&theICUFunctor);
|  |  |  |  |
|
|
|
|