Third-party Object Models: Axiom, DOM, JDOM, JDOM2, XOM, and DOM4J
This section is relevant to the Java platform only.
In the case of DOM, all Saxon editions support DOM access "out of the box", and no special configuration action is necessary. See also The Domino Tree Model.
Support for Axiom, JDOM, JDOM2, XOM, and DOM4J is not available "out of the box" with
Saxon-HE, but the source code is open source (in sub-packages of
net.sf.saxon.option
) and can be compiled for use with Saxon-HE if required.
The support code for Axiom, DOM4J, JDOM, JDOM2, and XOM is integrated into the main JAR files for Saxon-PE and Saxon-EE, but (unlike the case of DOM) it is not activated unless the object model is registered with the Configuration, which can be done either by including it in the relevant section of the configuration file, or by nominating it using the method registerExternalObjectModel().
Each supported object model is represented in Saxon by a TreeModel object, which in the case of external object
models will also be an instance of ExternalObjectModel. The
TreeModel
can be used to get a Builder
, which can then be used to
construct an instance of the model from SAX input. The Builder
can also be
inserted into a pipeline to capture the output of a transformation or query.
For DOM input, the source can be supplied by wrapping a DOMSource
around the DOM
Document node. For Axiom, JDOM, JDOM2, XOM, and DOM4J the approach is similar, except that the
wrapper classes are supplied by Saxon itself: they are net.sf.saxon.option.axiom.AxiomDocument, net.sf.saxon.option.jdom.JDOMDocumentWrapper, net.sf.saxon.option.jdom2.JDOM2DocumentWrapper, net.sf.saxon.option.xom.XOMDocumentWrapper, and net.sf.saxon.option.dom4j.DOM4JDocumentWrapper respectively. These wrapper classes
implement the Saxon NodeInfo interface
(which means that they also implement Source
).
Saxon supports these models by wrapping each external node in a wrapper that implements the
Saxon NodeInfo
interface. When nodes are returned by the XQuery or XPath API,
these wrappers are removed and the original node is returned. Similarly, the wrappers are
generally removed when extension functions expecting a node are called.
Saxon does not support wrapping of an external tree that contains entity reference nodes.
Most parsers provide an option to avoid constructing a tree that contains such nodes. For
example, with the JDK Xerces DOM parser, use DOMParser dp = new DOMParser();
dp.setFeature("http://apache.org/xml/features/dom/create-entity-ref-nodes",
expandEntities);
. If there is a need to process a tree that does contain entity
references, it should be copied to a Saxon tree. (Note, this only affects entities explicitly
declared in a DTD. It does not affect character references or built-in entity references such
as <
, which never appear as entity reference nodes in the tree.)
In the case of DOM only, Saxon also supports a wrapping the other way around: an object
implementing the DOM interface may be wrapped around a Saxon NodeInfo
. This is
done when Java methods expecting a DOM Node
are called as extension functions, if
the NodeInfo
is not itself a wrapper for a DOM Node
.
You can also send output to a DOM by using a DOMResult
, or to a JDOM tree by
using a JDOMResult
, or to a XOM document by using a XOMWriter
. In
such cases it is a good idea to set saxon:require-well-formed="yes"
on
xsl:output
to ensure that the transformation or query result is a well-formed
document (for example, that it does not contain several elements at the top level).
External object models do not in all cases fully support the XDM (XPath data model). In
particular, many of them have restrictions concerning the recognition of ID
and
IDREF
attributes. None of the external object models support typed
(schema-validated) data, and none support in-situ update using XQuery updates.