Prerequisites

• JDK 8 or higher

• Apache Maven 3.2.x

Maven

1. git clone git://github.com/smooks/smooks.git

2. cd smooks

3. mvn clean install

Why Smooks?

Smooks was conceived to performfragment-based transformations on messages. Supporting fragment-based transformation opened up the possibility of mixing and matching different technologies within the context of a single transformation. This meant that one could leverage distinct technologies for transforming fragments, depending on the type of transformation required by the fragment in question.

In the process of evolving this fragment-based transformation solution, it dawned on us that we were establishing a fragment-based processing paradigm. Concretely, a framework was being built for targeting customvisitor logic at message fragments. A visitor does not need to be restricted to transformation. A visitor could be implemented to apply all sorts of operations on fragments, and therefore, the message as a whole.

Smooks supports a wide range of data structures - XML, EDI, JSON, CSV, POJOs (POJO to POJO!). A pluggable reader interface allows you to plug in a reader implementation for any data format.

Fragment-Based Processing

The primary design goal of Smooks is to provide a framework that isolates and processes fragments in structured data (XML and non-XML) using existing data processing technologies (such as XSLT, plain vanilla Java, Groovy script).

A visitor targets a fragment with the visitor’s resourceselector value. The targeted fragment can take in as much or as little of the source stream as you like. A fragment is identified by the name of the node enclosing the fragment. You can target the whole stream using the node name of the root node as the selector or through the reserved#document selector.

What’s new in Smooks 2?

Smooks 2 introduces theDFDL cartridge and revamps itsEDI cartridge, while dropping support for Java 7 along with other notable changes:

• DFDL cartridge

  • DFDL is a specification for describing file formats in XML. The DFDL cartridge leveragesApache Daffodil to parse files and unparse XML. This opens up Smooks to a wide array of data formats like SWIFT, ISO8583, HL7, and many more.

• Added compatibility with Java 9 and later versions; retained compatibility for Java 8

• Pipeline support

  • Compose any series of transformations on an event outside the main execution context before directing the pipeline output to the execution result stream or to other destinations

• Complete overhaul of the EDI cartridge and strengthening of EDI functionality

  • Rewritten to extend the DFDL cartridge and provide much better support for reading EDI documents

  • Added functionality to serialize EDI documents

  • As in previous Smooks versions, incorporated special support for EDIFACT

• SAX NG filter

  • Replaces SAX filter and supersedes DOM filter

  • Brings with it a new visitor API which unifies the SAX and DOM visitor APIs

  • Cartridges migrated to SAX NG

  • Supports XSLT and StringTemplate resources unlike the legacy SAX filter

• Mementos: a convenient way to stash and un-stash a visitor’s state during its execution lifecycle

• Independent release cycles for all cartridges and oneMaven BOM (bill of materials) to track them all

• License change

  • After reaching consensus among our code contributors, we’ve dual-licensed Smooks underLGPL v3.0 andApache License 2.0. This license change keeps Smooks open source while adopting a permissive stance to modifications.

• New Smooks XSD schema (xmlns="https://www.smooks.org/xsd/smooks-2.0.xsd")

  • Uniform XML namespace declarations: droppeddefault-selector-namespace andselector-namespace XML attributes in favour of declaring namespaces within the standardxmlns attribute from thesmooks-resource-config element.

  • Removeddefault-selector attribute fromsmooks-resource-config element: selectors need to be set explicitly

• Dropped Smooks-specific annotations in favour of JSR annotations

  • Farewell@ConfigParam,@Config,@AppContext, and@StreamSinkWriter. Welcome@Inject.

  • Farewell@Initialize and@Uninitialize. Welcome@PostConstruct and@PreDestroy.

• Separate top-level Java namespaces for API and implementation to provide a cleaner and more intuitive package structure: API interfaces and internal classes were relocated toorg.smooks.api andorg.smooks.engine respectively

• Improved XPath support for resource selectors

  • Functions likenot() are now supported

• Numerous dependency updates

• Maven coordinates change: we are now publishing Smooks artifacts under Maven group IDs prefixed withorg.smooks

• Replaced default SAX parser implementation from Apache Xerces toFasterXML’s Woodstox: benchmarks consistently showed Woodstox outperforming Xerces

• Monitoring and management support with JMX

Migrating from Smooks 1.7 to v2

Comparing thecode examples for Smooks 1 withthose for Smooks 2 can be a useful guide in migrating to Smooks 2. While not exhaustive, we have compiled a list of notes to assist your migration:

1. Smooks 2 no longer supports Java 7. Your application needs to be compiled to at least Java 8 to run Smooks 2.

2. Replacejavax.xml.transform.Source parameter inSmooks#filterSource(…​) method calls with:

   • org.smooks.io.source.JavaSource instead oforg.milyn.payload.JavaSource

   • org.smooks.io.source.StringSource instead oforg.milyn.payload.StringSource

   • org.smooks.io.source.ByteSource instead oforg.milyn.payload.ByteSource

   • org.smooks.io.source.DOMSource instead oforg.milyn.payload.DOMSource

   • org.smooks.io.source.JavaSourceWithoutEventStream instead oforg.milyn.payload.JavaSourceWithoutEventStream

   • org.smooks.io.source.ReaderSource instead ofjavax.xml.transform.stream.StreamSource when the latter is constructed fromjava.io.Reader

   • org.smooks.io.source.StreamSource instead ofjavax.xml.transform.stream.StreamSource when the latter is constructed fromjava.io.InputStream

   • org.smooks.io.source.URLSource instead ofjavax.xml.transform.stream.StreamSource when the latter is constructed from a system ID

3. Replacejavax.xml.transform.Result parameter inSmooks#filterSource(…​) method calls with:

   • org.smooks.io.sink.StringSink instead oforg.milyn.payload.StringResult

   • org.smooks.io.sink.JavaSink instead oforg.milyn.payload.JavaResult

   • org.smooks.io.sink.ByteSink instead oforg.milyn.payload.ByteResult

   • org.smooks.io.sink.DOMSink instead ofjavax.xml.transform.dom.DOMResult

   • org.smooks.io.sink.StreamSink instead ofjavax.xml.transform.stream.StreamResult when the latter is constructed fromjava.io.OutputStream

   • org.smooks.io.sink.WriterSink instead ofjavax.xml.transform.stream.StreamResult when the latter is constructed fromjava.io.Writer

4. ReplacecloseResult attribute in the XML config elementcore:filterSettings withcloseSink.

5. Replace class interfaces:

   • org.milyn.delivery.ExecutionLifecycleInitializable withorg.smooks.api.lifecycle.PreExecutionLifecycle

   • org.milyn.delivery.ExecutionLifecycleCleanable withorg.smooks.api.lifecycle.PostExecutionLifecycle

   • org.milyn.delivery.VisitLifecycleCleanable withorg.smooks.api.lifecycle.PostFragmentLifecycle

   • org.milyn.delivery.ConfigurationExpander withorg.smooks.api.delivery.ResourceConfigExpander

   • org.milyn.event.ResourceBasedEvent withorg.smooks.api.delivery.event.ResourceAwareEvent

6. Remove references toorg.milyn.util.CollectionsUtil and write your own implementation for this class.

7. Implement fromorg.smooks.api.resource.visitor.sax.ng.SaxNgVisitor instead oforg.milyn.delivery.sax.SAXVisitor.

8. ReplaceSmooks#addConfiguration(…​) method calls withSmooks#addResourceConfig(…​).

9. ReplaceSmooks#addConfigurations(…​) method calls withSmooks#addResourceConfigs(…​).

10. Replace references to:

    • org.milyn.javabean.DataDecode withorg.smooks.api.converter.TypeConverterFactory.

    • org.milyn.cdr.annotation.Configurator withorg.smooks.api.lifecycle.LifecycleManager.

    • org.milyn.javabean.DataDecoderException withorg.smooks.api.converter.TypeConverterException.

    • org.milyn.cdr.SmooksResourceConfigurationStore withorg.smooks.api.Registry.

    • org.milyn.cdr.SmooksResourceConfiguration withorg.smooks.api.resource.config.ResourceConfig.

      • Replace calls tosetDefaultResource() withsetSystem()

      • Replace calls toisDefaultResource() withisSystem()

    • org.milyn.delivery.sax.SAXToXMLWriter withorg.smooks.io.DomSerializer.

    • org.milyn.delivery.dom.serialize.Serializer references withorg.smooks.api.resource.visitor.SerializerVisitor

    • org.milyn.event.types.ConfigBuilderEvent references withorg.smooks.api.delivery.event.ContentDeliveryConfigExecutionEvent

11. Replaceorg.milyn.* Java package references withorg.smooks.api,org.smooks.engine,org.smooks.io ororg.smooks.support.

12. Change legacy document root fragment selectors from$document to#document.

13. Remove themilyn-smooks-all dependency from the Maven POM and import theSmooks BOM instead. Declare the corresponding dependency of each Smooks cartridge used within the project but omit the artifact version.

14. Replace Smooks Maven coordinates to match the coordinates as described in theMaven guide.

15. ReplaceExecutionContext#isDefaultSerializationOn() method calls withExecutionContext#getContentDeliveryRuntime().getDeliveryConfig().isDefaultSerializationOn().

16. ReplaceExecutionContext#getContext() method calls withExecutionContext#getApplicationContext().

17. Replaceorg.milyn.cdr.annotation.AppContext annotations withjavax.inject.Inject annotations.

18. Replaceorg.milyn.cdr.annotation.ConfigParam annotations withjavax.inject.Inject annotations:

    • Substitute the@ConfigParam name attribute with the@javax.inject.Named annotation.

    • Wrapjava.util.Optional around the field to mimic the behaviour of the@ConfigParam optional attribute.

19. Replaceorg.milyn.delivery.annotation.Initialize annotations withjakarta.annotation.PostConstruct annotations.

20. Replaceorg.milyn.delivery.annotation.Uninitialize annotations withjakarta.annotation.PreDestroy annotations.

21. Follow theEDIFACT-to-Java example to migrate an implementation that binds an EDIFACT document to a POJO.

22. Follow theJava-to-EDIFACT example to migrate an implementation that deserialises a POJO into an EDIFACT document.

23. SetContainerResourceLocator fromDefaultApplicationContextBuilder#setResourceLocator instead fromApplicationContext#setResourceLocator.

FAQs

See theFAQ.

Maven

See theMaven guide for details on how to integrate Smooks into your project via Maven.

Hello World App

One or more ofSaxNgVisitor interfaces need to be implemented in order to consume the SAX event stream produced from the source, depending on which events are of interest.

The following is a hello world app demonstrating how to implement a visitor that is fired on thevisitBefore andvisitAfter events of a targeted node in the event stream. In this case, Smooks configures the visitor to target elementfoo:

The visitor implementation is straightforward: one method implementation per event. As shown above, a Smooks config (more aboutresource-config later on) is written to target the visitor at a node’svisitBefore andvisitAfter events.

The Java code executing the hello world app is a two-liner:

Observe that in this case the program does not produce a result. The program does not even interact with the filtering process in any way because it does not provide anExecutionContext tosmooks.filterSource(...).

This example illustrated the lower level mechanics of the Smooks’s programming model. In reality, most users are not going to want to solve their problems at this level of detail. Smooks ships with substantial pre-built functionality, that is, pre-built visitors. Visitors are bundled based on functionality: these bundles are calledCartridges.

Smooks Resources

A Smooks execution consumes an source of one form or another (XML, EDI, POJO, JSON, CSV, etc…​), and from it, generates an event stream that fires different visitors (Java, Groovy, DFDL, XSLT, etc…​). The goal of this process can be to produce a new result stream in a different format (data transformation), bind data from the source to POJOs and produce a populated Java object graph (Java binding), produce many fragments (splitting), and so on.

At its core, Smooks views visitors and other abstractions as resources. Aresource is applied when aselector matches a node in the event stream. The generality of such a processing model can be daunting from a usability perspective because resources are not tied to a particular domain. To counteract this, Smooks 1.1 introduced anExtensible Configuration Model feature that allows specific resource types to be specified in the configuration using dedicated XSD namespaces of their own. Instead of having a generic resource config such as:

an Extensible Configuration Model allows us to have a domain-specific resource config:

When comparing the above snippets, the latter resource has:

1. A more strongly typed domain specific configuration and so is easier to read,

2. Auto-completion support from the user’s IDE because the Smooks 1.1+ configurations are XSD-based, and

3. No need set the resource type in its configuration.

Input

Smooks relies on aReader for ingesting a source and generating a SAX event stream. A reader is any class extendingXMLReader. By default, Smooks uses theXMLReader returned fromXMLReaderFactory.createXMLReader(). You can easily implement your ownXMLReader to create a non-XML reader that generates the source event stream for Smooks to process:

Thereader config element is referencing a user-definedXMLReader. It can be configured with a set of handlers, features and parameters:

Packaged Smooks modules, known ascartridges, provide support for non-XML readers but, by default, Smooks expects an XML source. Omit the class name from thereader element to set features on the default XML reader:

Output

Smooks can present output to the outside world in two ways:

1. As instances ofSink: client code extracts output from theSink instance after passing an empty one toSmooks#filterSource(...).

2. As side effects: during filtering, resource output is sent to web services, local storage, queues, data stores, and other locations. Events trigger the routing of fragments to external endpoints such as what happens whensplitting and routing.

Unless configured otherwise, a Smooks execution does not accumulate the input data to produce all the outputs. The reason is simple: performance! Consider a document consisting of hundreds of thousands (or millions) of orders that need to be split up and routed to different systems in different formats, based on different conditions. The only way of handing documents of these magnitudes is by streaming them.

Pipeline

A pipeline is a flexible, yet simple, Smooks construct that isolates the processing of a targeted event from its main processing as well as from the processing of other pipelines. In practice, this means being able to compose any series of transformations on an event outside the main execution context before directing the pipeline output to the execution sink stream or to other destinations. With pipelines, you can enrich data, rename/remove nodes, and much more.

Under the hood, a pipeline is just another instance of Smooks, made self-evident from the Smooks config element declaring a pipeline:

core:smooks fires a nested Smooks execution whenever an event in the stream matches thefilterSourceOn selector. The pipeline within the innersmooks-resource-list element visits the selected event and its child events. It is worth highlighting that the innersmooks-resource-list element behaves identically to the outer one, and therefore, it accepts resources like visitors, readers, and even pipelines (a pipeline within a pipeline!). Moreover, a pipeline is transparent to its nested resources: a resource’s behaviour remains the same whether it’s declared inside a pipeline or outside it.

The optionalcore:action element tells the nested Smooks instance what to do with the pipeline’s output. The next sections list the supported actions.

Rewrite

Thecore:rewrite construct is a reader designed to offer a convenient mechanism for substituting the event stream entering apipeline with one that the pipeline resources can process.

core:rewrite enables one or more of its enclosed visitors to substitute targeted events with new events. In the example that follows, the pipeline feeds the event stream tocore:rewrite, andcore:rewrite in turn, feeds targeted events to the nested FreeMarker visitors:

A visitor withincore:rewrite writes XML fragments to the sink stream, replacing the targeted events. For example, in the config above, the FreeMarker visitors are replacing the#document andrecord events with materialised XML templates. More precisely,core:rewrite converts the materialised XML into a new event stream which is then processed by the downstream pipeline resources, in this case,edifact:unparser.

When implementing your own visitor forcore:rewrite, callorg.smooks.io.Stream#out(org.smooks.api.ExecutionContext).write(java.lang.String) within one of the overridden visit methods to replace the event stream as shown below:

BibliographyVisitor is a custom visitor which visits end events. ThevisitAfter method evaluates the author elements together with the title elements and writes XML to the sink stream replacing the selected events.

Cartridge

The basic functionality of Smooks can be extended through the development of a Smooks cartridge. A cartridge is a Java archive (JAR) containing reusable resources (also known asContent Handlers). A cartridge augments Smooks with support for a specific type input source or event handling.

Visit theGitHub repositories page for the complete list of Smooks cartridges.

Filter

A Smooks filter delivers generated events from a reader to the application’s resources. Smooks 1 had the DOM and SAX filters. The DOM filter was simple to use but kept all the events in memory while the SAX filter, though more complex, delivered the events in streaming fashion. Having two filter types meant two different visitor APIs and execution paths, with all the baggage it entailed.

Smooks 2 unifies the legacy DOM and SAX filters without sacrificing convenience or performance. The new SAX NG filter drops the API distinction between DOM and SAX. Instead, the filter streams SAX events aspartial DOM elements to SAX NG visitors targeting the element. A SAX NG visitor can read the targeted node as well as any of the node’s ancestors but not the targeted node’s children or siblings in order to keep the memory footprint to a minimum.

The SAX NG filter can mimic DOM by setting itsmax.node.depth parameter to 0 (default value is 1), allowing each visitor to process the complete DOM tree in itsvisitAfter(...) method:

Amax.node.depth value of greater than 1 will tell the filter to read and keep an node’s descendants up to the desired depth. Take the following input as an example:

Along with the config:

At any given time, there will always be a singleorder-item in memory containingproduct becausemax.node.depth is 2. Each neworder-item overwrites the previousorder-item to minimise the memory footprint.MyVisitor#visitAfter(...) is invoked 3 times, each invocation corresponding to anorder-item fragment. The first invocation will process:

While the second invocation will process:

Whereas the last invocation will process:

Programmatically, implementingorg.smooks.api.resource.visitor.sax.ng.ParameterizedVisitor will give you fine-grained control over the visitor’s targeted element depth:

ParameterizedVisitor#getMaxNodeDepth() returns an integer denoting the targeted element’s maximum tree depth the visitor can accept in itsvisitAfter(...) method.

Bean Context

TheBean Context is a container for objects which can be accessed within during a Smooks execution. One bean context is created per execution context, that is, perSmooks#filterSource(...) operation. Provide anorg.smooks.io.sink.JavaSink object toSmooks#filterSource(...) if you want the contents of the bean context to be returned at the end of the filtering process:

Resources like visitors access the bean context’s beans at runtime from theBeanContext. TheBeanContext is retrieved fromExecutionContext#getBeanContext(). You should first retrieve aBeanId from theBeanIdStore when adding or retrieving objects from theBeanContext. ABeanId is a special key that ensures higher performance thenString keys, howeverString keys are also supported. TheBeanIdStore must be retrieved fromApplicationContext#getBeanIdStore(). ABeanId object can be created by callingBeanIdStore#register(String). If you know that theBeanId is already registered, then you can retrieve it by callingBeanIdStore#getBeanId(String).BeanId is scoped at the application context. You normally register it in the@PostConstruct annotated method of your visitor implementation and then reference it as member variable from thevisitBefore andvisitAfter methods.

Global Configurations

Global configuration settings are, as the name implies, configuration options that can be set once and be applied to all resources in a configuration.

Smooks supports two types of globals, default properties and global parameters:

• Global Configuration Parameters: Every in a Smooks configuration can specify elements for configuration parameters. These parameter values are available at runtime through theResourceConfig, or are reflectively injected through the@Inject annotation. Global Configuration Parameters are parameters that are defined centrally (see below) and are accessible to all runtime components via theExecutionContext (vsResourceConfig). More on this in the following sections.

• Default Properties: Specify default values for attributes. These defaults are automatically applied toResourceConfig s when their corresponding does not specify the attribute. More on this in the following section.

Configuration Modularization

Smooks configurations are easily modularized through use of the<import> element. This allows you to split Smooks configurations into multiple reusable configuration files and then compose the top level configurations using the<import> element e.g.

You can also inject replacement tokens into the imported configuration by using<param> sub-elements on the<import>. This allows you to make tweaks to the imported configuration.

Note how the replacement token injection points are specified using@tokenname@.

General

• Cache and reuse the Smooks Object. Initialization of Smooks takes some time and therefore it is important that it is reused.

• Pool reader instances where possible. This can result in a huge performance boost, as some readers are very expensive to create.

• If possible, useSAX NG filtering. However, you need to check that all Smooks cartridges in use are SAX NG compatible. SAX NG processing is faster than DOM processing and has a consistently small memory footprint. It is especially recommended for processing large messages. See theFiltering Process Selection (DOM or SAX?) section. SAX NG is the default filter since Smooks 2.

• Turn off debug logging. Smooks performs some intensive debug logging in parts of the code. This can result in significant additional processing overhead and lower throughput. Also remember that NOT having your logging configured (at all) may result in debug log statements being executed!!

• Contextual selectors can obviously have a negative effect on performance e.g. evaluating a match for a selector like "a/b/c/d/e" will obviously require more processing than that of a selector like "d/e". Obviously there will be situations where your data model will require deep selectors, but where it does not, you should try to optimize them for the sake of performance.

Smooks Cartridges

Every cartridge can have its own performance optimization tips.

Javabean Cartridge

• If possible don’t use the Virtual Bean Model. Create Beans instead of maps. Creating and adding data to Maps is a lot slower then creating simple POJO’s and calling the setter methods.

Unit Testing

Unit testing with Smooks is simple:

The test case above usesXMLUnit.

The following maven dependency was used for xmlunit in the above test:

Processing Huge Messages (GBs)

One of the main features introduced in Smooks v1.0 is the ability to process huge messages (Gbs in size). Smooks supports the following types of processing for huge messages:

• One-to-One Transformation: This is the process of transforming a huge message from its source format (e.g. XML), to a huge message in a target format e.g. EDI, CSV, XML etc.

• Splitting & Routing: Splitting of a huge message into smaller (more consumable) messages in any format (EDI, XML, Java, etc…​) andRouting of those smaller messages to a number of different destination types (filesystem, JMS, database).

• Persistence: Persisting the components of the huge message to a database, from where they can be more easily queried and processed. Within Smooks, we consider this to be a form of Splitting and Routing (routing to a database).

All of the above is possible without writing any code (i.e. in a declarative manner). Typically, any of the above types of processing would have required writing quite a bit of ugly/unmaintainable code. It might also have been implemented as a multi-stage process where the huge message is split into smaller messages (stage #1) and then each smaller message is processed in turn to persist, route, etc…​ (stage #2). This would all be done in an effort to make that ugly/unmaintainable code a little more maintainable and reusable. With Smooks, most of these use-cases can be handled without writing any code. As well as that, they can also be handled in a single pass over the source message, splitting and routing in parallel (plus routing to multiple destinations of different types and in different formats).

Configuring Smooks Components

All Smooks components are configured in exactly the same way. As far as the Smooks Core code is concerned, all Smooks components are "resources" and are configured via a ResourceConfig instance, which we talked about in earlier sections.

Smooks provides mechanisms for constructing namespace (XSD) specific XML configurations for components, but the most basic configuration (and the one that maps directly to the ResourceConfig class) is the basic XML configuration from the base configuration namespace (https://www.smooks.org/xsd/smooks-2.0.xsd).

Where:

• Theselector attribute is the mechanism by which the resource is "selected" e.g. can be an XPath for a visitor. We’ll see more of this in the coming sections.

• Theresource element is the actual resource. This can be a Java Class name or some other form of resource (such as a template). For the purposes of this section however, lets just assume the resource to by a Java Class name.

• Theparam elements are configuration parameters for the resource defined in the resource element.

Smooks takes care of all the details of creating the runtime representation of the resource (e.g. constructing the class named in the resource element) and injecting all the configuration parameters. It also works out what the resource type is, and from that, how to interpret things like the selector e.g., if the resource is a visitor instance, it knows the selector is an XPath, selecting a Source message fragment.

Implementing a Source Reader

Implementing and configuring a new Source Reader for Smooks is straightforward. The Smooks specific parts of the process are easy and are not really the issue. The level of effort involved is a function of the complexity of the Source data format for which you are implementing the reader.

Implementing a Reader for your custom data format immediately opens all Smooks capabilities to that data format e.g. Java Binding, Templating, Persistence, Validation, Splitting & Routing, etc…​ So a relatively small investment can yield a quite significant return. The only requirement, from a Smooks perspective, is that the Reader implements the standardorg.xml.sax.XMLReader interface from the Java JDK. However, if you want to be able to configure the Reader implementation, it needs to implement theorg.smooks.api.resource.reader.SmooksXMLReader interface (which is just an extension oforg.xml.sax.XMLReader). So, you can easily use (or extend) an existingorg.xml.sax.XMLReader implementation, or implement a new Reader from scratch.

Let’s now look at a simple example of implementing a Reader for use with Smooks. In this example, we will implement a Reader that can read a stream of Comma Separated Value (CSV) records, converting the CSV stream into a stream of SAX events that can be processed by Smooks, allowing you to do all the things Smooks allows (Java Binding, etc…​).

We start by implementing the basic Reader class:

Two methods from theXMLReader interface are of particular interest:

• setContentHandler(ContentHandler): This method is called by Smooks Core. It sets theContentHandler instance for the reader. TheContentHandler instance methods are called from inside theparse(InputSource) method.

• parse(InputSource): This is the method that receives the Source data input stream, parses it (i.e. in the case of this example, the CSV stream) and generates the SAX event stream through calls to theContentHandler instance supplied in thesetContentHandler(ContentHandler) method.

We need to configure our CSV reader with the names of the fields associated with the CSV records. Configuring a custom reader implementation is the same as for any Smooks component, as described in theConfiguring Smooks Components section above.

So focusing a little more closely on the above methods and our fields configuration:

So now we have our basic Reader implementation stub. We can start writing unit tests to test the new reader implementation.

First thing we need is some sample CSV input. Lets use a simple list of names:

Second thing we need is a test Smooks configuration to configure Smooks with our MyCSVReader. As stated before, everything in Smooks is a resource and can be configured with the basic configuration. While this works fine, it’s a little noisy, so Smooks provides a basic configuration element specifically for the purpose of configuring a reader. The configuration for our test looks like the following:

And of course we need the JUnit test class:

So now we have a basic setup with our custom Reader implementation, as well as a unit test that we can use to drive our development. Of course, our readerparse method is not doing anything yet and our test class is not making any assertions, etc…​ So lets start implementing theparse method:

If you run the unit test class now, you should see the following output on the console (formatted):

After this, it is just a case of expanding the tests, hardening the reader implementation code, etc…​

Now you can use your reader to perform all sorts of operations supported by Smooks. As an example, the following configuration could be used to bind the names into a List of PersonName objects:

And then a test for this configuration could look as follows:

For more on Java Binding, see theJava Binding section.

Tips:

• Reader instances are never used concurrently. Smooks Core will create a new instance for every message, or, will pool and reuse instances as per thereaderPoolSize FilterSettings property.

• If your Reader requires access to the Smooks ExecutionContext for the current filtering context, your Reader needs to implement theSmooksXMLReader interface.

• If your Source data is a binary data stream your Reader must implement theStreamReader interface. See next section.

• You can programmatically configure your reader (e.g. in your unit tests) using aGenericReaderConfigurator instance, which you then set on the Smooks instance.

• While the basic configuration is fine, it’s possible to define a custom configuration namespace (XSD) for your custom CSV Reader implementation. This topic is not covered here. Review the source code to see the extended configuration namespace for the Reader implementations supplied with Smooks (out-of-the-box) e.g. the EDIReader, CSVReader, JSONReader, etc…​ From this, you should be able to work out how to do this for your own custom Reader.

Implementing a Fragment Visitor

Visitors are the workhorse of Smooks. Most of the out-of-the-box functionality in Smooks (Java binding, templating, persistence, etc…​) was created by creating one or more visitors. Visitors often collaborate through theExecutionContext andApplicationContext objects, accomplishing a common goal by working together.

Activation

To activate instrumentation in Smooks, you need to:

1. Add thesmooks-management module to your Java class path. The Maven coordinates for this module are:

   <dependency>    <groupId>org.smooks</groupId>    <artifactId>smooks-management</artifactId>    <version>2.1.0</version></dependency>

2. Declaremanagement:instrumentationResource in the Smooks config to activate instrumentation:

   <smooks-resource-listxmlns="https://www.smooks.org/xsd/smooks-2.0.xsd"xmlns:core="https://www.smooks.org/xsd/smooks/smooks-core-1.6.xsd"xmlns:management="https://www.smooks.org/xsd/smooks/management-1.0.xsd">    <management:instrumentationResource/>    ...    ...</smooks-resource-list>

   management:instrumentationResource supports the following attributes:

   Name	Description	Default
   usePlatformMBeanServer	Whether to use the MBeanServer from this JVM.	true
   mBeanServerDefaultDomain	The default JMX domain of the MBeanServer.	org.smooks
   mBeanObjectDomainName	The JMX domain that all object names will use.	org.smooks
   includeHostName	Whether to include the hostname in the MBean naming.	false

3. Optionally, declare theorg.smooks.management.InstrumentationInterceptor interceptor to instrument visitors:

   <smooks-resource-listxmlns="https://www.smooks.org/xsd/smooks-2.0.xsd"xmlns:core="https://www.smooks.org/xsd/smooks/smooks-core-1.6.xsd"xmlns:management="https://www.smooks.org/xsd/smooks/management-1.0.xsd">    <management:instrumentationResource/>    <core:interceptors>        <core:interceptorclass="org.smooks.management.InstrumentationInterceptor"/>    </core:interceptors>    ...    ...</smooks-resource-list>

Extending

In addition to the Smooks classes that are already instrumented, you can instrument your own classes with the help of annotations located in theorg.smooks.management.annotation package which are listed below: