org.milyn.delivery.dom
Class SmooksDOMFilter

java.lang.Object
  org.milyn.delivery.Filter
      org.milyn.delivery.dom.SmooksDOMFilter

public class SmooksDOMFilter
extends Filter

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(Reader) 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
• SmooksResourceConfiguration
• SmooksResourceConfigurationSortComparator

Author:

tom.fennelly@gmail.com

Nested Class Summary

Nested classes/interfaces inherited from class org.milyn.delivery.Filter

Filter.StreamFilterType

Field Summary

static String

DELIVERY_NODE_REQUEST_KEY Key under which a non-document content delivery node can be set in the request.

Fields inherited from class org.milyn.delivery.Filter

CLOSE_RESULT, CLOSE_SOURCE, DEFAULT_SERIALIZATION_ON, REVERSE_VISIT_ORDER_ON_VISIT_AFTER, STREAM_FILTER_TYPE, TERMINATE_ON_VISITOR_EXCEPTION

Constructor Summary

SmooksDOMFilter(ExecutionContext executionContext)
Public constructor.

Method Summary

void	cleanup() Cleanup the Filter.
void	doFilter(Source source, Result result) Filter the content in the supplied Source instance, outputing the result to the supplied Result instance.
Node	filter(Document doc) Phase the supplied W3C Document.
Node	filter(Reader source) Phase the supplied input reader.
void	serialize(Node node, Writer writer) Serialise the node to the supplied output writer instance.

Methods inherited from class org.milyn.delivery.Filter

close, close, getCurrentExecutionContext, getFilter, getReader, getWriter, removeCurrentExecutionContext, removeCurrentFilter, setCurrentExecutionContext, setFilter, setFilterType

Methods inherited from class java.lang.Object

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

Field Detail

DELIVERY_NODE_REQUEST_KEY

public static final String DELIVERY_NODE_REQUEST_KEY

Key under which a non-document content delivery node can be set in the request. This is needed because Xerces doesn't allow "overwriting" of the document root node.

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(Source source,
                     Result result)
              throws SmooksException

Description copied from class: Filter

Filter the content in the supplied Source instance, outputing the result to the supplied Result instance.

Specified by:

doFilter in class Filter

Parameters:

source - The content Source.

result - The content Result. To serialize the result, supply a StreamResult. To have the result returned as a DOM, supply a DOMResult.

Throws:

SmooksException - Failed to filter.

cleanup

public void cleanup()

Description copied from class: Filter

Cleanup the Filter.

Specified by:

cleanup in class Filter

filter

public Node filter(Reader source)
            throws SmooksException

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.

Throws:

SmooksException

filter

public Node filter(Document doc)

Phase the supplied W3C Document.

Executes the Assembly & Processing phases.

Parameters:

doc - The W3C Document to be filtered.

Returns:

Node representing filtered document.

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.