Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Content Handlers are the cornerstone of the Smooks component model. The following Content Handler types are currently in existance:

Include Page
Content Delivery Unit Types
Content Delivery Unit Types

Configuration

All Content Handler types share the same configuration model. This is based on the SmooksResourceConfiguration class (see Smooks Resources). Version 1.0 of Smooks also introduces an Annotation driven approach to Content Handler configuration.

SmooksResourceConfiguration

Content Handlers can receive their configuration by implementing the setConfiguration method:

No Format
public void setConfiguration(SmooksResourceConfiguration resourceConfig) throws SmooksConfigurationException;

Annotations

Version 1.0 of Smooks introduces support for annotation driven Content Handler configuration. This means that as well as supporting the old "setConfiguration(SmooksResourceConfiguration resourceConfig)" style Content Handler configuration, Smooks v1.0 also supports configuration injection via annotations. Two annotations are supported for this purpose:

@Config for injecting the SmooksResourceConfiguration directly onto the Content Handler e.g.

No Format
public class MyVisitor implements SAXElementVisitor {
    @Config
    private SmooksResourceConfiguration config;

    ... etc...
}

@ConfigParam for injecting specific <param> values from the SmooksResourceConfiguration directly onto the Content Handler e.g.

No Format
public class MyVisitor implements SAXElementVisitor {
    
    /**
     * Inject the "encoding" <param> from the SmooksResourceConfiguration.  Do some automatic type conversion on the value (to Charset).  Also default the value to "UTF-8".
     */
    @ConfigParam(defaultVal = "UTF-8")
    private Charset encoding;

    /**
     * Inject the "action" <param> from the SmooksResourceConfiguration.  Do some defaulting and validation on the value.
     */
    @ConfigParam(defaultVal = "replace", choice = {"replace", "addto", "insertbefore", "insertafter"})
    private String action;

    ... etc...
}

Annotation based <param> injection has a number of advantages:

  1. Cleaner code.
  2. Automatic type conversion.
  3. Automatic validation.
  4. Automatic "choice" support.

Lifecycle

Content Handler lifecycle is supported through the method annotations @Initialize and @Uninitialize.

Content Handler methods annotated with @Initialize will be automatically called by Smooks after handler creation and configuration. Content Handler methods annotated with @Uninitialize will be automatically called on VM shutdown (via a shutdown hook), or after calling Smooks.close() (useful where multiple Smooks instances are running in the same VM, with container managed lifecycle).

Stream Readers

Include Page
Stream Readers
Stream Readers

DOM Element Vistors & Serializers

DOMElementVisitors and SerializationUnits are Content Handler specializations that are applied during the DOM Filtering process.

DOMElementVisitors implement a very simple 2 method interface:

No Format
public interface DOMElementVisitor extends ContentHandler {

    public abstract void visitBefore(Element element, ExecutionContext executionContext) throws SmooksException;

    public abstract void visitAfter(Element element, ExecutionContext executionContext) throws SmooksException;
}

See the DOM Filtering section for details on when the SmooksDOMFilter calls the visitiBefore and visitAfter methods.

Tip
titlePoints to note:
  1. The best way to get a hands on feel for how to write your own DOMElementVisitor, or reuse some of the implementations already available in the Smooks Cartridges, is to check out the tutorials.
  2. It's not likely that you'll ever need to worry about SerializationUnits. For the most part, the default serialization fits the bill.

SAX Element Vistors

SAXElementVisitors are Content Handler specializations that are applied during the SAX Filtering process.

SAXElementVisitors implement a very simple 4 method interface:

No Format
public interface SAXElementVisitor extends ContentHandler {

    public abstract void visitBefore(SAXElement element, ExecutionContext executionContext) throws SmooksException, IOException;

    public abstract void onChildText(SAXElement element, SAXText childText, ExecutionContext executionContext) throws SmooksException, IOException;

    public abstract void onChildElement(SAXElement element, SAXElement childElement, ExecutionContext executionContext) throws SmooksException, IOException;

    public abstract void visitAfter(SAXElement element, ExecutionContext executionContext) throws SmooksException, IOException;
}

See the SAX Filtering section for details on when the SmooksSAXFilter calls the visitor methods.

Smooks Cartridges

Include Page
Smooks Cartridges
Smooks Cartridges