## Package net.sf.saxon.dom

This package provides glue classes that enable Saxon to process a source document supplied as a DOM tree in the form of a DOMSource object; it also provides classes that present a DOM view of Saxon's native tree structures.

See:
Description

Class Summary
AttrOverNodeInfo: This class is an implementation of the DOM Attr class that wraps a Saxon NodeInfo representation of an attribute or namespace node.
DocumentBuilderFactoryImpl: Implementation of JAXP 1.1 DocumentBuilderFactory.
DocumentBuilderImpl: This class implements the JAXP DocumentBuilder interface, allowing a Saxon TinyTree to be constructed using standard JAXP parsing interfaces.
DocumentOverNodeInfo: This class is an implementation of the DOM Document class that wraps a Saxon DocumentInfo representation of a document node.
DocumentWrapper: The document node of a tree implemented as a wrapper around a DOM Document.
DOMEnvelope: DOMEnvelope is an object model representation in which DOM interfaces are wrapped around Saxon NodeInfo nodes: that is, it implements the DOM on top of a Saxon tree implementation such as the tiny tree or linked tree.
DOMNodeList: This class wraps a list of nodes as a DOM NodeList
DOMObjectModel: This interface must be implemented by any third-party object model that can be wrapped with a wrapper that implements the Saxon Object Model (the NodeInfo interface).
DOMSender: DOMSender.java: pseudo-SAX driver for a DOM source document.
DOMTransform: Variant of command line net.sf.saxon.Transform do build the source document in DOM and then proceed with the transformation.
DOMWriter: DOMWriter is a Receiver that attaches the result tree to a specified Node in a DOM Document
ElementOverNodeInfo: This class is an implementation of the DOM Element class that wraps a Saxon NodeInfo representation of an element node.
NodeOverNodeInfo: This class implements the DOM Node interface as a wrapper around a Saxon NodeInfo object.
NodeWrapper: A node in the XML parse tree representing an XML element, character content, or attribute.
PIOverNodeInfo: This class is an implementation of the DOM ProcessingInstruction interface that wraps a Saxon NodeInfo representation of a text or comment node.
TextOverAttrInfo: This class represents a DOM text node that is the child of a DOM attribute node.
TextOverNodeInfo: This class is an implementation of the DOM Text and Comment interfaces that wraps a Saxon NodeInfo representation of a text or comment node.
TypeInfoImpl: This class implements the DOM TypeInfo interface as a wrapper over the Saxon SchemaType interface.

Exception Summary
DOMExceptionImpl: DOM operations only raise exceptions in "exceptional" circumstances, i.e., when an operation is impossible to perform (either for logical reasons, because data is lost, or because the implementation has become unstable).

## Package net.sf.saxon.dom Description

This package provides glue classes that enable Saxon to process a source document supplied as a DOM tree in the form of a DOMSource object; it also provides classes that present a DOM view of Saxon's native tree structures.

Because of incompatibilities between the DOM interfaces in JDK 1.4 and JDK 1.5, the native Saxon tree structures (the standard tree and tiny tree) no longer implements DOM interfaces directly. In addition, to reduce installation problems for users who dont require DOM interfaces, this package is delivered in a JAR file of its own, `saxon8-dom.jar`, and not with the main `saxon8.jar` JAR file. However, Saxon continues to support the DOM at two levels:

- The input to a transformation or query may be supplied in the form of a `DOMSource` (which contains a DOM document). Saxon performs the query or transformation on the DOM in situ, by wrapping the DOM nodes in a layer that make them appear to be Saxon nodes.

- It is possible for a transformation or query to call extension functions that use DOM interfaces to access a Saxon tree. If the Saxon tree is in fact a wrapper around the DOM, then extension functions will be presented with the underlying DOM nodes. In other cases, Saxon adds a wrapper to the native Saxon nodes to make them implement the DOM interfaces.

  Note, however, that Saxon's tree structures are immutable. Updating interfaces in the DOM API are therefore not supported.

The classes NodeWrapper and DocumentWrapper implement the Saxon interfaces NodeInfo and DocumentInfo on top of an underlying DOM Node or Document object respectively. This enables XPath expressions to be executed directly against the DOM.

The classes NodeOverNodeInfo, DocumentOverNodeInfo, and the like do the converse: they provide a DOM wrapper over a native Saxon node.

Note that using the DOM with Saxon is considerably less efficient than using Saxon's native tree implementations, the Tiny Tree and the (so-called) Standard Tree. The DOM should be used only where there is some good reason, e.g. where other parts of the application have to use DOM interfaces.

Saxon doesn't stop you modifying the contents of the DOM in the course of a transformation (for example, from an extension function, or in a different thread) but the consequences of doing so are unpredictable.

Michael H. Kay
Saxonica Limited
9 February 2005

Copyright (c) Saxonica Limited. All rights reserved.