English Version
Smooks Tools 是一个针对Smooks数据转换平台而开发的一个工具,整个工具是基于Eclipse的。
工具目前主要是由两个编辑器组成:1.Smooks configuration file编辑器,也就是Smooks Configuration Editor。2.EDI消息映射配置文件编辑器,EDI Message Mapping Editor。
本文将简要介绍一下Smooks configuration editor。
Quick Start
为了能够快速熟悉一下整个编辑器,我将通过一个QuickStart作为整片文章的开始。本例将讲述怎么使用Smooks tools创建,配置Java-to-Java转换所需的配置文件,以及如何编写Smooks代码进行运行该例。
下载以及安装
首先需要先下载Eclipse以及Smooks工具的Plugin:
Eclipse WTP 3.1 :http://www.eclipse.org/downloads/
Smooks Tools : http://www.jboss.org/tools/download.html
下载好Eclipse WTP后,解压缩到某个目录下,然后将smooks tools压缩包解压后,找到./plugins文件夹,将该文件夹下的jar文件复制到Eclipse WTP对应的文件夹(./eclipse/plugins)下。
然后我们需要去到Smooks.org下载Smooks 1.2.1。
完成后启动Eclipse,在菜单栏上选择:Help -> About Eclipse SDK -> Installation Details -> Plug-ins ,在列表中我们会看到Smooks tools所对应的3个plugin:
这说明Smooks tools已经安装成功了。
新建Smooks项目
在eclipse中我们新建一个Java工程,在项目下新建一个libs文件夹,然后将所下载的Smooks 1.2.1中的libraries复制到该文件夹下,并将这些libraries加入到java项目的classpath当中(右键点击项目-> Properties -> Java Build Path -> Libraries -> Add JARs... )
然后在该项目中创建我们所要转换的目标Java类以及转换输入Java类。(这些Java类以及代码都来自Smooks 1.2.1中的Java-to-Java example,读者可以去自行下载该例,或者直接从本文给出的链接中下载)。
映射规则
在使用Smooks tools工作之前,我们需要先搞清楚映射的规则:
转换输入Java类example.sourcemodel.Order类,具有以下结构:
1.Order类本身
2.Order包含有一个Header类,以及一个List类
3.Header类具有customerName,customerNumber,priority三个属性
4.List中将存放的是一个OrderItem类
5.OrderItem具有price,productId,quantity三个属性
让我们看看转换目标类LineOrder:
该结构为:
1.LineOrder类包含有customerId,customerName,priority 三个属性以及一个lineItems的数组。
2.数据lineItems是由LineItem组成
3.LineItem具有productCode,unitPrice,unitQuantity三个属性。
了解完转换输入以及转换目标的结构后,我们将要以下列的规则来将转换输入映射到转换目标中:
1.每一个Order类的实例对应生成一个LineOrder的实例
2.Order实例中Header的customerName值将赋值到对应LineOrder实例中的customerName
3.Order实例中Header的customerNumber值将赋值到对应LineOrder实例中的customerId
4.Order实例中Header的proiority值将赋值到对应LineOrder实例中的proiority
5.每一个Order实例中的orderitems List的实例将对应生成一个LineOrder中的lineItems数组对象,并且orderItem List中的OrderItem实例将会对应生成一个LineItem对象,该LineItem的对象会被放置到生成的lineItems数组对象中。
6.OrderItem实例中的productId值将赋值到对应LineItem对象中的productCode
7.OrderItem实例中的price值将赋值到对应LineItem对象中的unitPrice
8.OrderItem实例中的quantity值将赋值到对应LineItem对象中的unitQuantity
请仔细阅读以上规则后进入到下一节。
新建Smooks configuration file
我们选中所建项目的src文件夹,点右键,选择New -> Other... -> Smooks -> Smooks Configuratin File.
然后点击Next > ,选择所要生成smooks config file所在的文件夹,选择到所生成项目的src下,然后点击Finish完成配置文件的创建。
我们将会看到新建的smooks conig file , 并且该文件自动被Smooks Configuration Editor打开。
添加输入数据
在该编辑器的下方有一组tab按钮,分别是:
Overview, Reader , Message Filter ,Graph , Source
首先第一步,我们需要将转换输入Order类添加进来,点击Reader tab,切换到Reader/Input编辑页。
在该编辑页的下方,我们可以看到一个Input Data的列表,点击该列表右侧的Add按钮,根据向导,添加一个Java输入:
确定后点击Finish,Order类将被作为输入数据添加进来。
添加目标Bean
完成输入数据的添加后,我们切换到Message Filter页。
点击Add按钮,将有一个向导页出现。
我们选择Java Binding v1.2 -> Bean v1.2 然后确定,添加一个Bean:
这时我们会发现在Message Filter页面中增加一个Bean v1.2项,选中该项,在页面的右侧将会显示出它可配置的属性:
在bean Id 处,我们输入lineOrder,作为该Bean的id,在Class处我们点击Browse按钮,选择LineOrder类作为该Bean的Class。
(温馨小贴士:选中Class的文本框后,可以输入字符,然后按Alt+/ 键,将会有内容帮助窗口弹出,这样的可以提高效率。如果输入Alt + /无效果,可以使用Ctrl + space,这是Eclipse的内容帮助快捷键,在不同的平台上会有不同)
将这两项值输入完成后,我们点击下方的Add Binding , 将会弹出一个对话框,让我们选择所有添加的Bean的绑定属性:
全选后点击OK,我们会看到在左侧的Bean元素下,会生成一组属性绑定元素:
我们按照上述方法,再生成一个数组Bean lineItems以及一个LineItem的Bean。
这两个Bean所对应的Class以及Bean id 为:
数组Bean ,BeanId : lineItems , Class : example.trgmodel.LineItem[]
LineItem Bean , BeanId : lineItem , Class : example.trgmodel.LineItem
(温馨小贴士:作为数组bean,其class的值一般是以[]作为结尾,说明该bean是一个数组类型,而class中的类名则是数组所存放的bean的类型)
完成后,分别使用Add Binding键,将对应的绑定属性都添加好。
最后的结果如下:
我们看到有很多小红叉在这些Binding元素上,这是因为我们还没有设置其对应的源的Selector值。
(温馨小贴士:关于selector请到smooks.org上查看相关的描述)
创建映射
现在让我们切换到Graph页面,我们会看到一组图形:
现在我来对该图做一个介绍:
最左侧没有标题的图形是我们设定的Input Data,它是以树形结构的形式展现的。
右侧从上到下, Bean v1.2 这是我们在Message Filter中添加的一个Bean v1.2 ,现在显示在Graph页中,它的子图形是它所对应的binding子项。请参照上一节。
现在我们可以试着选中最左侧的图形的根节点“Order”,然后拖拽它,我们会发现会有一根线出现。我们将它拖拽到Bean v1.2 (lineOrder)上后释放,在这两个图形中出现了一条线。
这条线表示:Order 实例将会根据Bean v1.2 (lineOrder)中所描述的class,对应生成一个实例。我们在前几个章节“映射规则” 中已经说明了。
现在我们根据映射规则,将输入图形对应的点映射到Bean对应的图形上:
1.每一个Order类的实例对应生成一个LineOrder的实例
操作:将order点连接到lineOrder上
2.Order实例中Header的customerName值将赋值到对应LineOrder实例中的customerName
操作:将customerName连接到 lineOrder.customerName上
3.Order实例中Header的customerNumber值将赋值到对应LineOrder实例中的customerId
操作:将customerNumber连接到 lineOrder.customerId上
4.Order实例中Header的proiority值将赋值到对应LineOrder实例中的proiority
操作:将proiority连接到 lineOrder.proiority上
5.每一个Order实例中的orderitems List的实例将对应生成一个LineOrder中的lineItems数组对象,并且orderItem List中的OrderItem实例将会对应生成一个LineItem对象,该LineItem的对象会被放置到生成的lineItems数组对象中。
操作:先将lineOrder.lineItems连接到lineItems图形上,然后将orderItems连接到 lineItems上 , 并将lineItems的子图形lineItems.LineItem连接到lineItem上
6.OrderItem实例中的productId值将赋值到对应LineItem对象中的productCode
操作:将productId连接到 lineItem.productCode上
7.OrderItem实例中的price值将赋值到对应LineItem对象中的unitPrice
操作:将price连接到 lineItem.unitPrice上
8.OrderItem实例中的quantity值将赋值到对应LineItem对象中的unitQuantity
操作:将quantity连接到 lineItem.unitQuantity上
最后我们得到以下的图形:
在这里,我们需要回到Message Filter页面,选中Bean v1.2 (lineItems)节点,将它的property值删除,因为它所对应的是数组,所以不应该具有property值。
我们的映射工作已经完成,还有一些类型匹配上的工作没有做。
切换到Message Filter页,我们需要对一些属性的类型进行一些映射。
1.lineItem.unitPrice ,选中该元素,在它的Decoder中输入BigDecimal
2.lineItem.unitQuantity , 险种该元素,在她的Decoder中输入Integer
3.lineOrder.priority , 选中该元素,点击右键,选择 Add Smooks Resource -> Decod Param Type,一个增加四组。
对应的Name和Value分别是:
enumType :example.trgmodel.LineOrderPriority
LOW :NOT_IMPORTANT
MEDIUM : IMPORTANT
HIGH:VERY_IMPORTANT
保存文件。自此,我们的配置工作就完成了。
运行转换测试
先下载Main类,然后放到项目中,运行该类,测试转换是否成功。