dom

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:

• Conversions from DOM to eu.cdevreeze.yaidom.simple.Elem (and back) have more runtime costs than needed or wanted.
• Round-tripping from XML string to "tree", and back to XML string should keep the resulting XML string as much as possible the same.
• In-place updates (instead of "functional updates") of DOM trees are desired.
• The DOM elements are desired for their PSVI information.

Yet be aware that the advantages of immutability and thread-safety (offered by immutable Elem classes) are lost when using this wrapper API. Mutable DOM trees are also very easy to break, even via the ElemLike API, 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.Element instances, 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 ElemLike API 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 ElemLike API may be more verbose, but it requires no setup and "result set handling" boilerplate.