Menu
pushmode.dom

Class DomFragment

PushMode » API Reference » pushmode.dom

  • All Implemented Interfaces:
    Cloneable


    public final class DomFragment
    extends DomContainer
    Fragment of PushMode DOM tree. Fragment can have children just like DomElement, but it has no attributes nor other element properties. It's a thin extension of DomContainer.
    Fragment can be added to any DomContainer, including another DomFragment, and it stays there unchanged until DomContainer.freeze() is called on the parent container. Call to parent's DomContainer.freeze() will inline all DomFragment children in it recursively. DomFragment therefore cannot exist in frozen DOM trees.
    Fragment can hold a group of sibling nodes where wrapping element would be an unnecessary overhead. Methods can return single fragment instead of returning collections of DomContent references. Interfaces can standardize on taking and returning single DomContent, because DomFragment can be used to pass lists wherever single DomContent is expected.
    Thread-safety:
    DomFragment can be only accessed by single thread at a time unless it is frozen. Frozen DomFragment can be safely shared by multiple threads. Parallel access to mutable DomFragment will result in corruption of its internal state. Parallel read-only operations are permitted though.
    • Constructor Detail

      • DomFragment

        public DomFragment()
        Creates empty DOM fragment.
      • DomFragment

        public DomFragment(DomFragment other)
        Creates deep mutable copy of the DOM fragment. Calling this constructor is equivalent to calling clone().
        Parameters:
        other - DOM fragment to copy.
    • Method Detail

      • clone

        public DomFragment clone()
        Creates mutable deep clone of this DomFragment. All child nodes are cloned recursively. The clone is completely independent of this fragment.
        Specified by:
        clone in class DomContainer
        Returns:
        Deep mutable clone.
        Thread-safety:
        This method can be executed concurrently with other read-only operations on the same node. If this node is modified while being cloned, some descendants in the clone might be missing or duplicated, but this method will never throw, this node is never damaged, and the cloned node will be always internally consistent.
      • freeze

        public DomFragment freeze()
        Creates frozen deep clone of this fragment. Mutating methods throw IllegalStateException when executed on frozen fragment. Frozen fragments can be safely shared by all threads. Freezing is recursive. Frozen nodes therefore cannot contain mutable nodes.
        Freezing applies several transformations to the cloned fragment, so that these transformations don't have to be performed repeatedly during rendering. While DomFragment itself can be frozen, frozen DOM nodes cannot contain any DomFragment descendant. For this reason, the returned fragment has all DomFragment descendants inlined into their respective parents. Freezing the fragment causes all consecutive text nodes to be concatenated into single node. If the resulting text node is empty, it is removed. Listeners attached to descendants of type DomElement are discarded if the element has null DomElement.id(). All internal arrays are compacted, so that the frozen DOM tree takes up minimum amount of memory. None of these transformations modifies the original fragment in any way.
        Overrides:
        freeze in class DomContainer
        Returns:
        Deep frozen clone. Returns this if this fragment is already frozen.
        Thread-safety:
        This method can be executed concurrently with other read-only operations on the same node. If this node is modified while being cloned, some descendants in the clone might be missing or duplicated, but this method will never throw, this node is never damaged, and the cloned node will be always internally consistent.
      • equals

        public boolean equals(Object object)
        Compares content of two fragments. If the supplied object is not DomFragment, this method returns false. If one of the fragments is frozen and the other is not, this method returns false. Children of both fragments are compared recursively by calling their DomContent.equals(Object) methods.
        Overrides:
        equals in class DomContainer
        Parameters:
        object - Object to compare this fragment with.
        Returns:
        True if the two fragments are equal.
      • add

        public <C extends DomContentDomFragment add(C... children)
        Adds all nodes in an array to this fragment.
        Overrides:
        add in class DomContainer
        Parameters:
        children - Array of child nodes to add. This method has no effect if the parameter is null. Array items that are null are skipped.
        Returns:
        this
        Throws:
        IllegalStateException - This fragment is frozen.
        See Also:
        add(DomContent)
      • text

        public DomFragment text(String text)
        Adds literal text to this fragment The text is first wrapped in DomText. If the text is null or empty, this method has no effect.
        Overrides:
        text in class DomContainer
        Parameters:
        text - Text to add. This method has no effect if the text is null or empty.
        Returns:
        this
        Throws:
        IllegalStateException - This fragment is frozen.
        See Also:
        add(DomContent)
      • apply

        public DomFragment apply(Consumer<DomFragment> consumer)
        Passes this to the provided Consumer and returns this. The Consumer is usually a mutating method that modifies this fragment in some way. When the Consumer is a lambda, this method permits inlining arbitrary Java code anywhere in the HTML template.
        Parameters:
        consumer - Method that will manipulate this fragment. Usually a lambda. If it is null, NullPointerException is thrown.
        Returns:
        this
        Throws:
        NullPointerException - The Consumer is null.