Package org.smooks.engine.delivery.dom

Class SmooksDOMFilter

  • All Implemented Interfaces:
    Closeable, AutoCloseable, Filter
    public class SmooksDOMFilter
extends AbstractFilter
    Smooks DOM based content filtering class.

    This class is responsible for Filtering XML DOM streams (XML/XHTML/HTML etc) through a process of iterating over the source XML DOM tree and applying the configured Content Delivery Units (DOMElementVisitors and SerializationUnits).

    This class doesn't get used directly. See the Smooks class.

    XML/XHTML/HTML Filtering Process

    SmooksDOMFilter markup processing (XML/XHTML/HTML) is a 2 phase filter, depending on what needs to be done. The first phase is called the "Visit Phase", and the second phase is called the "Serialisation Phase". SmooksDOMFilter can be used to execute either or both of these phases (depending on what needs to be done!).

    Through this filter, Smooks can be used to analyse and/or transform markup, and then serialise it.

    So, in a little more detail, the 2 phases are:

    1. Visit: This phase is executed via either of the filter(Document) or filter(Source) methods. This phase is really 2 "sub" phases.
      • Assembly: This is effectively a pre-processing phase.

        This sub-phase involves iterating over the source XML DOM, visiting all DOM elements that have ASSEMBLY phase DOMElementVisitors targeted at them for the profile associated with the ExecutionContext. This phase can result in DOM elements being added to, or trimmed from, the DOM. This phase is also very usefull for gathering data from the message in the DOM (and storing it in the ExecutionContext), which can be used during the processing phase (see below). This phase is only executed if there are DOMElementVisitors targeted at this phase.

      • Processing: Processing takes the assembled DOM and iterates over it again, so as to perform transformation/analysis.

        This sub-phase involves iterating over the source XML DOM again, visiting all DOM elements that have PROCESSING phase DOMElementVisitors targeted at them for the profile associated with the ExecutionContext. This phase will only operate on DOM elements that were present in the assembled document; DOMElementVisitors will not be applied to elements that are introduced to the DOM during this phase.

    2. Serialisation: This phase is executed by the serialize(Node, Writer) method (which uses the Serializer class). The serialisation phase takes the processed DOM and iterates over it to apply all SerializationUnits, which write the document to the target output stream.

      Instead of using this serialisation mechanism, you may wish to perform DOM Serialisation via some other mechanism e.g. XSL-FO via something like Apache FOP.

    See the online flash demo demonstrating this process.

    Other Documents

    Author:
    tom.fennelly@gmail.com

    • Constructor Detail

      • SmooksDOMFilter

        public SmooksDOMFilter​(ExecutionContext executionContext)
        Public constructor.

        Constructs a SmooksDOMFilter instance for delivering content for the supplied execution context.

        Parameters:
        executionContext - Execution context. This instance is bound to the current Thread of execution. See Threading Issues.

    • Method Detail

      • doFilter

        public void doFilter()
              throws SmooksException
        Description copied from interface: Filter
        Filter the content in the supplied Source instance, outputing the result to the supplied Result instance.

        Implementations use static methods on the FilterSource and FilterResult classes to access the Source and Results objects.

        Throws:
        SmooksException - Failed to filter.

      • doFilter

        protected void doFilter​(Source source,
                        Result result)

      • close

        public void close()

      • filter

        public Node filter​(Source source)
        Phase the supplied input reader.

        Simply parses the input reader into a W3C DOM and calls filter(Document).

        Parameters:
        source - The source of markup to be filtered.
        Returns:
        Node representing filtered document.

      • filter

        public Node filter​(Document doc)
        Filter the supplied W3C Document.

        Executes the Assembly & Processing phases.

        Parameters:
        doc - The W3C Document to be filtered.
        Returns:
        Node representing filtered document.

      • filter

        public Node filter​(Element element)
        Filter the supplied W3C Element.

        Executes the Assembly & Processing phases.

        Parameters:
        element - The W3C Element to be filtered.
        Returns:
        Node representing filtered Element.

      • serialize

        public void serialize​(Node node,
                      Writer writer)
               throws IOException,
                      SmooksException
        Serialise the node to the supplied output writer instance.

        Executes the Serialisation phase, using the Serializer class to perform the serialization.

        Parameters:
        node - Document to be serialised.
        writer - Output writer.
        Throws:
        IOException - Unable to write to output writer.
        SmooksException - Unable to serialise due to bad Smooks environment. Check cause.