• JDK 8 or higher

• Apache Maven 3.2.x

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

2. cd smooks

3. mvn clean install

Smooks was conceived to perform fragment-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 custom visitor 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.

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 resource selector 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.

Smooks 2 introduces the DFDL cartridge and revamps its EDI 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 leverages Apache 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 one Maven BOM (bill of materials) to track them all

• License change

  • After reaching consensus among our code contributors, we’ve dual-licensed Smooks under LGPL v3.0 and Apache 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: dropped default-selector-namespace and selector-namespace XML attributes in favour of declaring namespaces within the standard xmlns attribute from the smooks-resource-config element.

  • Removed default-selector attribute from smooks-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 to org.smooks.api and org.smooks.engine respectively

• Improved XPath support for resource selectors

  • Functions like not() are now supported

• Numerous dependency updates

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

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

• Monitoring and management support with JMX

Comparing the code examples for Smooks 1 with those 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. Replace javax.xml.transform.Source parameter in Smooks#filterSource(…​) method calls with:

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

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

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

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

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

   • org.smooks.io.source.ReaderSource instead of javax.xml.transform.stream.StreamSource when the latter is constructed from java.io.Reader

   • org.smooks.io.source.StreamSource instead of javax.xml.transform.stream.StreamSource when the latter is constructed from java.io.InputStream

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

3. Replace javax.xml.transform.Result parameter in Smooks#filterSource(…​) method calls with:

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

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

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

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

   • org.smooks.io.sink.StreamSink instead of javax.xml.transform.stream.StreamResult when the latter is constructed from java.io.OutputStream

   • org.smooks.io.sink.WriterSink instead of javax.xml.transform.stream.StreamResult when the latter is constructed from java.io.Writer

4. Replace closeSource attribute in the XML config element core:filterSettings with closeSink.

5. Replace class interfaces:

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

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

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

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

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

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

7. Implement from org.smooks.api.resource.visitor.sax.ng.SaxNgVisitor instead of org.milyn.delivery.sax.SAXVisitor.

8. Replace Smooks#addConfiguration(…​) method calls with Smooks#addResourceConfig(…​).

9. Replace Smooks#addConfigurations(…​) method calls with Smooks#addResourceConfigs(…​).

10. Replace references to:

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

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

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

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

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

      • Replace calls to setDefaultResource() with setSystem()

      • Replace calls to isDefaultResource() with isSystem()

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

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

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

11. Replace org.milyn.* Java package references with org.smooks.api, org.smooks.engine, org.smooks.io or org.smooks.support.

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

13. Remove the milyn-smooks-all dependency from the Maven POM and import the Smooks 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 the Maven guide.

15. Replace ExecutionContext#isDefaultSerializationOn() method calls with ExecutionContext#getContentDeliveryRuntime().getDeliveryConfig().isDefaultSerializationOn().

16. Replace ExecutionContext#getContext() method calls with ExecutionContext#getApplicationContext().

17. Replace org.milyn.cdr.annotation.AppContext annotations with javax.inject.Inject annotations.

18. Replace org.milyn.cdr.annotation.ConfigParam annotations with javax.inject.Inject annotations:

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

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

19. Replace org.milyn.delivery.annotation.Initialize annotations with jakarta.annotation.PostConstruct annotations.

20. Replace org.milyn.delivery.annotation.Uninitialize annotations with jakarta.annotation.PreDestroy annotations.

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

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

23. Set ContainerResourceLocator from DefaultApplicationContextBuilder#setResourceLocator instead from ApplicationContext#setResourceLocator.

See the FAQ.

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

One or more of SaxNgVisitor 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 the visitBefore and visitAfter events of a targeted node in the event stream. In this case, Smooks configures the visitor to target element foo:

The visitor implementation is straightforward: one method implementation per event. As shown above, a Smooks config (more about resource-config later on) is written to target the visitor at a node’s visitBefore and visitAfter 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 an ExecutionContext to smooks.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 called Cartridges.

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. A resource is applied when a selector 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 an Extensible 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.

Smooks relies on a Reader for ingesting a source and generating a SAX event stream. A reader is any class extending XMLReader. By default, Smooks uses the XMLReader returned from XMLReaderFactory.createXMLReader(). You can easily implement your own XMLReader to create a non-XML reader that generates the source event stream for Smooks to process:

The reader config element is referencing a user-defined XMLReader. It can be configured with a set of handlers, features and parameters:

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

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

1. As instances of Sink: client code extracts output from the Sink instance after passing an empty one to Smooks#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 when splitting 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.

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 the filterSourceOn selector. The pipeline within the inner smooks-resource-list element visits the selected event and its child events. It is worth highlighting that the inner smooks-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 optional core:action element tells the nested Smooks instance what to do with the pipeline’s output. The next sections list the supported actions.

The core:rewrite construct is a reader designed to offer a convenient mechanism for substituting the event stream entering a pipeline 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 to core:rewrite, and core:rewrite in turn, feeds targeted events to the nested FreeMarker visitors:

A visitor within core: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 and record 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 for core:rewrite, call org.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. The visitAfter method evaluates the author elements together with the title elements and writes XML to the sink stream replacing the selected events.

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 as Content Handlers). A cartridge augments Smooks with support for a specific type input source or event handling.

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

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 as partial 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 its max.node.depth parameter to 0 (default value is 1), allowing each visitor to process the complete DOM tree in its visitAfter(...) method:

A max.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 single order-item in memory containing product because max.node.depth is 2. Each new order-item overwrites the previous order-item to minimise the memory footprint. MyVisitor#visitAfter(...) is invoked 3 times, each invocation corresponding to an order-item fragment. The first invocation will process:

While the second invocation will process:

Whereas the last invocation will process:

Programmatically, implementing org.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 its visitAfter(...) method.

The Bean 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, per Smooks#filterSource(...) operation. Provide an org.smooks.io.sink.JavaSink object to Smooks#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 the BeanContext. The BeanContext is retrieved from ExecutionContext#getBeanContext(). You should first retrieve a BeanId from the BeanIdStore when adding or retrieving objects from the BeanContext. A BeanId is a special key that ensures higher performance then String keys, however String keys are also supported. The BeanIdStore must be retrieved from ApplicationContext#getBeanIdStore(). A BeanId object can be created by calling BeanIdStore#register(String). If you know that the BeanId is already registered, then you can retrieve it by calling BeanIdStore#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 the visitBefore and visitAfter methods.

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 the ResourceConfig, 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 the ExecutionContext (vs ResourceConfig). More on this in the following sections.

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

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@.

• 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, use SAX 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 the Filtering 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.

Every cartridge can have its own performance optimization tips.

• 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 with Smooks is simple:

The test case above uses XMLUnit.

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

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…​) and Routing 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).

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:

• The selector 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.

• The resource 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.

• The param 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 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 standard org.xml.sax.XMLReader interface from the Java JDK. However, if you want to be able to configure the Reader implementation, it needs to implement the org.smooks.api.resource.reader.SmooksXMLReader interface (which is just an extension of org.xml.sax.XMLReader). So, you can easily use (or extend) an existing org.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 the XMLReader interface are of particular interest:

• setContentHandler(ContentHandler): This method is called by Smooks Core. It sets the ContentHandler instance for the reader. The ContentHandler instance methods are called from inside the parse(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 the ContentHandler instance supplied in the setContentHandler(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 the Configuring 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 reader parse method is not doing anything yet and our test class is not making any assertions, etc…​ So lets start implementing the parse 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 the Java 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 the readerPoolSize FilterSettings property.

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

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

• You can programmatically configure your reader (e.g. in your unit tests) using a GenericReaderConfigurator 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.

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 the ExecutionContext and ApplicationContext objects, accomplishing a common goal by working together.

To activate instrumentation in Smooks, you need to:

1. Add the smooks-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. Declare management:instrumentationResource in the Smooks config to activate instrumentation:

   <smooks-resource-list xmlns="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 the org.smooks.management.InstrumentationInterceptor interceptor to instrument visitors:

   <smooks-resource-list xmlns="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:interceptor class="org.smooks.management.InstrumentationInterceptor"/>
       </core:interceptors>
   
       ...
       ...
   </smooks-resource-list>

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