= Smooks :toc: macro :!toc-title: :toclevels:3

image:https://img.shields.io/maven-central/v/org.smooks/smooks[Maven Central] image:https://img.shields.io/nexus/s/org.smooks/smooks?server=https%3A%2F%2Foss.sonatype.org[Sonatype Nexus (Snapshots)] image:https://github.com/smooks/smooks/workflows/CI/badge.svg[Build Status] image:https://img.shields.io/badge/group-user-red?logo=Gmail[email group,link=https://groups.google.com/g/smooks-user] image:https://img.shields.io/badge/group-dev-red?logo=Gmail[email group,link=https://groups.google.com/g/smooks-dev] image:https://img.shields.io/badge/chat-on%20gitter-46bc99.svg[Gitter chat,link=https://gitter.im/smooks/smooks]

This is the Git source code repository for the http://www.smooks.org[Smooks] project.

toc::[]

== Building

=== Prerequisites

JDK 8 or higher
Apache Maven 3.2.x

=== Maven

. git clone git://github.com/smooks/smooks.git . cd smooks . mvn clean install

NOTE: You will need both Maven (version 3.2.x) and Git installed on your local machine.

// tag::getting-started[] == Getting Started

The easiest way to get started with Smooks is to download and try out the https://github.com/smooks/smooks-examples/tree/v6[examples]. The examples are the recommended base upon which to integrate Smooks into your application. // end::getting-started[]

// tag::introduction[] == Introduction

Smooks is an open-source, extensible Java framework for building event-driven applications that break up XML and non-XML data into chunks for data integration. 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 https://www.w3.org/TR/xslt/[XSLT], https://freemarker.apache.org/[FreeMarker], and https://www.stringtemplate.org/[StringTemplate].
Scalable Processing: process huge payloads while keeping a small memory footprint. Split, transform and route fragments to JMS, filesystem, database, and other destinations.
Enrichment: enrich fragments with data from a database or other data sources.
Complex Fragment Validation: rule-based fragment validation.
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.

=== Why Smooks?

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 link:#visitors[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.

=== Fragment-Based Processing

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

A visitor targets a fragment with the visitor's 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

=== What's new in Smooks 2?

Smooks 2 introduces the https://github.com/smooks/smooks-dfdl-cartridge[DFDL cartridge] and revamps its https://github.com/smooks/smooks-edi-cartridge[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 https://daffodil.apache.org/[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
link:#pipeline[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 https://www.smooks.org/maven[Maven BOM] (bill of materials) to track them all
License change ** After reaching consensus among our code contributors, we've dual-licensed Smooks under https://choosealicense.com/licenses/lgpl-3.0/[LGPL v3.0] and https://choosealicense.com/licenses/apache-2.0/[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 https://github.com/FasterXML/woodstox[FasterXML's Woodstox]: benchmarks consistently showed Woodstox outperforming Xerces
link:#instrumentation[Monitoring and management support] with JMX

=== Migrating from Smooks 1.7 to v2

Comparing the https://github.com/smooks/smooks/tree/v1.7.1/smooks-examples[code examples] for Smooks 1 with https://github.com/smooks/smooks-examples/tree/v6[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 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.JavaSourceWithoutEve

Smooks

Install / Use

README