- java.lang.Object
-
- com.machinezoo.pushmode.dom.DomContent
-
- All Implemented Interfaces:
-
Cloneable
- Direct Known Subclasses:
-
DomContainer
,DomText
@NoTests public abstract class DomContent extends Object implements Cloneable
Base class for all PushMode DOM nodes that can be added to an element, specificallyDomElement
,DomText
, andDomFragment
.DOM nodes can be mutable (
DomElement
andDomFragment
) 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 byfreeze()
. Transition from frozen to mutable state is performed byclone()
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 fromtoString()
. All text stored recursively in the DOM node can be obtained by callingtext()
.DOM content is safe to read concurrently by multiple threads. Write operations cannot be concurrent with reads or other writes.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract DomContent
clone()
Creates deep clone of this node.boolean
equals(Object obj)
Compares this node with another DOM node for equality.abstract DomContent
freeze()
Protects this node from further modification.int
hashCode()
Computes deep hash code of the node.abstract String
text()
Gets concatenated text content of this node.String
toString()
Gets serialized HTML code for this node for debugging purposes.
-
-
-
Method Detail
-
clone
public abstract DomContent clone()
Creates deep clone of this node. If this node is immutable, this method just returnsthis
. For frozen and mutable nodes, this method returns mutable deep clone that is completely independent of this node.
-
equals
public 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.
-
hashCode
public int hashCode()
Computes deep hash code of the node. Hash code is unaffected by whether the node is frozen or not.
-
freeze
public abstract DomContent freeze()
Protects this node from further modification. Mutating methods throwIllegalStateException
when 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.
- Returns:
-
this
-
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.- Returns:
- all text content in this node
-
toString
public 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. UseDomFormatter
to reliably produce HTML.
-
-