- All Implemented Interfaces:
DOM nodes can be mutable (
DomFragment) or immutable (
DomText). Mutable nodes can be frozen, which causes all mutating methods to throw and improves thread-safety. DOM nodes can be thus in three states: immutable, mutable, and frozen. Immutable state cannot be changed. Transition from mutable to frozen state is performed by
freeze(). Transition from frozen to mutable state is performed by
clone() or appropriate copy constructor.
DOM content has value semantics. It can be copied, compared for equality, and hashed. Elements and fragments can be assigned.
HTML representation of the node can be obtained by using
DomFormatter. For debugging purposes, it is also available from
toString(). All text stored recursively in the DOM node can be obtained by calling
DOM content is safe to read concurrently by multiple threads. Write operations cannot be concurrent with reads or other writes.
Method SummaryModifier and TypeMethodDescription
clone()Creates deep clone of this node.
booleanCompares this node with another DOM node for equality.
freeze()Protects this node from further modification.
hashCode()Computes deep hash code of the node.
text()Gets concatenated text content of this node.
toString()Gets serialized HTML code for this node for debugging purposes.
clonepublic abstract DomContent clone()Creates deep clone of this node. If this node is immutable, this method just returns
this. For frozen and mutable nodes, this method returns mutable deep clone that is completely independent of this node.
equalspublic boolean equals
(Object obj)Compares this node with another DOM node for equality. Equality considers the type of the node, all its properties, and recursively its children. Equality is unaffected by whether the node is frozen or not.
hashCodepublic int hashCode()Computes deep hash code of the node. Hash code is unaffected by whether the node is frozen or not.
freezepublic abstract DomContent freeze()Protects this node from further modification. Mutating methods throw
IllegalStateExceptionwhen executed on frozen node. Freezing is recursive. Frozen nodes therefore cannot contain mutable nodes. If this node is immutable by nature (i.e.
DomText) or already frozen, this method has no effect.
Freezing is particularly useful in caches that provide the same DOM tree to multiple threads. While unfrozen DOM trees can be safely shared, this relies on threads voluntarily abstaining from modifications. Caches can protect consistency of data they return by freezing the returned DOM tree, which will effectively enable a runtime check causing any mutating methods to throw. If some thread runs buggy code that tries to modify the DOM tree obtained from shared cache, the buggy code will throw an exception while the cached DOM tree is left intact.
Besides marking the node as frozen, freezing modifies internal data structures to save memory. All internal arrays are compacted to their minimum required size.
Freezing is carefully implemented in such a way that multiple threads can safely attempt to freeze the same node at the same time. Freezing is also safe to run concurrently with reads. This is an exception to the general prohibition of concurrent modifications. This exception was added to ensure that downstream cache can freeze its output even though it incorporates unfrozen subtree obtained from upstream cache. The nested DOM tree from upstream cache is frozen as a byproduct of freezing parent DOM tree in the downstream cache. Since freezing doesn't change anything observable about the DOM tree except for blocking writes, freezing is also safe for the upstream cache.
text@DraftApi("perhaps add space around block elements and some other elements (br), perhaps normalize whitespace") public abstract String text()Gets concatenated text content of this node. Text is concatenated recursively in the same order in which it would appear in HTML. Attribute values are not included. No whitespace normalization is performed.
- all text content in this node
toStringpublic String toString()Gets serialized HTML code for this node for debugging purposes. HTML returned by this method is not guaranteed to be stable across releases or even usable in browsers. Use
DomFormatterto reliably produce HTML.