2009年8月24日星期一

Smooks Tools - QuickStart


Smooks Configuration Editor is a tools for Smooks data transform platform , it's a eclipse plug-in base Eclipse.

As far , the tools contains two editors :

1. Smooks configuration file editor , its name is Smooks Configuration Editor.

2. EDI message mapping config file editor , its name is EDI Message Mapping Editor.

This article will introduct the Smooks Configuration Editor simply.

Quick Start

For making your guys to be familiarity with this editor quickly , I will use a "QuickStart" to be the begining of all of the articles. This article will tell peoples how to use the Smooks tools to create/edit the smooks config file of Java-to-Java smooks example.


Download and install

First we need to download the Eclipse and Smooks tools' plug-ins



When finish downloading Eclipse WTP , unzip it to some directory , then unzip the Smook tools zip file , copy the files under ./plugins folder to the Eclipse WTP folder (./eclipse/plugins).

After that we need to download the Smooks1.2.1 from Smooks.org

When we finish the works start up the Eclipse. Select Help -> About Eclipse SDK -> Installation Details -> Plug-in on the menu bar of Eclipses , on the plug-ins' list

we will see there are 3 plug-ins of Smooks tools here:



It means that the Smooks tools install successfully.

New a Java project

We create a new Java project inEclipse and create a libs folder on this new project , then we put all the jars come from Smooks 1.2.1 libraries into this folder and add those JARs to the classpath of the Java project. (Right-click the Java project -> Properties -> Java Build Path -> Libraries -> Add JARs... )

Then we need to create all tarnsform target Java files and the input source Java files on this Java project. ( Those Java class files come from the Java-to-Java example of Smooks 1.2.1 , The readers can download them by theirself or download from here directly.)

Mapping Rules

At the begining of working with Smooks tools , we need to understand the Java-to-Java mapping rules of this case :

The transform input Java class : example.sourcemodel.Order , its structure looks like this :


1.Order Class

2.Order class contains a Header class and a List class

3.Header class has customerName,customerNumber,priority these 3 properties.

4.List stores the OrderItem class

5.OrderItem has price,productId,quantity 3 properties.


Let's look at the transform target Java class : LineOrder

Its structure is :

1.LineOrder class contains 'customerId','customerName','priority' 3 properties and a lineItems array。

2.The array lineItems is makeuped with LineItem class.

3.LineItem class has 'productCode','unitPrice','unitQuantity' 3 properties.

Finish overview the structure of transform target and input source, then we will makeup those rules to transform the input source java class to the target java class:

1. Each instance of Order class mapping with a instance of LineOrder class.

2. The value of 'customerName' of the Header class need to assign itself to the 'customerName' property of LineOrder instance.

3. The value of 'customerNumber' of the Header class need to assign itself to the 'customerId' property of LineOrder instance.

4. The value of 'proiority' of the Header class need to assign itself to the 'proiority' property of LineOrder instance.

5.For the orderitems List of Order instance , it need to create a new lineItems array instance for LineOrder , and each OrderItem instance in the orderItems List need to create a LineItem instance , those instances will be put into the lineItems array.

6. The value of 'productId' of OrderItem instance will assign itself to the 'productCode' of LineItem.

7. The value of 'price' of OrderItem instance will assign itself to the 'unitPrice' of LineItem.

8. The value of 'quantity' of OrderItem instance will assign itself to the 'unitQuantity' of LineItem.

Before go to the next section , please read th rules deeply.


New Smooks configuration file


Select the src folder of the Java project we created , right-click and select New -> Other... -> Smooks -> Smooks Configuratin File.


Click Next > , select the folder for the new smooks config file and click Finish button.


We will see the new smooks config file and this file will be opened with Smooks Configuration Editor automatically.



Add the input data

On the bottom of this editor , there are sort of tabs , they are :

Overview, Reader , Message Filter ,Graph , Source


At the first , we need to add the Order class as the input data. Click the Reader tab , swich to the Reader/Input editor page.



At the bottom of this edit page , we can see there is a 'Input data' list , click the Add button to add a Java input data follow the Input data wizard.



Click the Finish , the Order class will be added as a input data.

Add the target Bean

After adding the input data , let's switch to the Message Filter page:



Click the Add button , a wizard page will be shown , let's select the 'Java Binding v1.2 -> Bean v1.2 ' and click OK to add a Bean :



Then we can find on the Message Filter page , a Bean v1.2 item is added , select on it , the right side of the page will show the GUI to edit its properties:



On the "Bean Id" , we input 'lineOrder' as the Bean's id , On the 'Class' UI we click the 'Browse' button , and select the LineOrder as the Bean's class.
(Note : When we input on the Class text control , we can type 'Alt + /' , the content assist pop dialog will be shown , so it's will increase the efficiency. If type 'Alt + /' dosen't work , try to use the 'Ctrl + space' , it's the 'Key Assist' of Eclipse , it's not the same on the different platform.)

Finish this work , Let's click the 'Add Binding' link on the bottom of this page , it will show a dialog to ask us which 'Binding' of the Bean we will add.


Select all and click OK , we can see there is a sort of Binding elements are added under the Bean item:


Let's follow this way , add a Array Bean lineItems and a Bean LineItem.

These two Beans' Class and Id value is :

Array Bean ,BeanId : lineItems , Class : example.trgmodel.LineItem[]

LineItem Bean , BeanId : lineItem , Class : example.trgmodel.LineItem
(Note : In the Smooks , to be a array Bean , the class string value is end with '[]' , it means that this bean is a array type)
Finish this work , use the 'Add Binding' link to add the all bindings for each Bean.

Finally , it looks like this:


We can see there are many 'red cross' on the Binding elements , because we don't set the properties of them perfectly.


Create Mapping


Now let's switch to the Graph page , we will see some figures here:


Let me introduct those figures:

At the left , there is a figure with out header , it's the Order input data we add , now the graph page display it as a tree here.

On the right up-to-down , Bean v1.2 is the Bean elements we added in the Message Filter page , now they are shown on the Graph page , thire sub-figures is thire Bindings element. (please see the last section)

Let's try to select the "Order" node of the left figure , and drag it , we will see on the Graph page , a line is started from the "Order" node , we can drag it to the "Bean v1.2 (lineOrder)" node on the right and drop it , now there is a line between the two nodes.

This line means : When the Smooks runtime meets each 'Order' class instance , it will new a instance describe by the "Bean v1.2 (lineOrder)" model's Class property . We have knew this on the "Mapping Rules" section.

Note : Actually , the Smooks runtime dosen't know the Java instance , all the input data in the Smooks runtime will be transform to XML stream.

Now , let's mapping (link) the nodes of 'Input data' figures to the 'Bean' figure follow with the "Mapping Rules":

1. Each instance of Order class mapping with a instance of LineOrder class.
operations : Link the 'order' of 'Input data' figure with the 'lineOrder' Bean figure.

2. The value of 'customerName' of the Header class need to assign itself to the 'customerName' property of LineOrder instance.

operations : Link the 'customerName' of 'Input data' figure with the 'lineOrder.customerName'

3. The value of 'customerNumber' of the Header class need to assign itself to the 'customerId' property of LineOrder instance.

operations : Link the 'customerNumber' with the 'lineOrder. customerId'

4. The value of 'proiority' of the Header class need to assign itself to the 'proiority' property of LineOrder instance.

operations :Link the 'proiority' with the 'lineOrder. proiority'

5.For the orderitems List of Order instance , it need to create a new lineItems array instance for LineOrder , and each OrderItem instance in the orderItems List need to create a LineItem instance , those instances will be put into the lineItems array.

operations : First , link the 'orderItems' of 'Input data' figure to the 'lineItems' Bean,then link the 'lineOrder.lineItems' to the 'lineItems' Bean , and link the sub-figure of 'lineItems' Bean 'lineItems.LineItem' to the 'lineItem' Bean.


6. The value of 'productId' of OrderItem instance will assign itself to the 'productCode' of LineItem.

operations: Link the 'productId' with the 'lineItem. productCode'.

7. The value of 'price' of OrderItem instance will assign itself to the 'unitPrice' of LineItem.

operations : Link the 'price' with the 'lineItem. unitPrice'.

8. The value of 'quantity' of OrderItem instance will assign itself to the 'unitQuantity' of LineItem.

operations : Link the 'quantity' with the 'lineItem. unitQuantity'.


Finally , we will get this picture :




And now , we need to return to the Message Filter page , select on the Bean v1.2(lineItems) node , remove its property value (keep it to be empty ) , because it's array , so it can't have the property value.

The mapping works was finished , but there are little works we don't do.

Go to the Message Filter page , we need to set some 'Type' mapping for some 'Binding':

1.lineItem.unitPrice ,select on the node,Input 'BigDecimal' to Decoder property .

2.lineItem.unitQuantity , select on the node,Input 'Integer' to Decoder property .

3.lineOrder.priority , select on the node,right-click ,choose : 'Add Smooks Resource -> Decod Param Type',add four Decod Param.

And for these four Decod Param , their 'Name' and 'Value' is :

enumType :example.trgmodel.LineOrderPriority

LOW :NOT_IMPORTANT

MEDIUM : IMPORTANT

HIGH:VERY_IMPORTANT


Save the file , as far , our mapping work was finished.

Run the test case

Open the Main.java ( you have downloaded it when you start this article) , run it to test.

没有评论:

发表评论