JBoss.orgCommunity Documentation
Version: 1.0.0.GA
Copyright © 2009 JBoss, a division of Red Hat
November 2008
This chapter give you a short introduction to Smooks, Smooks tools and its installation
Smooks is a Java Framework/Engine for processing XML and non XML data (CSV, EDI, Java, JSON etc).
Transformation: Perform a wide range of Data Transforms. Supports many different Source and Result types -XML/CSV/EDI/Java/JSON to XML/CSV/EDI/Java/JSON.
Java Binding: Bind into a Java Object Model from any data source (CSV, EDI, XML, Java, JSON etc).
Huge Message Processing: Process huge messages (GBs) - Split, Transform and Route message fragments to JMS, File, Database etc destinations. Route multiple message formats to multiple destinations in a single pass over a message.
Message Enrichment: Enrich a message with data from a Database, or other Datasources.
Combine: Combine the above features in different ways e.g. add Message Enrichment as part of a Splitting and Routing process.
For More informations about Smooks, please visit Smooks official site.
Smooks tools is a set of graphical tools for editing Smooks configuration file based on Eclipse.
The Smooks tools was included by the JBoss Tools since 3.0.0 Beta1 version. You can download the JBoss Tools from JBoss download site.
Smooks tools (JBoss Tools) run with the latest Eclipse and other required plug-ins (GEF, EMF, etc.).
You should download the latest IDE for Java EE developers from Eclipse site. It contains many plug-ins ( GEF, EMF, etc. ) required by Smooks dev tools.
Now let's progress to more advanced topics.
This "Quick Start" will show how to use the Smooks tools to create/edit the Smooks configuration file for Java2Java data transformation.
This chapter gives you a brief understanding of the Smooks tools.
Visit here to download the "java-to-java" example project.
Tip:
The example project is based on Maven, we suggest you to create a new eclipse Java project, copy the example code and .jar files from the example project and paste them into the eclipse Java project.
Select the Smooks Java-to-Java example project that you created and right-click, select the menu New > Other, then find Smooks > Smooks Configuration File. Click the Next button.
The first wizard page is a file path creation page. Select the src folder to be the files container, and input the name newConfig.smooks. Click Next.
The second wizard page is a transform data type choose page.
As the quick start introduces how to create/edit the Java-to-Java Smooks configuration file, let's select the Java-to-Java type as the source/target transform data type.
On the next page you are prompted to choose the source data for transformation. Let's select the Order class from the example project as the source JavaBean class.
Then the wizard page asks you to choose the target data for transformation. We select the ListOrder class as the target JavaBean class.
Tip:
You can omit two these steps and just press Finish. This will open the empty Smooks Configuration file. It's possible to select source/target data afterwards in the Smooks Graph editor.
When all the wizard steps are passed, a new Smooks Configuration file is created and the Smooks Editor will be opened automatically:
This editor contains several parts:
Table 2.1. The Smooks Editor Parts
| Editor feature | Functionality |
|---|---|
|
Problems area |
If there are any errors when you are editing the file, the Problems area displays them |
|
Source data tree |
The tree displays a structure of the transformed source data |
|
Target data tree |
The tree displays a structure of the transformed target data |
|
Mapping graphical area |
Show the data mapping connection lines |
|
Source/Target data selection links |
Click the link, and Data Selection wizard is opened helping you to choose the source/target data |
To choose the transform data you should make use of the data selection links:
Source Select for selecting source data
Target Select for selecting target data
After clicking the link the Data Type Selection wizard is opened, and there are two data types on the list: Java and XML.
Note
There will become more and more data types on the list as the development goes on.
Select the Java data type and click Next, you will see the JavaBean class selection page:
When you select all the necessary java classes, click Finish and the structure of the java class is displayed on the source/target data tree.
As you see, the source/target data tree displays the structure of the java class.
How to map it?
First, you should know what to transform:
Bind the "customerName" property of the Order#header to the "customerName" property of LineOrder.
Bind the "customerNumber" property of the Order#header to the "customerId" property of LineOrder.
Bind the "price" property of the OrderItem to the "unitPrice" property of LineItem.
Bind the "productId" property of the OrderItem to the "productCode" property of LineItem.
Bind the "quantity" property of the OrderItem to the "unitQuantity" property of LineItem.
Make sense?
OK, let's select the "customerName" item of the "header" item on the source data tree and start to drag it. When the drag item crosses the Mapping graphical area, you will see a connection line. Drop the item onto the "customerName" of the LineOrder on the target data view.
Now a dialog is opened asking you to connect the root node:
Please, click Yes to connect the root node. If you don't do that, this dialog is opened again when you connect other nodes.
Note:
Please, remember that the root nodes of the source data and target data *MUST* be connected.
This rule is not only for Java-to-Java, but also is relevant for XML-to-Java
Now let's do the same operation with the "customerNumber", that is what you should see:
Next, you are going to bind the properties of the OrderItem to the properties of the LineItem.
Select the "price" and drag it onto the "unitPrice" of the other side tree viewer. The Problems area shows an error:
How to deal with the error?
Please click the Fix it link, a menu is popped-up with several resolve methods on it.
Select the first resolve method: 'Connect the "OrderItem" to the "LineItem" '. As the result the "OrderItem" is connected with the "LineItem".
But the notify message area still shows some other errors:
OK, let's deal with the fire error. Click the Fix it link and select the first resolve method. The "orderItems" is connected with the "lineItems".
Tip:
Why does the error occur?
You will find that, if you only connect the property node without connecting the parent node of the property, the "connection error" occurs.
The connection of the "price-to-unitPrice" is the "Binding Connection", but it needs an "Instance Creation Connection" - the connection of the "OrderItem-to-LineItem".
After that, connect "quantity" to the "unitQuantity" and "productId" to the "productCode":
Now, you should save the file and the Smooks tools generate the correct configuration file content.
OK, let run the test class: example.Main. (Please, make sure that the Smooks engine loads the correct configuration file).
Success!
This chapter is packed with useful information about Smooks Graphical Editor Page usage
Smooks Graphical Editor page is one tab of the Smooks Editor.
This Graphical editor allows you to perform drug/drop operations with the nodes of transform data to map the source data to target data.
When you save the changes in the Graphical editor the correct Smooks Configuration file content is generated.
To adjust the properties of the connection lines in the editor, you should use the Properties view (activate it by following to Window > Show View > Other > General > Properties).
For example, if you defined a date decoder in the Smooks Configuration Editor, in the Properties view you can select it as a Mapping type for the "Date" type element.
Information on the topic could be found in the Quick Start/Smooks Editor section.
Click the links under the data view, the Data Type Selection wizard page will be shown.
There are sets of transform data type on the wizard page, select one type and click Next, the data source selection wizard page will be shown.
Note:
For different data type, the Data source selection wizard are different too.
When you finish the data selection (file path selection), click Finish, the data view displays the selected data structure.
To get information on the topic please, read the Quick Start/Mapping section.
When you do any mapping operations, the Smooks tools validate the file content with "Mapping Logic". If there are any errors of the configuration file content, error messages are shown in the Problems area.
Please, read the Quick Start/Mapping section to find how to fix the errors.
You can edit the properties of the connection lines with the Properties view.
Navigate to Window > Show View > Other > Properties, to open the Properties view.
When you select the connection line, the Properties view will show a set of section GUI for editing its properties.
Tip:
This GUI on the Properties view is displayed when the Smooks Graphical editor is active, if not, the Properties view displays empty GUI.
If the source data type of the selected connection line is "XML", the Properties view shows an XML Properties section GUI.
But if the source data type of the selected connection line is "Java", the XML Properties section GUI isn't displayed.
It means that if the source/target data type of the selected connection line is different, the Properties view shows a different GUI.
To discover about other Editor pages, read the next chapters
In this section you will explore the details of Smooks Configuration Editor usage
Smooks Configuration Editor is one tab of the Smooks Editor.
You can add/edit/remove the Date Decoder on the Configuration page of the Smooks Editor.
The configuration editor also edits the Smooks parse type and manages the Import Files.
Open the Other Configurations section, we will see there is a set of radio buttons:
Select the needed radio button to change the Smooks parse type.
Open the Other Configurations section, there is an Import Files list under the Smooks parse type buttons (see the figure above).
There are three buttons on the right side of the File Import list. You can click those to add/edit/remove the import files.
Tip:
If the import file doesn&t exist, the image of the import file is changed to "Error Image". If you double-click the import file in the Import File list, the file is opened with a new default editor.
Date Decoder is a resourceConfig element in the Smooks configuration file. It describes how to transform the "Date" type.
Click the New button to open the New Resource Type wizard dialog.
There are several resource type on the list. Select the Date Decoder and click the Finish button, a new Date Decoder item was added and shown on the resource type list.
There are several parameters in the Date Decoder resourceConfig element:
Format
Locale-Language
Locale-Country
You can modify the parameters of the Date Decoder item with the left detail page.
When you defined a new Date Decoder, then you can use the JavaBean Properties GUI to set it to be the "Java type".
Now when we've learnt Smooks Configuration Editor Page, let's have a look at one more Smooks Editor Page - Smooks Source Editor Page and investigate its functionality
This section provides information about Smooks Source Editor Page
You can use this editor to edit the Smooks Configuration file directly.
If the Smooks tools can't understand the configuration file or the configuration file is illegal (XML structure isn't right for Smooks Configuration file, etc.), the error is underlined.
We hope, our guide will help you to get started with JBoss Smooks Tools. Besides, for additional information you are welcome on JBoss forum.