XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (805 page)

Using the API

AltovaXML offers three APIs, for COM, Java, and .NET applications. The underlying implementation is a COM object, and the Java and .NET interfaces are simply thin wrappers over the COM interface. The server is automatically registered as a COM object during product installation, but you can also register it (or unregister it) manually if you need to. See the reference manual for details. A single server supports concurrent clients, whether they are doing XML validation, XSLT processing, or XQuery processing.

The APIs are thoroughly documented in the reference manual that comes with the product. They are fairly straightforward. Generally, they take raw XML as input and produce raw XML as output; they don't interface with other XML-related components such as the Microsoft or Java DOM. There is no attempt to conform to externally defined API specifications such as JAXP in the Java world.

The COM API

A COM application starts by invoking:

This object contains four subsidiary objects available via its properties: their names are
XMLValidator
,
XSLT1
,
XSLT2
, and
XQuery
. Let's look briefly at the
XMLValidator
and
XSLT2
objects.

XMLValidator

The
XMLValidator
is used to test whether an XML document is well formed, and whether it is valid against a schema and/or DTD.

The source document can be loaded either by specifying a filename (or URI) or by supplying the XML content as a string, as shown in the following two examples:

There are analogous properties to supply a DTD or a schema document either as a filename or as a string:
DTDFileName
,
DTDFromText
,
SchemaFileName
,
SchemaFromText
.

You can then test whether the document is well formed by using the
IsWellFormed
property, you can check it against a DTD or schema referenced from within the instance by using the
IsValid
property, and you can check it against an externally-supplied DTD or schema by using the property
IsValidWithExternalSchemaOrDTD
. I wasn't able to find in the documentation any way to return the document after validation (that is, with defaults expanded and with type annotations). There is a property,
LastErrorMessage
, which provides a rudimentary way of returning error information to the application.

XSLT2

The XSLT2 object similarly has properties to load the source document and stylesheet either by giving a filename (or URI) or by supplying the content as a string. These properties are
InputXMLFileName
,
InputXMLFromText
,
XSLFileName
, and
XSLFromText
.

You can specify the values of stylesheet parameters by calling the method
AddExternalParameter
. The value is supplied in the form of an XPath expression, which is evaluated with the input document as the context node. This means that if you want to supply a string as the value, you need to put it in quotes.

There are two methods provided to run the transformation:
Execute
, which runs the stylesheet and serializes the result to a specified output file, and
ExecuteAndGetResultAsString
, which returns the serialized result as a string.

Putting this together, you can run a transformation like this:

The Java API

The Java API is provided as a thin layer above the underlying COM engine. It makes no attempt to implement JAXP interfaces or to integrate with any other XML components in the Java environment: if you want to mix Altova processing with other components, the only way to interface them is via lexical XML (that is, XML stored as a file or as a string).

First step is:

Following which you can get a validator or an XSLT 2.0 processor as follows:

The source document, schema, and stylesheet are supplied to these objects using methods that map directly onto the COM properties described earlier:
setInputXMLFileName()
,
setInputXMLFromText()
,
setSchemaFileName()
,
setSchemaFromText()
,
setXSLTFileName()
,
setXSLTFromText()
.

The schema validator supports the methods that map directly to the underlying COM object:
isWellFormed()
,
isValid()
,
isValidWithExternalSchemaOrDTD()
, and
getLastErrorMessage()
.

Similarly the XSLT2 processor supports methods
addExternalParameter()
,
execute()
,
executeAndGetResultAsString()
, and
getLastErrorMessage()
.

One thing that requires a little care is the need to explicitly disconnect from the COM server when a task is finished. For this purpose, both the
XMLValidator
and the
XSLT2
object provide a method
releaseInstance()
. Unless you call this, the COM server will be left running. You can quickly find yourself with multiple instances of this process tying up all your memory.

The .NET API

If the Java API is a thin layer over the COM interface, the .NET API is waif-like. In fact, when you get beyond the top-level marketing statements, there isn't really a separate API at all; the way you call Altova from a .NET application is the same way that you invoke any other COM object, by making direct use of the .NET capabilities to call COM interfaces. Which, to be fair, is all that you need.

If you're not familiar with how to import a COM object into a .NET application built using Visual Studio, the Altova documentation gives a helpful summary of the steps you need to take.

Summary

I've tried hard in this short appendix to stick to factual information about Altova's product; it's tempting at the end of the chapter to give a personal assessment, but it would inevitably be biased and I will resist the temptation. Try it out, and make your own judgment. Don't make the mistake, however, of judging it solely from what people have said publicly about earlier releases: as I have stated, the level of conformance to the W3 C specifications has improved with each release and in the 2008 version looks quite solid.

At the time of writing, Altova, Gestalt, and Saxon are the only finished XSLT 2.0 processors on the market, so there's no harm in trying all three and seeing how they compare against your particular requirements. They are very different products.

Appendix H

Glossary

This glossary gathers together some of the more common technical terms used in this book. Most of these terms are defined in the XSLT or XPath specifications, but some of them are borrowed from XML or other standards in the XML family, and one or two have been invented for the purposes of this book. So for each definition, I also tell you where the term comes from.

The definitions in all cases are my own; in some cases, the original specifications have a much more formal definition, but in other cases they are surprisingly vague.

Where a definition contains references to other terms defined in the glossary, these terms are written in italics.

Ancestor Axis (XPath)

The ancestor
axis
selects the
parent
of the
context node
, its
parent
, and so on, up to and including the
root node
. This
axis
is a
reverse axis
.

Ancestor-or-Self Axis (XPath)

The ancestor-or-self
axis
selects the
context node
followed by all the nodes on the
ancestor axis
. This
axis
is a
reverse axis
.

Arity (XPath)

The arity of a
function
is the number of
parameters
defined in the function signature; for example, the arity of the function
true()
is zero, while the two versions of the
contains()
function have arity two and three, respectively.

Atomic Value (XPath)

An atomic value is an
item
such as an integer, a
string
, a date, or a
boolean
. Specifically, it is an instance of the class
xs:anyAtomicType
, which includes all
simple types
(as defined in XML Schema) that are not
list types
or
union types
.

Atomization (XPath)

Atomization is a process that takes an arbitrary
sequence
, containing a mixture of
nodes
and
atomic values
, and creates a new
sequence
in which each of the nodes is replaced by its
typed value
.
Atomic values
appearing in the input sequence are retained in the result sequence unchanged.

Attribute (XML)

A name = value pair appearing in an
element'
s start
tag
; for example,
category=“grocery”
.

Attribute Axis (XPath)

The attribute
axis
selects all the
attributes
of the
context node
. If the
context node
is not an
element
, the
axis
will be empty.

Attribute Declaration (Schema)

An attribute declaration is a
schema component
corresponding to an

element in a
schema document
: it defines constraints on the values of
attributes
having a particular name. It may be a global attribute declaration (if it is defined at the top level of a schema) or a local attribute declaration (if defined within the structure of a
complex type
).

Attribute Node (XPath)

A
node
in a tree that represents an
attribute
in an XML
document
. There will be an attribute node attached to an
element node
for each
attribute
defined in the start
tag
of the corresponding
element
in the original XML
document
, other than an attribute acting as a
namespace declaration
. There will also be attribute nodes for attributes given a default value in the
document type definition
or
schema
. The
string value
of the
node
is the value of the attribute; its
typed value
is the result of
validating
the string value against the relevant
type definition
in a
schema
.

Attribute Set (XSLT)

A named collection of

instructions
, which when invoked using the
use-attribute-sets
attribute of

or

, or the
xsl:use-attribute-sets
attribute of a
literal result element
, generates a set of
attribute nodes
to be added to the result sequence.

Attribute Value Template (XSLT)

An attribute value template is an
attribute
in the
stylesheet
that can contain both fixed and variable parts. The fixed parts are written as ordinary characters, while the variable parts are written between curly braces; for example,
file=“{$dir}/{$fname}.html”
would evaluate to
file=“out/page.html”
if the variables
$dir
and
$fname
have the values
out
and
page
, respectively. Attribute value templates can be used for any attribute of a
literal result element
, but on XSLT elements they can be used only for those attributes that explicitly allow them.