package 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.
- Alphabetic
- By Inheritance
- dom
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
Type Members
- sealed trait CanBeDomDocumentChild extends DomNode with CanBeDocumentChild
- final class DomComment extends CanBeDomDocumentChild with Comment
-
final
class
DomDocument
extends DocumentApi
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.
-
final
class
DomElem
extends CanBeDomDocumentChild with Elem with ScopedElemLike with HasParent
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 asScalaXmlElem
. On the other hand, if the use oforg.w3c.dom
is a given, then this DomElem makes namespace-aware querying of DOM elements far easier than direct querying of DOM elements. - final class DomEntityRef extends DomNode with EntityRef
-
sealed
trait
DomNode
extends Node
Wrappers around
org.w3c.dom.Node
and subclasses, such that the wrapper aroundorg.w3c.dom.Element
conforms to the eu.cdevreeze.yaidom.queryapi.ElemLike API.Wrappers around
org.w3c.dom.Node
and subclasses, such that the wrapper aroundorg.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.
- final class DomProcessingInstruction extends CanBeDomDocumentChild with ProcessingInstruction
- final class DomText extends DomNode with Text
Value Members
- object CanBeDomDocumentChild
- object DomComment
- object DomDocument
- object DomElem
- object DomEntityRef
- object DomNode
- object DomProcessingInstruction
- object DomText