Package org.smooks.engine.delivery.dom

Class SmooksDOMFilter

java.lang.Object

org.smooks.engine.delivery.AbstractFilter

org.smooks.engine.delivery.dom.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

• Smooks
• ResourceConfig
• ResourceConfigSortComparator

Author:

tom.fennelly@gmail.com

Field Summary

Fields inherited from interface org.smooks.api.delivery.Filter

CLOSE_EMPTY_ELEMENTS, CLOSE_RESULT, CLOSE_SOURCE, DEFAULT_SERIALIZATION_ON, ENTITIES_REWRITE, MAINTAIN_ELEMENT_STACK, MAX_NODE_DEPTH, READER_POOL_SIZE, REVERSE_VISIT_ORDER_ON_VISIT_AFTER, STREAM_FILTER_TYPE, TERMINATE_ON_VISITOR_EXCEPTION

Constructor Summary

Constructors

Constructor	Description
SmooksDOMFilter(ExecutionContext executionContext)	Public constructor.

Method Summary

Modifier and Type	Method	Description
void	close()
void	doFilter()	Filter the content in the supplied Source instance, outputing the result to the supplied Result instance.
protected void	doFilter(Source source, Result result)
Node	filter(Source source)	Phase the supplied input reader.
Node	filter(Document doc)	Filter the supplied W3C Document.
Node	filter(Element element)	Filter the supplied W3C Element.
void	serialize(Node node, Writer writer)	Serialise the node to the supplied output writer instance.

Methods inherited from class org.smooks.engine.delivery.AbstractFilter

close, close, getFilter, getReader, getWriter, removeCurrentFilter, setFilter, setFilterType

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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:

ResourceConfigurationNotFoundException - DOM Serialiser exception.

IOException - Unable to write to output writer.

SmooksException - Unable to serialise due to bad Smooks environment. Check cause.