Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/smooks/smooks-templating-cartridge

Smooks Templating Cartridge
https://github.com/smooks/smooks-templating-cartridge

freemarker smooks-cartridge stringtemplate xslt

Last synced: about 1 month ago
JSON representation

Smooks Templating Cartridge

Awesome Lists containing this project

README 

        
= Smooks Templating Cartridge



image:https://img.shields.io/maven-central/v/org.smooks.cartridges/smooks-templating-cartridge[Maven Central]

image:https://img.shields.io/nexus/s/org.smooks.cartridges/smooks-templating-cartridge?server=https%3A%2F%2Foss.sonatype.org[Sonatype Nexus (Snapshots)]

image:https://github.com/smooks/smooks-templating-cartridge/workflows/CI/badge.svg[Build Status]



// tag::smooks-templating-cartridge[]

Smooks Templating Cartridge supports the following template providers:



. http://freemarker.org/[FreeMarker]

. https://www.w3.org/TR/xslt/[XSLT]

. https://www.stringtemplate.org/[StringTemplate]



This cartridge adds the ability to use these templating technologies within the Smooks filtering process. This means that templates can:



. Be applied to an input source on a per-fragment basis (e.g., for transformations) as opposed to the whole document. This could be useful in situations where you only wish to insert a piece of data into a stream at a specific position (e.g., add headers to a SOAP message) but do not wish to interfere with the rest of the stream. In this case, you can apply the template to the fragment of interest. This method of transformation is commonly known as enrichment.



. Take advantage of other Smooks cartridges such as the https://github.com/smooks/smooks-javabean-cartridge/blob/master/README.adoc[JavaBean cartridge]. You can use the JavaBean cartridge to (1) decode and bind the stream data to the Smooks bean context, and then (2) reference that decoded data from within your FreeMarker template.



. Be used to process huge message streams (e.g., gigabytes), while at the same time maintain a relatively simple processing model, with a low memory footprint. See https://www.smooks.org/documentation/#processing_huge_messages_gbs[Processing Huge Messages] for further information.



. Be used for generating new fragments that can then be routed (using https://www.smooks.org/documentation/#splitting_routing[Smooks Routing components]) to physical endpoints (e.g., File, JMS), or logical endpoints on an ESB (a "Service").



Smooks can be extended to support other templating technologies.



NOTE: Be sure to read the section on https://github.com/smooks/smooks-javabean-cartridge/blob/master/README.adoc#java-binding[Java Binding].



== FreeMarker Templating



http://freemarker.org/[FreeMarker] is a powerful templating engine. Smooks uses FreeMarker to create text from a fragment. This text can then be inserted into the result stream, or https://www.smooks.org/documentation/#splitting_routing[routed to another process].



Add the schema declaration `+https://www.smooks.org/xsd/smooks/freemarker-2.1.xsd+` to the Smooks XML config to configure FreeMarker resources with namespace elements.



*Example - Inline Template*:



.smooks-config.xml

[source,xml]

----



    

        

    



----



*Example - External Template Reference*:



.smooks-config.xml

[source,xml]

----



    

        /templates/shop/ordergen.ftl

    



----



=== FreeMarker transformations using node trees



The easiest way to construct message transformations in FreeMarker is to leverage FreeMarker's http://freemarker.org/docs/xgui_expose_dom.html[DOM tree] facility. This is where FreeMarker uses a W3C DOM for node variables, referencing the DOM nodes directly from inside the FreeMarker template. Smooks extends this by:



. Capturing DOM nodes on a fragment-basis: you do not have to use the full document for the DOM model, just the targeted fragment.



. Allowing the captured DOM nodes node trees to be referenced from Freemarker templates during filtering to create non-XML messages like CSV and JSON.



To take advantage of this facility in Smooks, you need to configure a `org.smooks.engine.resource.visitor.dom.DomModelCreator` resource that declares the node trees to be captured:



.smooks-config.xml

[source,xml]

----



    

    

        

            

                

            

        

        

            

                

                

                    org.smooks.engine.resource.visitor.dom.DomModelCreator

                

                

                

                                     

                

                

                           

                

                

                

                               

                

                

                

                        

                

            

        

    



----



=== FreeMarker and JavaBean Cartridge



FreeMarker node trees are very powerful and easy to use. The trade-off is performance. Constructing W3C DOMs is expensive. It also may be the case that the required data has already been extracted and populated into a Java object model (e.g., where the data also needs to be routed to a JMS endpoint as Java Objects).



In situations where using a node tree is not practical, Smooks allows you to use the JavaBean Cartridge to populate a POJO (or a Virtual Model). This model can then be referencing from the FreeMarker templated. See the docs on the https://github.com/smooks/smooks-javabean-cartridge/blob/master/README.adoc[JavaBean Cartridge] for more details.



*Example (using a Virtual Model)*:



.smooks-config.xml

[source,xml]

----



    

    

        

        

        

        

    

    

        

        

        

        

    



    

        

        

    



----



NOTE: See full example in the https://github.com/smooks/smooks-examples/tree/v4/file-router[file-router] example



=== Programmatic Configuration



FreeMarker templating configurations can be programmatically added to a Smooks instance by configuring and adding a link:https://www.smooks.org/javadoc/v2.0.0/smooks-templating-cartridge/org/smooks/cartridges/templating/freemarker/FreeMarkerTemplateProcessor.html[`+FreeMarkerTemplateProcessor+`] instance to the Smooks instance. The following example creates a Smooks instance with Java binding and FreeMarker templating configurations:



[source,java]

----

Smooks smooks = new Smooks();



smooks.addVisitor(new Bean(OrderItem.class, "orderItem", "order-item").bindTo("productId", "order-item/product/@id"));

smooks.addVisitor(new FreeMarkerTemplateProcessor(new TemplatingConfiguration("/templates/order-tem.ftl")), "order-item");



// And then just use Smooks as normal... filter a Source to a Sink etc...

----



== XSLT Templating



Configuring XSL resources in Smooks is almost identical to that of configuring link:#freemarker-templating[FreeMarker resources]. Add the schema declaration `+https://www.smooks.org/xsd/smooks/xsl-2.0.xsd+` to the Smooks XML config to configure XSL resources with namespace elements.



*Example*:



.smooks-config.xml

[source,xml]

----



    

        

    



----



As with a FreeMarker resource, an XSLT script can be externally referenced from the XSL resource.



As already stated, configuring XSLT templates in Smooks is almost identical to that of configuring FreeMarker templates (see above). For this reason, please consult the FreeMarker configuration docs. Translating to XSL counterparts is simply a matter of changing the configuration namespace. However, please read the following sections.



=== Points to note regarding XSLT support



. It is not recommended to use Smooks for executing XSLT, unless:

    * You need to perform fragment transformations, in other words, you are not transforming the whole message.

    * You need to use other Smooks functionality to perform other operations on the input source, such as message splitting, persistence, etc...



. Smooks applies XSLT scripts on a fragment-basis (i.e., DOM element nodes) instead of the whole document (i.e., DOM document node). This can be very useful for modularizing your XSLT scripts, however, one ought not to assume that an XSLT script written and working standalone (externally to Smooks and on the whole document) will behave as expected when called from Smooks without modification. The reason is that Smooks handles XSLT targeted at the document root node differently: Smooks applies the XSLT to the DOM document node instead of the root DOM element. You may need to tweak to the stylesheet if you already have XSLT scripts and are porting them to Smooks.



. XSLT scripts typically contain a template matched to the root element. Because Smooks applies the XSLT on a fragment-basis, matching against the "root element" is no longer valid. You need to make sure the stylesheet contains a template that matches against the context node (i.e., the targeted fragment).



=== My XSLT works outside Smooks but not from within Smooks?



This can happen and is most likely going to be a result of your stylesheet containing a template that is using an absolute path reference to the document root node. This will cause issues in the Smooks fragment-based processing model because the element being targeted by Smooks is not the document root node. Your XSLT needs to contain a template that matches against the context node being targeted by Smooks.



== Maven Coordinates



.pom.xml

[source,xml]

----



    org.smooks.cartridges

    smooks-templating-cartridge

    2.1.0



----

// end::smooks-templating-cartridge[]



== License



Smooks Templating Cartridge is open source and licensed under the terms of the Apache License Version 2.0, or the GNU Lesser General Public License version 3.0 or later. You may use Smooks Templating Cartridge according to either of these licenses as is most appropriate for your project.



`+SPDX-License-Identifier: Apache-2.0 OR LGPL-3.0-or-later+`