Smooks Dev Tools Reference Guide

Tip:

The example project is base on Maven, you suggest you to create a new eclipse Java project and copy the example code and .jar files from the example project paste them into the eclipse Java project.

2.2. Smooks configuration file wizard

Select the Smooks Java-to-Java example project what you created and right-click, select the menu: "New" -> "Other...", find the "Smooks Configuration File" wizard. Click "Next" button.

Figure 2.1. To select Smooks Configuration File wizard

The first wizard page is a file path creation page. Select the "src" to be the files container, and input "smooks-newconfig.smooks". Click "Next".

Figure 2.2. Choose the configuration file container and type the file name

The second wizard page is a transform data type choose page.

Note

As the quick start introduces how to create/edit the Java-to-Java Smooks configuration file, it's necessary that "Java" type is the source/target transform data type please.

Figure 2.3. Select Data Type

2.3. Smooks form Editor

When all the wizard steps are passed, a new Smooks configuration file is created and the Smooks editor will be opened automatically.

You will see the "Smooks Form Editor":

Figure 2.4. Smooks form editor

This editor contains several parts:

Notify message display area. If there are any errors when you are editing the file, the error area will display them.

Source data tree. The tree will display the structure of transformed source data.

Target data tree. The tree will display the structure of transformed target data.

Mapping graphical area. Show the data mapping connection lines.

Source/Target data selection links. Click the link, and "Data Selection Wizard" will be opened helping you to choose the source/target data.

2.4. Choosing the source/target data

Click the data selection links to choose the transform data. The "Data Selection Wizard" is opened, and there are two data types on the list: XML and Java.

Note

There will be more and more data types on a list as the development went on.

Figure 2.5. Data type wizard

Select the "JavaBean Data Type" and click "Next", you will see a java class selection page:

Figure 2.6. JavaBean Data Selection Wizard

When you select all the necessary java classes, click "Finish" and the structure of the java class will be displayed on the Source data tree. Please, do the same with a target data link.

Figure 2.7. Displaying Structure of the Transformed Data

2.5. Mapping

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 oped asking you to connect the root node:

Figure 2.8. Dialog Asking You to Connect to the Root Nodes

Please, click "Yes" to connect the root node, if you didn't do that, this dialog will be 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 the same is also relevant for XML-to-Java

Now let's do the same operation with the "customerNumber", that is what you want to see:

Figure 2.9. Correctly Mapping Editor

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 error message display area will show an error:

Figure 2.10. Connection Error 1

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" ', then the "OrderItem" is connected with the "LineItem".

But the notify message area still shows some other errors:

Figure 2.11. Connection Error 2

OK, let's deal with the fire error ---- Click "Fix it" link and select the first resolve method. The "orderItems" is connected with the "lineItems".

Tip

Why does the occur error?

You will find that, if you only connect the property node without connecting the parent node of the property, the "connection error" occur

The connection of the "price-to-unitPrice" is the "Binding Connection", but it needs a "Instance Creation Connection" -the connection of the "OrderItem-to-LineItem".

After that, connect the quantity to the unitQuantity ; connect the productId to the productCode:

Figure 2.12. Complete mapping

Now, you should save the file and the Smooks tools will 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!

Chapter 3. Smooks Graphical Editor Page

3.1. Introducing the areas of graphical editor
3.2. Load source/target data
3.3. Using the graphical editor for mapping
3.4. Error messages
3.5. Properties Viewer

Smooks Graphical Editor Page is one tab of the Smooks Form Editor.

Figure 3.1. Graphical Editor

This graphical editor could allow 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 will be generated.

3.1. Introducing the areas of graphical editor

Information on the topic could be found here "Quick Start/Smooks Form Editor"

3.2. Load source/target data

Click the links under the data viewer, the data type selection wizard page will be shown.

Figure 3.2. Data type selection wizard page

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.

Figure 3.3. Java data source selection wizard page

Figure 3.4. XML file path selection wizard page

When you finish the data selection (file path selection), Click Finish , the data viewer will display the selected data structure.

3.3. Using the graphical editor for mapping

To get information on the topic please, read the "Quick Start/Mapping"

3.4. Error messages

When you do any mapping operations, the Smooks tools validates the file content with "Mapping Logic", If there is any errors of the configuration file content , error messages are shown on the "Error message area" .

Please, read the "Quick Start/Mapping" to find how to fix the errors.

3.5. Properties Viewer

You can edit the properties of the "connection lines" with the properties viewer.

Select the menu: "Window -> Show View -> Other -> Properties", the properties viewer is opened.

When you select on the connection lines, the properties viewer will show a set of section GUI for editing the properties of the connection line.

Tip

This GUI on the properties viewer is displayed when the "Smooks Graphical Page" is active, if not, the properties viewer displays empty GUI.

If the source data type of the selected connection line is "XML", The properties viewer shows a "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 viewer shows different GUI.

Figure 3.5. JavaBean Properties Section

Figure 3.6. XML properties section

Figure 3.7. Mapping properties section

Chapter 4. Smooks Configuration Editor Page

4.1. Smooks parse type
4.2. Import file
4.3. Date Decoder Detail Page

Smooks Configuration Editor Page is one tab of the Smooks Form Editor.

Figure 4.1. Graphical Editor

The "Date Decoder" can add/edit/remove on the configuration editor page.

The configuration also edit the "Smooks parse type" and manage the "Import File" .

4.1. Smooks parse type

Open the "Other configuration" section, we will see there is a set of radio buttons:

Figure 4.2. Smooks parse type

Select the radio button to change the Smooks parse type.

4.2. Import file

Open the "Other configuration" section, there is a "Import File" list under the "Smooks parse type" buttons.

Figure 4.3. Import File

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 dosen't exist, the image of the import file will change to "Error Image". If you double-click the import file in the "Import File" list, the file will be open with a new default editor.

4.3. Date Decoder Detail Page

"Date Decoder" is a resourceConfig element in the Smooks configuration file.It describe how to transform the "Date" type.

Click "New" button to open the "New Resource Type" wizard dialog.

Figure 4.4. Resource Type Selection Wizard

There are several resource type on the list. Select the "Date Decoder" and click "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:

locale-language
format
locale-country

You can modify the parameters of the "Date Decoder" item with the left detail page.

Figure 4.5. Date Decoder Detail Page

When you defined new "Date Decoder", they can use the "JavaBean Properties" GUI to set the them to be the "Java type".

5.1. XML Source Editor

You can use this editor to edit the Smooks configuration file directly.

Figure 5.1. Graphical Editor

5.2. Error Messages GUI

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 message panel will be displayed above the XML editor.

Figure 5.2. Graphical Editor

Tip

When the error message panel is displayed, other editors ( Graphical Editor, Configuration Editor ) are disabled.

You can't edit the configuration file with other editors until file becomes valid.