dom
Wrapper around org.w3c.dom.Document.
Wrapper around org.w3c.dom.Document. The yaidom wrapper is not considered to be a node, unlike the wrapped DOM
document (which is a DOM node).
Use these wrappers only if there is a specific need for them. They are not immutable, and they are not thread-safe.
Wrapper around org.w3c.dom.Element, conforming to the eu.cdevreeze.yaidom.queryapi.ElemLike API.
Wrapper around org.w3c.dom.Element, conforming to the eu.cdevreeze.yaidom.queryapi.ElemLike API.
See the documentation of the mixed-in query API trait(s) for more details on the uniform query API offered by this class.
By design the only state of the DomElem is the wrapped element. Otherwise it would be easy to cause any inconsistency between this wrapper element and the wrapped element. The down-side is that computing the resolved name or resolved attributes is expensive, because on each call first the in-scope namespaces are computed (by following namespace declarations in the ancestry and in the element itself). This is done for reliable namespace support, independent of namespace-awareness of the underlying element's document.
This choice for reliable namespace support (see the documented properties of ScopedElemApi) and defensive handling
of mutable state makes this DomElem slower (when querying for resolved names or attributes) than other wrapper
element implementations, such as ScalaXmlElem. On the other hand, if the use of org.w3c.dom is a given, then
this DomElem makes namespace-aware querying of DOM elements far easier than direct querying of DOM elements.
Wrappers around org.w3c.dom.Node and subclasses, such that the wrapper around org.w3c.dom.Element conforms to the
eu.cdevreeze.yaidom.queryapi.ElemLike API.
Wrappers around org.w3c.dom.Node and subclasses, such that the wrapper around org.w3c.dom.Element conforms to the
eu.cdevreeze.yaidom.queryapi.ElemLike API.
Not all DOM node types are exposed via these wrappers. For example, attributes are not nodes according to the ElemLike API,
so there is no wrapper for attributes.
Use these wrappers only if there is a specific need for them. They are not immutable, and they are not thread-safe.
The wrappers are very light-weight, and typically very short-lived. On the other hand, each query may create many wrapper instances for the query results. By design, the only state of each wrapper instance is the wrapped DOM node, so changes to the state of that wrapped DOM node cannot corrupt the wrapper instance.
Wrapper around class
org.w3c.dom.Element, adapting it to the eu.cdevreeze.yaidom.queryapi.ElemLike API.This wrapper is not thread-safe, and should only be used if the immutable element classes such as eu.cdevreeze.yaidom.simple.Elem are not the best fit.
Such scenarios could be as follows:
Yet be aware that the advantages of immutability and thread-safety (offered by immutable
Elemclasses) are lost when using this wrapper API. Mutable DOM trees are also very easy to break, even via theElemLikeAPI, if element predicates with side-effects are used.To explain the "round-tripping" item above, note that class eu.cdevreeze.yaidom.simple.Elem considers attributes in an element unordered, let alone namespace declarations. That is consistent with the XML Infoset specification, but can sometimes be impractical. Using
org.w3c.dom.Elementinstances, parsed from XML input sources, chances are that this order is retained.There are of course limitations to what formatting data is retained in a DOM tree. A good example is the short versus long form of an empty element. Typically parsers do not pass any information about this distinction, so it is unknown whether the XML input source used the long or short form for an empty element.
It should also be noted that the configuration of XML parsers and serializers can be of substantial influence on the extent that "round-tripping" keeps the XML string the same. Whitespace handling is one such area in which different configurations can lead to quite different "round-tripping" results.
Note that in one way these wrappers are somewhat unnatural: the
ElemLikeAPI uses immutable Scala collections everywhere, whereas the elements of those collections are mutable (!) DOM node wrappers. The wrappers are idiomatic Scala in their use of the Scala Collections API, whereas the wrapped DOM nodes come from a distant past, when imperative programming and "mutability everywhere" ruled.In comparison to XPath against DOM trees, the
ElemLikeAPI may be more verbose, but it requires no setup and "result set handling" boilerplate.