This is the Git source code repository for the Smooks project.
The easiest way to get started with Smooks is to download and try out the examples. The examples are the recommended base upon which to integrate Smooks into your application.
Smooks is an extensible Java framework for building XML and non-XML data (CSV, EDI, POJOs, etc…) fragment-based applications. It can be used as a lightweight framework on which to hook your own processing logic for a wide range of data formats but, out-of-the-box, Smooks ships with features that can be used individually or seamlessly together:
-
Java Binding: Populate POJOs from a source (CSV, EDI, XML, POJOs, etc…). Populated POJOs can either be the final result of a transformation, or serve as a bridge for further transformations like what is seen in template resources which generate textual results such as XML. Additionally, Smooks supports collections (maps and lists of typed data) that can be referenced from expression languages and templates.
-
Transformation: perform a wide range of data transformations and mappings. XML to XML, CSV to XML, EDI to XML, XML to EDI, XML to CSV, POJO to XML, POJO to EDI, POJO to CSV, etc…
-
Templating: extensible template-driven transformations, with support for XSLT, FreeMarker, and StringTemplate.
-
Huge Message Processing: process huge messages (gigabytes!). Split, transform and route fragments to JMS, filesystem, database, and other destinations.
-
Fragment Enrichment: enrich fragments with data from a database or other data sources.
-
Complex Fragment Validation: rule-based fragment validation.
-
Fragment Persistence: read fragments from, and save fragments to, a database with either JDBC, persistence frameworks (like MyBatis, Hibernate, or any JPA compatible framework), or DAOs.
-
Combine: leverage Smooks’s transformation, routing and persistence functionality for Extract Transform Load (ETL) operations.
-
Validation: perform basic or complex validation on fragment content. This is more than simple type/value-range validation.
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.
|
Note
|
The terms fragment and node denote different meanings. It is usually acceptable to use the terms interchangeably because the difference is subtle and, more often than not, irrelevant. A node may be the outer node of a fragment, excluding the child nodes. A fragment is the outer node and all its child nodes along with their character nodes (text, etc…). When a visitor targets a node, it typically means that the visitor can only process the fragment’s outer node as opposed to the fragment as a whole, that is, the outer node and its child nodes |
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
-
-
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-namespaceandselector-namespaceXML attributes in favour of declaring namespaces within the standardxmlnsattribute from thesmooks-resource-configelement. -
Removed
default-selectorattribute fromsmooks-resource-configelement: selectors need to be set explicitly
-
-
Dropped Smooks-specific annotations in favour of JSR annotations
-
Farewell
@ConfigParam,@Config,@AppContext, and@StreamResultWriter. Welcome@Inject. -
Farewell
@Initializeand@Uninitialize. Welcome@PostConstructand@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.apiandorg.smooks.enginerespectively -
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:
-
Smooks 2 no longer supports Java 7. Your application needs to be compiled to at least Java 8 to run Smooks 2.
-
Replace class interfaces:
-
org.milyn.delivery.ExecutionLifecycleInitializablewithorg.smooks.api.lifecycle.PreExecutionLifecycle -
org.milyn.delivery.ExecutionLifecycleCleanablewithorg.smooks.api.lifecycle.PostExecutionLifecycle -
org.milyn.delivery.VisitLifecycleCleanablewithorg.smooks.api.lifecycle.PostFragmentLifecycle -
org.milyn.delivery.ConfigurationExpanderwithorg.smooks.api.delivery.ResourceConfigExpander -
org.milyn.event.ResourceBasedEventwithorg.smooks.api.delivery.event.ResourceAwareEvent
-
-
Remove references to
org.milyn.util.CollectionsUtiland write your own implementation for this class. -
Implement from
org.smooks.api.resource.visitor.sax.ng.SaxNgVisitorinstead oforg.milyn.delivery.sax.SAXVisitor. -
Replace
Smooks#addConfiguration(…)method calls withSmooks#addResourceConfig(…). -
Replace
Smooks#addConfigurations(…)method calls withSmooks#addResourceConfigs(…). -
Replace references to:
-
org.milyn.javabean.DataDecodewithorg.smooks.api.converter.TypeConverterFactory. -
org.milyn.cdr.annotation.Configuratorwithorg.smooks.api.lifecycle.LifecycleManager. -
org.milyn.javabean.DataDecoderExceptionwithorg.smooks.api.converter.TypeConverterException. -
org.milyn.cdr.SmooksResourceConfigurationStorewithorg.smooks.api.Registry. -
org.milyn.cdr.SmooksResourceConfigurationwithorg.smooks.api.resource.config.ResourceConfig.-
Replace calls to
setDefaultResource()withsetSystem() -
Replace calls to
isDefaultResource()withisSystem()
-
-
org.milyn.delivery.sax.SAXToXMLWriterwithorg.smooks.io.DomSerializer. -
org.milyn.delivery.dom.serialize.Serializerreferences withorg.smooks.api.resource.visitor.SerializerVisitor -
org.milyn.event.types.ConfigBuilderEventreferences withorg.smooks.api.delivery.event.ContentDeliveryConfigExecutionEvent
-
-
Replace
org.milyn.*Java package references withorg.smooks.api,org.smooks.engine,org.smooks.ioororg.smooks.support. -
Change legacy document root fragment selectors from
$documentto#document. -
Remove the
milyn-smooks-alldependency 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. -
Replace Smooks Maven coordinates to match the coordinates as described in the Maven guide.
-
Replace
ExecutionContext#isDefaultSerializationOn()method calls withExecutionContext#getContentDeliveryRuntime().getDeliveryConfig().isDefaultSerializationOn(). -
Replace
ExecutionContext#getContext()method calls withExecutionContext#getApplicationContext(). -
Replace
org.milyn.cdr.annotation.AppContextannotations withjavax.inject.Injectannotations. -
Replace
org.milyn.cdr.annotation.ConfigParamannotations withjavax.inject.Injectannotations:-
Substitute the
@ConfigParamname attribute with the@javax.inject.Namedannotation. -
Wrap
java.util.Optionalaround the field to mimic the behaviour of the@ConfigParamoptional attribute.
-
-
Replace
org.milyn.delivery.annotation.Initializeannotations withjakarta.annotation.PostConstructannotations. -
Replace
org.milyn.delivery.annotation.Uninitializeannotations withjakarta.annotation.PreDestroyannotations. -
Follow the EDIFACT-to-Java example to migrate an implementation that binds an EDIFACT document to a POJO.
-
Follow the Java-to-EDIFACT example to migrate an implementation that deserialises a POJO into an EDIFACT document.
-
Set
ContainerResourceLocatorfromDefaultApplicationContextBuilder#setResourceLocatorinstead fromApplicationContext#setResourceLocator.
See the FAQ.
See the Maven guide for details on how to integrate Smooks into your project via Maven.
A commonly accepted definition of Smooks is of it being a Transformation Engine. Nonetheless, at its core, Smooks makes no reference to data transformation. The core codebase is designed to hook visitor logic into an event stream produced from a source of some kind. As such, in its most distilled form, Smooks is a Structured Data Event Stream Processor.
An application of a structured data event processor is transformation. In implementation terms, a Smooks transformation solution is a visitor reading the event stream from a source to produce a different representation of the input. However, Smooks’s core capabilities enable much more than transformation. A range of other solutions can be implemented based on the fragment-based processing model:
-
Java binding: population of a POJO from the source.
-
splitting & routing: perform complex splitting and routing operations on the source stream, including routing data in different formats (XML, EDI, CSV, POJO, etc…) to multiple destinations concurrently.
-
huge message processing: declaratively consume (transform, or split and route) huge messages without writing boilerplate code.
The following gives a 10,000 foot view of Smooks:
Smooks’s fundamental behaviour is to take an input source, such as CSV, and from it generate an event stream to which visitors are applied to produce a result, such as EDI. In Smooks nomenclature, this behaviour is called filtering. During filtering, you have other Smooks actors which are participating, including:
-
resources
-
application context
-
execution context
-
bean context
-
registry
-
listeners
All of these actors are explained in later sections. Several sources and result types are supported which equate to different transformation types, including but not limited to:
-
XML to XML
-
XML to POJO
-
POJO to XML
-
POJO to POJO
-
EDI to XML
-
EDI to POJO
-
POJO to EDI
-
CSV to XML
-
CSV to …
-
… to …
Smooks maps the source to the result with the help of a highly-tunable SAX event model. The hierarchical events generated from an XML source (startElement, endElement, etc…) drive the SAX event model though the event model can be just as easily applied to other structured data sources (EDI, CSV, POJO, etc…). The most important events are typically the before and after visit events. The following illustration conveys the hierarchical nature of these events:
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:
Smooks smooks = new Smooks("/smooks/echo-example.xml");
smooks.filterSource(new StreamSource(inputStream));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:
<resource-config selector="order-item">
<resource type="ftl"><!-- <item>
<id>${.vars["order-item"].@id}</id>
<productId>${.vars["order-item"].product}</productId>
<quantity>${.vars["order-item"].quantity}</quantity>
<price>${.vars["order-item"].price}</price>
</item>
-->
</resource>
</resource-config>an Extensible Configuration Model allows us to have a domain-specific resource config:
<ftl:freemarker applyOnElement="order-item">
<ftl:template><!-- <item>
<id>${.vars["order-item"].@id}</id>
<productId>${.vars["order-item"].product}</productId>
<quantity>${.vars["order-item"].quantity}</quantity>
<price>${.vars["order-item"].price}</price>
</item>
-->
</ftl:template>
</ftl:freemarker>When comparing the above snippets, the latter resource has:
-
A more strongly typed domain specific configuration and so is easier to read,
-
Auto-completion support from the user’s IDE because the Smooks 1.1+ configurations are XSD-based, and
-
No need set the resource type in its configuration.
Central to how Smooks works is the concept of a visitor. A visitor is a Java class performing a specific task on the targeted fragment such as applying an XSLT script, binding fragment data to a POJO, validate fragments, etc…
Resource selectors are another central concept in Smooks. A selector chooses the node/s a visitor should visit, as well working as a simple opaque lookup value for non-visitor logic.
When the resource is a visitor, Smooks will interpret the selector as an XPath-like expression. There are a number of things to be aware of:
-
The order in which the XPath expression is applied is the reverse of a normal order, like what hapens in an XSLT script. Smooks inspects backwards from the targeted fragment node, as opposed to forwards from the root node.
-
Not all of the XPath specification is supported. A selector supports the following XPath syntax:
-
text()and attribute value selectors:a/b[text() = 'abc'],a/b[text() = 123],a/b[@id = 'abc'],a/b[@id = 123].-
text()is only supported on the last selector step in an expression:a/b[text() = 'abc']is legal whilea/b[text() = 'abc']/cis illegal. -
text()is only supported on visitor implementations that implement theAfterVisitorinterface only. If the visitor implements theBeforeVisitororChildrenVisitorinterfaces, an error will result.
-
-
or&andlogical operations:a/b[text() = 'abc' and @id = 123],a/b[text() = 'abc' or @id = 123] -
Namespaces on both the elements and attributes:
a:order/b:address[@b:city = 'NY'].NoteThis requires the namespace prefix-to-URI mappings to be defined. A configuration error will result if not defined. Read the namespace declaration section for more details. -
Supports
=(equals),!=(not equals),<(less than),>(greater than). -
Index selectors:
a/b[3].
-
The xmlns attribute is used to bind a selector prefix to a namespace:
<?xml version="1.0"?>
<smooks-resource-list xmlns="https://www.smooks.org/xsd/smooks-2.0.xsd"
xmlns:c="http://c" xmlns:d="http://d">
<resource-config selector="c:item[@c:code = '8655']/d:units[text() = 1]">
<resource>com.acme.visitors.MyCustomVisitorImpl</resource>
</resource-config>
</smooks-resource-list>Alternatively, namespace prefix-to-URI mappings can be declared using the legacy core config namespace element:
<?xml version="1.0"?>
<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">
<core:namespaces>
<core:namespace prefix="c" uri="http://c"/>
<core:namespace prefix="d" uri="http://d"/>
</core:namespaces>
<resource-config selector="c:item[@c:code = '8655']/d:units[text() = 1]">
<resource>com.acme.visitors.MyCustomVisitorImpl</resource>
</resource-config>
</smooks-resource-list>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:
<?xml version="1.0"?>
<smooks-resource-list xmlns="https://www.smooks.org/xsd/smooks-2.0.xsd">
<reader class="com.acme.ZZZZReader" />
<!--
Other Smooks resources, e.g. <jb:bean> configs for
binding data from the ZZZZ data stream into POJOs....
-->
</smooks-resource-list>The reader config element is referencing a user-defined XMLReader. It can be configured with a set of handlers, features and parameters:
<reader class="com.acme.ZZZZReader">
<handlers>
<handler class="com.X" />
<handler class="com.Y" />
</handlers>
<features>
<setOn feature="http://a" />
<setOn feature="http://b" />
<setOff feature="http://c" />
<setOff feature="http://d" />
</features>
<params>
<param name="param1">val1</param>
<param name="param2">val2</param>
</params>
</reader>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:
<reader>
<features>
<setOn feature="http://a" />
<setOn feature="http://b" />
<setOff feature="http://c" />
<setOff feature="http://d" />
</features>
</reader>Smooks can present output to the outside world in two ways:
-
As instances of
Result: client code extracts output from theResultinstance after passing an empty one toSmooks#filterSource(...). -
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.
|
Important
|
Smooks can generate output in either, or both, of the above ways, all in a single filtering pass of the source. It does not need to filter the source multiple times in order to generate multiple outputs, critical for performance. |
A look at the Smooks API reveals that Smooks can be supplied with multiple Result instances:
public void filterSource(Source source, Result... results) throws SmooksExceptionSmooks can work with the standard JDK StreamResult and DOMResult result types, as well as the Smooks specific ones:
-
JavaResult: result type for capturing the contents of the Smooks JavaBean context. -
StringResult:StreamResultextension wrapping aStringWriter, useful for testing.
|
Important
|
As yet, Smooks does not support capturing output to multiple Result instances of the same type. For example, you can specify multiple StreamResult instances in Smooks.filterSource(...) but Smooks will only output to the first StreamResult instance.
|
The StreamResult and DOMResult types receive special attention from Smooks. When the default.serialization.on global parameter is turned on, which by default it is, Smooks serializes the stream of events to XML while filtering the source. The XML is fed to the Result instance if a StreamResult or DOMResult is passed to Smooks#filterSource.
|
Note
|
This is the mechanism used to perform a standard 1-input/1-xml-output character-based transformation. |
Smooks is also able to generate different types of output during filtering, that is, while filtering the source event stream but before it reaches the end of the stream. A classic example of this output type is when it is used to split and route fragments to different endpoints for processing by other processes.
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 result 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:
<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">
<core:smooks filterSourceOn="...">
<core:action>
...
</core:action>
<core:config>
<smooks-resource-list>
...
</smooks-resource-list>
</core:config>
</core:smooks>
</smooks-resource-list>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.
Merges the pipeline’s output with the result stream:
...
<core:action>
<core:inline>
...
</core:inline>
</core:action>
...As described in the subsequent sections, an inline action replaces, prepends, or appends content.
Substitutes the selected fragment with the pipeline output:
...
<core:inline>
<core:replace/>
</core:inline>
...Adds the output before the selector start tag:
<core:inline>
<core:prepend-before/>
</core:inline>Adds the output after the selector start tag:
<core:inline>
<core:prepend-after/>
</core:inline>Adds the output before the selector end tag:
<core:inline>
<core:append-before/>
</core:inline>Binds the output to the execution context’s bean store:
...
<core:action>
<core:bindTo id="..."/>
</core:action>
...|
Note
|
core:delegate-reader was introduced in Smooks 2.0.0-M3 and will be renamed to core:rewrite in the next release of Smooks.
|
The core:delegate-reader 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:delegate-reader 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:delegate-reader, and core:delegate-reader in turn, feeds targeted events to the nested FreeMarker visitors:
<?xml version="1.0"?>
<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:ftl="https://www.smooks.org/xsd/smooks/freemarker-2.0.xsd"
xmlns:edifact="https://www.smooks.org/xsd/smooks/edifact-2.0.xsd">
...
...
<core:smooks filterSourceOn="#document">
<core:action>
<core:inline>
<core:replace/>
</core:inline>
</core:action>
<core:config>
<smooks-resource-list>
<core:delegate-reader>
<ftl:freemarker applyOnElement="#document" applyBefore="true">
<ftl:template>header.xml.ftl</ftl:template>
</ftl:freemarker>
<core:smooks filterSourceOn="record" maxNodeDepth="0">
<core:config>
<smooks-resource-list>
<ftl:freemarker applyOnElement="#document">
<ftl:template>body.xml.ftl</ftl:template>
</ftl:freemarker>
</smooks-resource-list>
</core:config>
</core:smooks>
<ftl:freemarker applyOnElement="#document">
<ftl:template>footer.xml.ftl</ftl:template>
</ftl:freemarker>
</core:delegate-reader>
<edifact:unparser schemaUri="/d96a/EDIFACT-Messages.dfdl.xsd" unparseOnNode="*">
<edifact:messageTypes>
<edifact:messageType>ORDERS</edifact:messageType>
</edifact:messageTypes>
</edifact:unparser>
</smooks-resource-list>
</core:config>
</core:smooks>
...
...
</smooks-resource-list>A visitor within core:delegate-reader writes XML fragments to the result 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:delegate-reader converts the materialised XML into a new event stream which is then processed by the downstream pipeline resources, in this case, edifact:unparser.
|
Tip
|
The full example is available in the smooks-examples repository. |
When implementing your own visitor for core:delegate-reader, 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:
package org.smooks.benchmark;
...
...
public class BibliographyVisitor implements AfterVisitor {
private final static String TEMPLATE = "<entry><author>%s</author><title>%s</title></entry>";
private DOMXPath domXPath;
private DOMXPath titleXPath;
@PostConstruct
public void postConstruct() throws JaxenException {
this.domXPath = new DOMXPath("//author");
this.titleXPath = new DOMXPath("//title");
}
@Override
public void visitAfter(Element element, ExecutionContext executionContext) {
try {
List<Element> authors = ((List<Element>) domXPath.evaluate(element));
List<Element> titles = ((List<Element>) titleXPath.evaluate(element));
Stream.out(executionContext).write(String.format(TEMPLATE, authors.isEmpty() ? "N/A" : authors.get(0).getTextContent(), "<![CDATA[" + (titles.isEmpty() ? "N/A" : titles.get(0).getTextContent())) + "]]>");
} catch (IOException | JaxenException e) {
throw new SmooksException(e);
}
}
}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 result 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:
<smooks-resource-list xmlns="https://www.smooks.org/xsd/smooks-2.0.xsd">
<params>
<param name="max.node.depth">0</param>
</params>
...
</smooks>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:
<order id="332">
<header>
<customer number="123">Joe</customer>
</header>
<order-items>
<order-item id="1">
<product>1</product>
<quantity>2</quantity>
<price>8.80</price>
</order-item>
<order-item id="2">
<product>2</product>
<quantity>2</quantity>
<price>8.80</price>
</order-item>
<order-item id="3">
<product>3</product>
<quantity>2</quantity>
<price>8.80</price>
</order-item>
</order-items>
</order>Along with the config:
<smooks-resource-list xmlns="https://www.smooks.org/xsd/smooks-2.0.xsd">
<params>
<param name="max.node.depth">2</param>
</params>
<resource-config selector="order-item">
<resource>org.acme.MyVisitor</resource>
</resource-config>
</smooks>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:
<order-item id='1'>
<product>2</product>
</order-item>While the second invocation will process:
<order-item id='2'>
<product>2</product>
</order-item>Whereas the last invocation will process:
<order-item id='3'>
<product>3</product>
</order-item>Programmatically, implementing org.smooks.api.resource.visitor.sax.ng.ParameterizedVisitor will give you fine-grained control over the visitor’s targeted element depth:
...
public class DomVisitor implements ParameterizedVisitor {
@Override
public void visitBefore(Element element, ExecutionContext executionContext) {
}
@Override
public void visitAfter(Element element, ExecutionContext executionContext) {
System.out.println("Element: " + XmlUtil.serialize(element, true));
}
@Override
public int getMaxNodeDepth() {
return Integer.MAX_VALUE;
}
}ParameterizedVisitor#getMaxNodeDepth() returns an integer denoting the targeted element’s maximum tree depth the visitor can accept in its visitAfter(...) method.
Filter-specific knobs are set through the smooks-core configuration namespace (https://www.smooks.org/xsd/smooks/smooks-core-1.6.xsd) introduced in Smooks 1.3:
<?xml version="1.0"?>
<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">
<core:filterSettings type="SAX NG" (1)
defaultSerialization="true" (2)
terminateOnException="true" (3)
closeSource="true" (4)
closeResult="true" (5)
rewriteEntities="true" (6)
readerPoolSize="3"/> (7)
<!-- Other visitor configs etc... -->
</smooks-resource-list>-
type(default:SAX NG): the type of processing model that will be used.SAX NGis the recommended type. TheDOMtype is deprecated. -
defaultSerialization(default:true): if default serialization should be switched on. Default serialization being turned on simply tells Smooks to locate aStreamResult(orDOMResult) in the Result objects provided to theSmooks.filterSourcemethod and to serialize all events to thatResultinstance. This behavior can be turned off using this global configuration parameter and can be overridden on a per-fragment basis by targeting a visitor at that fragment that takes ownership of theorg.smooks.io.FragmentWriterobject. -
terminateOnException(default:true): whether an exception should terminate execution. -
closeSource(default:true): closeInpinstance streams passed to theSmooks.filterSourcemethod. The exception here isSystem.in, which will never be closed. -
closeResult: close Result streams passed to the[Smooks.filterSourcemethod (default "true"). The exception here isSystem.outandSystem.err, which will never be closed. -
rewriteEntities: rewrite XML entities when reading and writing (default serialization) XML. -
readerPoolSize: reader Pool Size (default 0). Some Reader implementations are very expensive to create (e.g. Xerces). Pooling Reader instances (i.e. reusing) can result in a huge performance improvement, especially when processing lots of "small" messages. The default value for this setting is 0 (i.e. unpooled - a new Reader instance is created for each message). Configure in line with your applications threading model.
Smooks streams events that can be captured, and inspected, while in-flight or after execution. HtmlReportGenerator is one such class that inspects in-flight events to go on and generate an HTML report from the execution:
Smooks smooks = new Smooks("/smooks/smooks-transform-x.xml");
ExecutionContext executionContext = smooks.createExecutionContext();
executionContext.getContentDeliveryRuntime().addExecutionEventListener(new HtmlReportGenerator("/tmp/smooks-report.html"));
smooks.filterSource(executionContext, new StreamSource(inputStream), new StreamResult(outputStream));HtmlReportGenerator is a useful tool in the developer’s arsenal for diagnosing issues, or for comprehending a transformation.
An example HtmlReportGenerator report can be seen online here.
Of course you can also write and use your own ExecutionEventListener implementations.
|
Caution
|
Only use the HTMLReportGenerator in development. When enabled, the HTMLReportGenerator incurs a significant performance overhead and with large message, can even result in OutOfMemory exceptions. |
You can terminate Smooks’s filtering before it reaches the end of a stream. The following config terminates filtering at the end of the customer fragment:
<?xml version="1.0"?>
<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">
<!-- Visitors... -->
<core:terminate onElement="customer"/>
</smooks-resource-list>The default behavior is to terminate at the end of the targeted fragment, on the visitAfter event. To terminate at the start of the targeted fragment, on the visitBefore event, set the terminateBefore attribute to true:
<?xml version="1.0"?>
<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">
<!-- Visitors... -->
<core:terminate onElement="customer" terminateBefore="true"/>
</smooks-resource-list>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.payload.JavaResult object to Smooks#filterSource(...) if you want the contents of the bean context to be returned at the end of the filtering process:
//Get the data to filter
StreamSource source = new StreamSource(getClass().getResourceAsStream("data.xml"));
//Create a Smooks instance (cachable)
Smooks smooks = new Smooks("smooks-config.xml");
//Create the JavaResult, which will contain the filter result after filtering
JavaResult result = new JavaResult();
//Filter the data from the source, putting the result into the JavaResult
smooks.filterSource(source, result);
//Getting the Order bean which was created by the JavaBean cartridge
Order order = (Order)result.getBean("order");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.
|
Note
|
BeanId and BeanIdStore are thread-safe.
|
A number of pre-installed beans are available in the bean context at runtime:
The following are examples of how each of these would be used in a FreeMarker template.
${PUUID.execContext}
${PUUID.random}
${PTIME.startMillis}
${PTIME.startNanos}
${PTIME.startDate}
${PTIME.nowMillis}
${PTIME.nowNanos}
${PTIME.nowDate}
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@Injectannotation. 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 to
ResourceConfigs when their corresponding does not specify the attribute. More on this in the following section.
Global properties differ from the default properties in that they are not specified on the root element and are not automatically applied to resources.
Global parameters are specified in a <params> element:
<params>
<param name="xyz.param1">param1-val</param>
</params>Global Configuration Parameters are accessible via the ExecutionContext e.g.:
public void visitAfter(Element element, ExecutionContext executionContext) {
String param1 = executionContext.getConfigParameter("xyz.param1", "defaultValueABC");
....
}Default properties are properties that can be set on the root element of a Smooks configuration and have them applied to all resource configurations in smooks-conf.xml file. For example, if you have a resource configuration file in which all the resource configurations have the same selector value, you could specify a default-target-profile=order to save specifying the profile on every resource configuration:
<?xml version="1.0"?>
<smooks-resource-list xmlns="https://www.smooks.org/xsd/smooks-2.0.xsd"
default-target-profile="order">
<resource-config>
<resource>com.acme.VisitorA</resource>
...
</resource-config>
<resource-config>
<resource>com.acme.VisitorB</resource>
...
</resource-config>
<smooks-resource-list>The following default configuration options are available:
-
default-target-profile*: Default target profile that will be applied to all resources in the smooks configuration file, where a target-profile is not defined. -
default-condition-ref: Refers to a global condition by the conditions id. This condition is applied to resources that define an empty "condition" element (i.e. ) that does not reference a globally defined condition.
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.
<smooks-resource-list xmlns="https://www.smooks.org/xsd/smooks-2.0.xsd">
<import file="bindings/order-binding.xml" />
<import file="templates/order-template.xml" />
</smooks-resource-list>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.
<!-- Top level configuration... -->
<smooks-resource-list xmlns="https://www.smooks.org/xsd/smooks-2.0.xsd">
<import file="bindings/order-binding.xml">
<param name="orderRootElement">order</param>
</import>
</smooks-resource-list><!-- Imported parameterized bindings/order-binding.xml configuration... -->
<smooks-resource-list xmlns="https://www.smooks.org/xsd/smooks-2.0.xsd"
xmlns:jb="https://www.smooks.org/xsd/smooks/javabean-1.6.xsd">
<jb:bean beanId="order" class="org.acme.Order" createOnElement="@orderRootElement@">
.....
</jb:bean>
</smooks-resource-list>Note how the replacement token injection points are specified using @tokenname@.
When using Smooks standalone you are in full control of the type of output that Smooks produces since you specify it by passing a certain Result to the filter method. But when integrating Smooks with other frameworks (JBossESB, Mule, Camel, and others) this needs to be specified inside the framework’s configuration. Starting with version 1.4 of Smooks you can now declare the data types that Smooks produces and you can use the Smooks api to retrieve the Result(s) that Smooks exports.
To declare the type of result that Smooks produces you use the 'exports' element as shown below:
<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">
<core:exports>
<core:result type="org.smooks.io.payload.JavaResult"/>
</core:exports>
</smooks-resource-list>The newly added exports element declares the results that are produced by this Smooks configuration. A exports element can contain one or more result elements. A framework that uses Smooks could then perform filtering like this:
// Get the Exported types that were configured.
Exports exports = Exports.getExports(smooks.getApplicationContext());
if (exports.hasExports())
{
// Create the instances of the Result types.
// (Only the types, i.e the Class type are declared in the 'type' attribute.
Result[] results = exports.createResults();
smooks.filterSource(executionContext, getSource(exchange), results);
// The Results(s) will now be populate by Smooks filtering process and
// available to the framework in question.
}There might also be cases where you only want a portion of the result extracted and returned. You can use the ‘extract’ attribute to specify this:
<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">
<core:exports>
<core:result type="org.smooks.io.payload.JavaResult" extract="orderBean"/>
</core:exports>
</smooks-resource-list>The extract attribute is intended to be used when you are only interested in a sub-section of a produced result. In the example above we are saying that we only want the object named orderBean to be exported. The other contents of the JavaResult will be ignored. Another example where you might want to use this kind of extracting could be when you only want a ValidationResult of a certain type, for example to only return validation errors.
Below is an example of using the extracts option from an embedded framework:
// Get the Exported types that were configured.
Exports exports = Exports.getExports(smooks.getApplicationContext());
if (exports.hasExports())
{
// Create the instances of the Result types.
// (Only the types, i.e the Class type are declared in the 'type' attribute.
Result[] results = exports.createResults();
smooks.filterSource(executionContext, getSource(exchange), results);
List<object> objects = Exports.extractResults(results, exports);
// Now make the object available to the framework that this code is running:
// Camel, JBossESB, Mule, etc...
}Like with any Software, when configured or used incorrectly, performance can be one of the first things to suffer. Smooks is no different in this regard.
-
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.
Unit testing with Smooks is simple:
public class MyMessageTransformTest {
@Test
public void test_transform() throws Exception {
Smooks smooks = new Smooks(getClass().getResourceAsStream("smooks-config.xml"));
try {
Source source = new StreamSource(getClass().getResourceAsStream("input-message.xml" ) );
StringResult result = new StringResult();
smooks.filterSource(source, result);
// compare the expected xml with the transformation result.
XMLUnit.setIgnoreWhitespace(true);
XMLAssert.assertXMLEqual(new InputStreamReader(getClass().getResourceAsStream("expected.xml")), new StringReader(result.getResult()));
} finally {
smooks.close();
}
}
}The test case above uses XMLUnit.
The following maven dependency was used for xmlunit in the above test:
<dependency>
<groupId>xmlunit</groupId>
<artifactId>xmlunit</artifactId>
<version>1.1</version>
</dependency>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).
|
Note
|
Be sure to read the section on Java Binding. |
If the requirement is to process a huge message by transforming it into a single message of another format, the easiest mechanism with Smooks is to apply multiple FreeMarker templates to the Source message Event Stream, outputting to a Smooks.filterSource Result stream.
This can be done in one of 2 ways with FreeMarker templating, depending on the type of model that’s appropriate:
-
Using FreeMarker + NodeModels for the model.
-
Using FreeMarker + a Java Object model for the model. The model can be constructed from data in the message, using the Javabean Cartridge.
Option #1 above is obviously the option of choice, if the tradeoffs are OK for your use case. Please see the FreeMarker Templating docs for more details.
The following images shows an message, as well as the message to which we need to transform the message:
Imagine a situation where the message contains millions of elements. Processing a huge message in this way with Smooks and FreeMarker (using NodeModels) is quite straightforward. Because the message is huge, we need to identify multiple NodeModels in the message, such that the runtime memory footprint is as low as possible. We cannot process the message using a single model, as the full message is just too big to hold in memory. In the case of the message, there are 2 models, one for the main data (blue highlight) and one for the data (beige highlight):
So in this case, the most data that will be in memory at any one time is the main order data, plus one of the order-items. Because the NodeModels are nested, Smooks makes sure that the order data NodeModel never contains any of the data from the order-item NodeModels. Also, as Smooks filters the message, the order-item NodeModel will be overwritten for every order-item (i.e. they are not collected). See SAX NG.
Configuring Smooks to capture multiple NodeModels for use by the FreeMarker templates is just a matter of configuring the DomModelCreator visitor, targeting it at the root node of each of the models. Note again that Smooks also makes this available to SAX filtering (the key to processing huge message). The Smooks configuration for creating the NodeModels for this message are:
<?xml version="1.0"?>
<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:ftl="https://www.smooks.org/xsd/smooks/freemarker-2.0.xsd">
<!--
Create 2 NodeModels. One high level model for the "order"
(header, etc...) and then one for the "order-item" elements...
-->
<resource-config selector="order,order-item">
<resource>org.smooks.engine.resource.visitor.dom.DomModelCreator</resource>
</resource-config>
<!-- FreeMarker templating configs to be added below... -->Now the FreeMarker templates need to be added. We need to apply 3 templates in total:
-
A template to output the order "header" details, up to but not including the order items.
-
A template for each of the order items, to generate the elements in the .
-
A template to close out the message.
With Smooks, we implement this by defining 2 FreeMarker templates. One to cover #1 and #3 (combined) above, and a seconds to cover the elements.
The first FreeMarker template is targeted at the element and looks as follows:
<ftl:freemarker applyOnElement="order-items">
<ftl:template><!--<salesorder>
<details>
<orderid>${order.@id}</orderid>
<customer>
<id>${order.header.customer.@number}</id>
<name>${order.header.customer}</name>
</customer>
</details>
<itemList>
<?TEMPLATE-SPLIT-PI?>
</itemList>
</salesorder>-->
</ftl:template>
</ftl:freemarker>You will notice the `<?TEMPLATE-SPLIT-PI?>` processing instruction. This tells Smooks where to split the template, outputting the first part of the template at the start of the element, and the other part at the end of the element. The element template (the second template) will be output in between.
The second FreeMarker template is very straightforward. It simply outputs the elements at the end of every element in the source message:
<ftl:freemarker applyOnElement="order-item">
<ftl:template><!-- <item>
<id>${.vars["order-item"].@id}</id>
<productId>${.vars["order-item"].product}</productId>
<quantity>${.vars["order-item"].quantity}</quantity>
<price>${.vars["order-item"].price}</price>
</item>-->
</ftl:template>
</ftl:freemarker>
</smooks-resource-list>Because the second template fires on the end of the elements, it effectively generates output into the location of the <?TEMPLATE-SPLIT-PI?> Processing Instruction in the first template. Note that the second template could have also referenced data in the "order" NodeModel.
And that’s it! This is available as a runnable example in the Tutorials section.
This approach to performing a One-to-One Transformation of a huge message works simply because the only objects in memory at any one time are the order header details and the current details (in the Virtual Object Model).? Obviously it can’t work if the transformation is so obscure as to always require full access to all the data in the source message e.g. if the messages needs to have all the order items reversed in order (or sorted).? In such a case however, you do have the option of routing the order details and items to a database and then using the database’s storage, query and paging features to perform the transformation.
Smooks supports a number of options when it comes to splitting and routing fragments. The ability to split the stream into fragments and route these fragments to different endpoints (File, JMS, etc…) is a fundamental capability. Smooks improves this capability with the following features:
-
Basic Fragment Splitting: basic splitting means that no fragment transformation happens prior to routing. Basic splitting and routing involves defining the XPath of the fragment to be split out and defining a routing component (e.g., Apache Camel) to route that unmodified split fragment.
-
Complex Fragment Splitting: basic fragment splitting works for many use cases and is what most splitting and routing solutions offer. Smooks extends the basic splitting capabilities by allowing you to perform transformations on the split fragment data before routing is applied. For example, merging in the customer-details order information with each order-item information before performing the routing order-item split fragment routing.
-
In-Flight Stream Splitting & Routing (Huge Message Support): Smooks is able to process gigabyte streams because it can perform in-flight event routing; events are not accumulated when the
max.node.depthparameter is left unset. -
Multiple Splitting and Routing: conditionally split and route multiple fragments (different formats XML, EDI, POJOs, etc…) to different endpoints in a single filtering pass of the source. One could route an OrderItem Java instance to the HighValueOrdersValidation JMS queue for order items with a value greater than $1,000 and route all order items as XML/JSON to an HTTP endpoint for logging.
All existing Smooks functionality (Java Binding, EDI processing, etc…) is built through extension of a number of well-defined APIs. We will look at these APIs in the coming sections.
The main extension points/APIs in Smooks are:
-
Reader APIs: Those for processing Source/Input data (Readers) so as to make it consumable by other Smooks components as a series of well defined hierarchical events (based on the SAX event model) for all of the message fragments and sub-fragments.
-
Visitor APIs: Those for consuming the message fragment SAX events produced by a source/input reader.
Another very important aspect of writing Smooks extensions is how these components are configured. Because this is common to all Smooks components, we will look at this first.
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).