开发地图编辑器_使用地图编辑器开发地图
存在XML映射以将源XML文档转换为目标XML文档。 映射编辑器获取在“映射编辑器”中创建的映射，并生成XSL文件以在运行时执行实际的XML转换。 在WebSphere Integration Developer中，XML映射有两种主要用法：
- 在构建中介流时，有时会出现一个原语的输出消息结构与下一个原语的输入消息结构不匹配的情况。 消息作为服务消息对象（SMO）通过中介流传递，该消息流具有一致的XML结构。 在这种情况下，您可以使用映射将消息从一种结构转换为另一种结构。
- 在构建流程流时，有时还会需要将流程流中的变量从一种类型转换为另一种类型。 您还可以在流程流中使用XML映射来转换和操作变量。
创建映射时，目标是构建一个映射，以生成完整且有效的目标XML文档。 生成的XML文档必须完整，因为它包含所有预期数据，并且该文档也必须有效并匹配其对应的架构。
本系列的第2部分， 在Mapping Editor中使用复杂的XML结构 ，介绍了更高级的XML映射主题。
映射编辑器
映射编辑器使使用源XML文档中的数据填充目标XML文档成为一项直观而直观的任务。 通常，源XML结构显示在左侧，目标XML结构显示在右侧， 如图1所示。 通过在源字段和目标字段之间绘制连接，可以在源元素与目标元素和属性之间创建映射。 编辑区域下方的属性视图使您可以优化和自定义在“映射编辑器”中创建的映射。 映射编辑器还包含一个测试视图，该视图允许您关联样本输入XML并立即查看地图的输出XML。
图1. XML映射编辑器
创建地图
在哪里创建地图
映射通常是在中介模块项目中创建的，以在特定中介流中使用，或在模块项目中创建的，以在特定业务流程中使用。 也可以在“库”项目中创建它们，这将使它们可在依赖于“库”的模块中的任何地图文件中重复使用。
在中介流中，使用XSL Transformation原语创建地图文件。 每个XSL转换原语都与一个映射文件相关联，该映射文件描述了要对输入XML进行的转换。 映射文件是根据实现原语时指定的信息创建的。
在业务流程中，使用“数据映射”基本操作创建映射文件。
在处理映射时，您可能会发现您正在不断映射相同的两种元素类型。 在这种情况下，您可能会发现创建一个Submap很有用，然后可以在映射这两种类型时重新使用它。 子图仅是您可以使用子图变换从其他地图文件调用的常规地图文件。 您可以从“映射”编辑器内创建一个子图，也可以通过右键单击“业务集成”视图并选择“ 新建”>“ XML映射”来创建它。
选择映射根
映射根是映射中的顶级输入和输出对。 通常，输入基于一种XML Schema类型，而输出则基于其他XML Schema类型。
在中介流中创建映射时，需要映射根。 映射根确定原始输入消息的哪一部分用作映射输入，以及原始输出消息的哪一部分用作映射输出。 要选择映射根，首先要确定目标文档的哪个部分需要更改，然后确定将填充目标文档的数据的来源。 一旦知道要使用文档的哪些区域，就可以为地图选择适当的根。 中介流中使用的XML映射只能具有单个输入或源以及单个输出或目标。 在中介流的情况下，消息是SMO消息，其分解如下：
- 语境
- 标头
- 身体
您可以选择SMO的任一部分作为根，或者，如果您需要多个SMO的部分，则可以选择SMO的根。 在大多数情况下，您的更改将仅在SMO主体中发生，并且该主体是映射的适当根。 但是，有时您可能需要上下文或标头中的数据来正确填充目标正文。 有时您可能需要更新目标上下文或目标标头。 在这种情况下，您将需要使用SMO“ /”的根作为映射的根。 使用“ /”作为根可以访问源SMO和目标SMO的所有区域。 使用选定的根创建了SMO映射后，您将无法更改根。
映射细化
在“映射编辑器”中工作时，您会将源模式的元素和属性与目标的元素和属性相关联。 一旦在源和目标之间创建了关联，该关联就称为转换或映射。 每个映射都可以有一个细化形式来指示它是什么类型的映射。 本节描述改进。
移动
Move是最基本的改进。 它在源端采用一个简单或复杂的字段，并将其不变地从源移动到目标。 对复制字段所做的唯一更改将是名称空间前缀，以确保它们在目标文档中有效。 当您想将某些内容从源复制到目标而不进行更改时，建议使用“移动”。
兑换
分配
要为目标元素或属性分配常量值时使用“分配细化”。 分配仅可用于将值分配给简单类型字段，例如字符串和整数。 要创建分配映射：
- 选择目标元素或属性以分配值。
- 右键单击目标元素或属性，然后选择创建变换 。
- 使用“属性”视图将所需的值分配给目标元素或属性。
当地地图
本地地图是用于组织映射文件的工具。 它使您可以嵌套复杂类型的映射，从而使顶层映射不会过于杂乱。 重要的是认识到在源和目标之间创建本地映射不会自行执行任何数据转换。 除非您进入“本地”地图并使用诸如“移动”之类的优化方法来创建映射，否则所有内容都不会从源移动到目标。 本地地图用作容器映射，以对嵌套映射（例如Move）进行本地化，以执行实际的转换。
本地地图包含一个输入字段和一个输出字段。 在需要多个输入字段的情况下，合并映射将替换本地映射，但是其行为类似。
在源和目标之间创建本地地图后，可以双击本地地图细化以导航到地图。 进入本地地图后，您可以创建子映射。 在本地地图中，您会注意到，您可以使用“上一级”图标导航出本地地图，返回到父级地图（
本地地图不可重用。 如果要映射的源类型和目标类型将在其他映射中以相同的方式映射，请考虑使用可在多个映射文件中重复使用和共享的子映射。 见子图这篇文章部分有关创建子图的更多信息。
合并
合并细化在某种意义上类似于本地地图，因为它是嵌套其他地图的容器。 与本地地图不同，合并支持多个源输入。 这使您可以从两个不同的源字段中获取数据并将它们合并为一个目标字段。 在处理数组时也使用合并。 有关更多信息，请参见第2部分中的使用数组 。
子图
子图细化是存储在单独文件中的两种特定类型之间的映射。 子映射是常规映射文件中的根映射，您可以从任何其他映射文件中引用它，因此非常适合重用。 由于子图是为重用而设计的，因此我们建议您将子图存储在库中，以便在相关模块之间轻松共享和重用子图。 如果您有两个不同的复杂类型经常相互关联以进行映射，则Submap是在这些类型之间创建可重用映射的好方法。
在某些情况下，您可能会发现无法为所需类型创建子图，因为该类型未在XSD文件中定义。 如果类型是在WSDL文件中定义的，则可能是这种情况。 Submap创建向导将不允许您创建非XSD定义类型的Submap作为输入或输出。 在这种情况下，您可以通过执行以下操作从WSDL文件中重构类型：
- 在“业务集成”视图中，在模块或引用的库项目的“数据类型”类别中找到所需的类型。
- 右键单击该类型，然后选择“ 重构”>“提取内联业务对象” 。
提取所需的类型后，可以使用提取的类型作为输入或输出来创建子图。 使用局部元素或匿名类型时，无法使用Submap优化。 对于本地元素或匿名类型，当前不能选择可重用的映射。
内建功能
您可以在“映射编辑器”中使用一些常用的内置函数，例如Concat，Normalize和Substring。 除这些以外，您还可以轻松使用60多种XPath和EXSLT Java™函数来转换数据。 以下各节说明一些内置功能。 XPath和EXSLT Java函数部分介绍了如何使用其他函数。
康卡特
Concat函数会将源中的两个或多个字符串连接到目标端的单个字符串值中。 内置的Concat函数通过其属性页支持前缀，后缀和定界符的规范。
要在表1所示的示例中实现所需的输出，可以使用具有以下属性的Concat变换：
- 指定输入顺序，以使cityName为第一个输入，countryName为第二个输入。
- 在cityName输入上使用定界符“，”。
表1.用例数据示例
| 输入项 | 所需输出 |
|---|---|
|
|
归一化
Normalize函数会将字符串从源移动到目标，并在移动过程中对字符串进行以下修改。
- 删除前导和尾随空白。
- 将字符串中的空白序列替换为单个空格。
要在表2所示的示例中获得所需的输出，可以使用Normalize变换。
表2.规范化示例
| 之前 | 后 |
|---|---|
|
|
子串
Substring函数将从源字符串中提取文本。 Substring函数使用分隔符和索引来确定要从传入的源字符串中提取什么文本。 根据指定的定界符，源字符串分为几部分。 索引用于标识要使用分割后的字符串的哪一部分。 默认情况下，索引为0，指示将使用第一部分。 例如，假设您要从
您可以通过指定“，”（逗号）作为分隔符来使用Substring函数。 默认情况下，索引0会返回分隔字符串的第一部分，在本示例中为Toronto。
要从同一字符串中提取国家/地区名称，请指定“，”（逗号后的空格）作为分隔符，并将索引设置为1，这将导致使用分割后的字符串的第二部分，在此示例中为加拿大。
如果不能保证源字符串中逗号后有空格，则可以对XPath表达式使用Custom修饰，例如： normalize-space(substring-after($destination, ",")) 。
XPath和EXSLT Java函数
字符串函数
这些函数对字符串进行操作或返回字符串。 映射编辑器支持的字符串功能的完整列表为：包含，格式编号，本地名称，名称，名称空间-uri，开头为，字符串，字符串长度，子字符串，之后的子字符串，之前的子字符串，系统-属性，翻译，对齐，数组连接和填充。
作为说明这些功能之一的示例，让我们考虑数组concat函数。 array concat函数将字符串数组作为输入，并将字符串的串联返回到单个字符串输出中。
作为说明这些功能之一的示例，请考虑表3的数组concat函数。
表3.数组连接示例
| 输入项 | 输出量 |
|---|---|
A |
|
在“映射编辑器”中创建数组连接函数后，“属性”视图中的“常规”选项卡将包含一个表，用于指定函数的输入参数。 这些参数的值是XPath表达式，可以使用表示输入连接的转换变量。 默认情况下，输入连接变量用作功能的输入； 但是，可以根据需要进行编辑。
输入参数的“常规”选项卡和表在所有其他XPath和EXSLT函数中通用。 一些功能包含可选的输入参数，您可以根据需要添加或删除这些参数。
数学函数
这些函数对数字进行运算或返回数值。 映射编辑器支持的数学函数的完整列表是：上限，计数，下限，数字，舍入，求和，abs，acos，asin，atan，atan2，常数，cos，exp，log，max，min，power，random ，sin，sqrt和tan。
布尔函数
这些函数对布尔值进行操作或返回布尔值。 映射编辑器支持的布尔函数的完整列表为：布尔值，false，lang，not和true。
日期和时间功能
这些功能可操作或返回日期和时间值。 映射编辑器中支持的日期和时间函数的完整列表是：date，dateTime，dayAbbreviation，dayInMonth，dayInWeek，dayInYear，dayName，dayOfWeekInMonth，格式化日期，hourInDay，jumpYear，minuteInHour，monthABbreviation，monthInYear，monthName，secondInMinute，时间weekInYear和year。
您可以使用dateTime函数获取当前日期和时间，而无需输入转换。 您也可以使用没有输入的其他日期和时间函数来获取当前值。 例如，使用在星期三无输入的dayAbbreviation函数将产生Wed的目标值。
格式化日期函数是有用的函数，用于根据指定的模式转换给定的dateTime，如表4所示。
表4.格式日期功能示例
| 之前 | 模式 | 后 |
|---|---|---|
Wednesday January 27, 2010 |
yyyy-MM-dd hh:mm:ss |
2010-01-27 06:29:25 |
Wednesday January 27, 2010 |
MMMM dd, yyyy |
January 27, 2010 |
“属性”视图中的“常规”选项卡包含配置“格式化日期”功能所需的属性。 日期和时间输入参数是XPath表达式，默认情况下，它使用表示函数输入连接的变量。 或者，您可以编辑此内容以输入用户定义的XPath表达式。
日期选择器在“格式化日期”功能属性的“常规”选项卡中也可用，可以用作输入日期和时间。 选择日期会生成一个XPath文字表达式，作为表示所选日期和时间的函数的输入。
格式化日期功能还包含一个模式，用于指定如何格式化给定的日期和时间。 可以从组合框中选择许多预定义的模式，或者可以输入用户定义的模式。 同样，如果在输入数据结构中定义的源元素中指定了模式，则也可以将用于表示输入连接的XPath变量用作模式。
最后，为格式日期功能提供了一个示例字段，以显示期望的结果以及提供的信息。
抬头
- 逗号分隔值文件查找 ：CSV（逗号分隔值）查找引擎将使用逗号分隔值文件来执行查找。 CSV文件的每一行都被视为新条目。 CSV文件的第一行可以是文件的列标题。 在CSV文件中进行查找时，这些属性允许您指定将哪个列用作键列，将哪个列用作值列。 您可以使用从0开始的索引或使用列标题名称来标识列。 要了解CSV文件中的列，请考虑以下数据：
State Name, Abbreviation, Old GPO, FIPS
Alabama, AL, Ala., 01
Alaska, AK, Alaska, 02
Arizona, AZ, Ariz, 04
Arkansas, AR, Ark., 05如果使用上述CSV文件根据状态缩写检索状态名称，则可以设置查找以将第1列用作键列，将0列用作值列。 或者，您也可以设置查找，以将“缩写”列用作键列，将“状态名称”用作值列。 在这两种情况下，键AK都会返回阿拉斯加的值。
要使用CSV查找，CSV文件必须具有* .csv文件扩展名。 CSV文件必须与地图文件位于同一项目中，或位于从属项目中。
- 属性文件查找 ：属性文件查找使用“ key = value”格式的文件来执行查找。
- 关系查找 ：关系使用现有的静态关系来执行查找。 在WebSphere Integration Developer中定义了静态关系来描述静态关联。 例如，可以定义一个关系来将状态名称与状态缩写相关联。 一旦定义了关系，映射内的查找就可以使用该关系来检索值。 这些属性使您可以定义关系中的哪个角色用作键，以及哪个角色用作值。
以下示例说明了查找映射的用法。 让我们考虑图2所示的CSV文件。
图2. CSV文件示例
在此示例中，输入文件将包含状态缩写，而输出将需要完整的状态名称， 如图3所示。
图3.查找映射
上面查找的属性如图4所示。
图4.查找属性
上图的结果如图5所示。
图5.映射结果
也可以提供自定义查找引擎。 产品帮助中的“ 创建自定义查找”主题说明了定义自定义查找引擎的过程。
其他改进
本文中未提及的其他改进主要用于处理数组和其他结构化数据时。 有关更多信息，请参见第2部分中的使用数组和自定义 。
条件映射
有时，地图中的变换取决于条件。 条件用于确定特定映射在运行时是否会发生，从而提供一种控制映射逻辑流程的方式。 映射编辑器包含对使用If，Else if和Else转换在映射上实现这种条件逻辑的支持。 这些转换根据给定的XPath表达式条件对一组映射进行分组。 另外，XML映射编辑器还通过直接提供XPath表达式或使用静态Java方法调用来支持单个映射的条件。 最后，隐式条件自动应用于连接到源数据的转换，这是可选的。 仅当源数据在运行时存在时，才会对可选源数据进行任何转换。 否则，将不会发生转换。
If，Else if和Else细化
通过从“属性”视图的“条件”选项卡中为其分配XPath表达式，可以在If和Else if精简条件上提供条件。 Else细化只能与关联的If或Else if细化一起存在，并且不具有任何条件。 请参阅XPath条件部分，以了解如何评估此类表达式。
在“映射编辑器”中创建If细化类似于创建其他变换。 只需在源元素和目标元素之间创建连接，并将转换类型更新为If细化。 创建If细化后，可以通过选择If细化并从悬停操作栏或上下文菜单中调用“添加其他if”或“添加其他”操作来添加其他if或Else细化。 创建Else if或Else精炼后，您必须添加目标连接以提供该精炼将在输出中填充的内容的上下文。 同样，您可以选择添加源连接以提供优化的输入上下文。 与其他细化不同，If，Else if和Else细化可以分别具有多个输入和输出连接，这将为嵌套映射提供操作依据。
If，Else if和Else优化项组合在一起以说明它们彼此之间的关联。 当映射包含If，Else if或Else细化的此类分组时，基于提供的条件，组中的这些细化中只有一个或一个都不会在运行时执行。 仅执行条件为第一个If或Else if的条件细化，该条件的计算结果为true。 否则，如果所有其他关联条件在分组内均失败，则将执行Else细化。 一旦执行了这些优化之一，与条件优化相关的所有嵌套映射将在运行时执行。
在If，Else if和Else细化分组上创建目标连接时，由于对这些细化施加了限制，因此必须小心：
- If，Else if和Else精炼分组中的所有目标连接都必须以目标数据结构上的同级元素为目标。 否则，将导致错误消息如下：“如果转换组未将彼此相同的元素作为目标，则Else中的所有转换”。 若要更正此问题，请确保条件精简组内的所有目标连接都是彼此的同级。
- 不相关的转换输出不能存在于条件转换组的输出范围内。 不相关的转换是那些不包含在If，Else if和Else改进中的转换。 条件转换组的输出范围定义为在最顶部连接的输出元素和最底部连接的输出元素之间。 不遵守此限制将导致以下错误消息：“ Move转换存在于条件转换的输出范围之外，这是无效的”。 若要更正此问题，请将无关转换放在条件转换之一中（如果在所有情况下都适用，则将其复制到所有条件转换中）。 以下说明了图6中所示的条件分组范围的示例。
图6.条件映射
注意，条件转换组的输出范围在元素“ field1”和元素“ field5”之间。 除非将其包含在If，Else if或Else精简之一中，否则其他任何不相关的转换都不能包含在此突出显示的区域内。
单变换条件
有时，单个转换只需要一个简单的条件即可执行所需的映射。 在这种情况下，您可以将XPath表达式应用于单个转换，而无需进行If细化。 就像在If和Else if精炼上添加XPath表达式一样，您可以使用Properties视图中的Condition选项卡在单个转换上添加条件。
为了更好地理解“映射编辑器”中内置的单个转换条件和隐式条件，请考虑一种情况，如果您想使用一个输入字段的值（如果源中存在该值）。 否则，您将使用其他输入字段的值。 请考虑以下情形：
输入：
- 用于特定建议的可选字符串输入。
- 一般推荐的必需字符串输入。
输出：
- 单个建议尽可能具体。 如果有具体的建议，那就是价值。 否则，将使用一般建议。
在这种情况下，您可以考虑这样做：
- 在输入特定建议和输出建议之间创建移动细化。 存在特定建议时，将发生“移动”并且正确设置了值。 由于将为可选输入自动生成条件，因此无需在此转换中添加其他条件。
- 在输入的一般建议和输出的建议之间创建移动细化。 使用以下条件对Move进行条件处理，以便仅在输入中不存在特定建议时才执行Move：
not(/body/response/specificRecommendation)。
使用条件的另一种方法是将过滤器应用于可重复元素列表。 有关更多信息，请参见第2部分中的过滤数组 。
XPath条件
您可以使用XPath表达式为If，Else If或其他优化条件编写条件。 评估XPath表达式时，将根据表达式的返回值确定条件的值，如表5所示。
表5. XPath条件评估标准
| 表达式返回类型 | 真实结果 | 错误的结果 |
|---|---|---|
| 节点集 | 非空节点集 | 空节点集 |
| 串 | 长度为一个或多个字符的字符串 | 零长度的字符串 |
| 数 | 零以外的任何数字（负数或正数） | 零 |
| 布尔值 | 真正 | 假 |
使用XPath编写条件时，可以使用相对或绝对路径。 转换的输入可用作变量，并插入表达式中。 您可以在条件输入区域中使用内容辅助来查看可用变量的列表。 您还可以在条件输入区域中使用内容辅助来利用XPath函数。 要在条件输入区域中调用内容辅助，请使用CTRL + Space 。
使用相对路径时，当前无法使用../语法在上下文节点上方引用。 如果需要访问在输入值之一中不可访问的信息，请使用绝对路径。 对于使用变量的示例， 图7中的内容帮助显示cityName可作为变量使用：
图7. XPath内容助手
单击上面列表中的cityName变量后，将“ $ cityName”插入输入字段，然后可以继续创建条件，例如$cityName = "Toronto" 。
要了解使用条件的基础，请考虑以下示例。 一个旅行公司以下列提示之一的形式向客户提供有关其旅行目的地的建议：
- 天气会很热 -带上防晒霜。
- 天气会很冷 -带上皮大衣。
提示取决于所选目的地的温度。 对于温度高于0°C的目的地，会给出炎热的天气提示。 否则，会给出寒冷的天气提示。 您可以像这样调整映射：
- 根据源celsiusTemperature元素创建If细化，该元素的目标是输出中的咨询元素。
- 将以下XPath表达式添加为If细化条件
$celsiusTemperature > 0。 - 向If细化添加和其他细化，然后将顾问元素定位到输出上。
- 在If细化中添加一个嵌套的Assign变换，其值为“天气会很热 -带上防晒霜”。
- 在“ Else”细化中添加一个嵌套的Assign变换，其值为“天气将很冷 -带上您的风衣”。
Java条件
您还可以使用对静态Java方法的调用来构建条件。 使用Java方法调用时，该方法的返回值确定条件结果，如表6所示。
表6. Java条件评估标准
| 方法返回类型 | 真实条件 | 错误条件 |
|---|---|---|
| org.w3c.dom.NodeList | 非空节点列表 | 空节点列表或null |
| 串 | 长度为一个或多个字符的字符串 | 零长度的字符串 |
| 整型 | 零以外的任何数字（负数或正数） | 零 |
| 布尔值 | 真正 | 假 |
编写Java方法以计算条件的逻辑：
- 在现有的Java项目中创建新的静态Java方法，或创建一个新的Java项目以在其中存储该方法。
- 确保您的映射项目或其库依赖项之一包含对Java项目的依赖项。
- 单击“ Java导入”属性页面，然后单击“ 添加”按钮。 接下来，指定前缀和关联的Java类。
- 在条件输入字段中，使用内容辅助（可通过按CTRL + Space来获得 ）来插入适当的方法调用。
例如，假设您具有以下条件：
| 类： | TravelCompanyUtilities |
|---|---|
| 方法： | isDesirableCity |
| 参数： | cityName（类型为String） |
The condition might look like this:
TravelCompanyUtilities::isDesirableCity(/body/response/destination/cityName)
要么
TravelCompanyUtilities::isDesirableCity($cityName)
技巧和窍门
This section contains some tips and tricks to help make XML mapping an easier task. The tips in this section include:
- Tips for working faster : Match mapping, content assist.
- Tips for working with large schemas : Scrolling, filtering, navigation trail.
- Other tips : Test map view, sorting transforms, viewing model groups, moving mappings.
Match mapping
You can use match mapping when the source and target are similar or contain similar sections. Match mapping always attempts to match whatever is showing on the source side of the editor with whatever is on the target side of the editor. It is not dependent on a selection. A match is made when an element or attribute on the source side has the same name as an element or attribute on the target side. The types of the matched elements must be similar for the match to produce useful mappings. If the matched types are complex types, a container map is used to match them at the top level, and then match mapping will continue within the container mapping until no more matches are found. To invoke match mapping, use the "Map source to target based on the name and types" toolbar button (
For example, if a Move transform had been used to map the body on the source to the body on the target, and you wanted to make a minor adjustment to something in the body, you need to delete the Move transform and create individual transforms at a more granular level. However, when using match mapping, container maps are used and drilling into those container maps allow you to get to the exact location where the changes need to be made. In this way, only transforms that correspond to the minor adjustments need to be changed.
When the source and target have similar fields of the same type, but may not have the same name, you can use Local maps to match these similar types, and then use match mapping within the Local maps that you create. For example, suppose we have the following source and target as shown in Figure 8 .
Figure 8. Mapping editor before match mapping is invoked
Invoking match mapping at this level will not find any matches and will display an error message indicating that no matches were found for the "getWeather" element in the target. However, the GetWeather element in the target is looking for a cityName and a countryName which will come from the first element in the destinations array on the source side. We can reset the starting point for the match mapping by creating a Local map between the destinations element in the source and the GetWeather element in the target as shown in Fiure 9.
Figure 9. Mapping editor after match mapping is invoked
From within the Local map, invoking match mapping will map the CityName and CountryName.
Content assist and XPath Expression Builder
Some of the entry fields that are used within the property pages of the Mapping editor contain content assist to help when syntax is important. If content assist is available in an entry field, a light-bulb icon (
When editing an XPath expression, the content assist will contain a menu item called "Insert Simple XPath" expression. Clicking the menu option will display the "Simple XPath Expression Builder" dialog. The XPath Expression Builder assists in creating simple XPath expressions as shown in Figure 10 .
Figure 10. Simple XPath expression builder
卷动
When creating a transform or mapping in the editor, it is typical to do so by locating a source input field, clicking on the source input field, holding the mouse button down, dragging a connection over to the target field, and finally releasing the mouse button to complete the action. Using this method is quick and easy, but inhibits the ability of using the editor's scroll bars at the same time. This makes it hard to work with large schemas where the source and target fields of an intended transformation are not always in view with each other at the same time. You can use the following methods to create transformations between a source and target that are not visible at the same time.
- Hover over the source input field, single-click the drag handle that appears, but do not hold down the mouse button as shown in Figure 11 .
Figure 11. Drag handle
This will initiate the connection creation process while still giving the ability to use the scrollbars at the same time. While the connection wire is active, you can also initiate scrolling by hovering near the editor edge and pausing briefly. - Select the source input field without holding down the mouse button. Scroll to the appropriate matching field in the target, hold the CTRL key and click the target field to select it. Finally, right-click on the target field and select Create Transform . A transform between the selected source and target will be created and you can then customize the transform as desired.
- Select the source input field, right-click, and select Create Connection . Once the connection wire appears, you can use the scrollbars at the same time to find the target field and complete the transformation. While the connection is being created, you can also initiate scrolling by hovering near the editor edge and pausing briefly.
筛选
Figure 12. Mapping editor source and target filters
To clear a filter, click
Navigation trail
As you create nested mappings such as Local maps, you can find yourself deep within an element structure wondering where exactly you came from. At the top of the editor is a navigation trail that lets you know what elements you are nested in, which is shown in Figure 13 . Clicking any part of the navigation trail will quickly bring the editor view to the associated level.
Figure 13. Mapping editor navigation trail
Test map view
While working in the Mapping Editor, you can use the Test Map view to test your mapping transforms as you create them. For details on the The Test Map view, see Problem determination .
Sorting transforms
By default, the Mapping Editor will sort the transforms column based on the source input. This means that the transformations align themselves with their associated source input fields. In some cases, it may be more convenient to have the transform column sorted by the target outputs. Since this will align transformations closest to their target output, it provides a quick way to see what type of transformation is operating on a particular target. To switch the sorting method, right-click in the mapping editor area and use the "Sort Transforms" menu action, or click the desired sort method button on the local toolbar (by source
Viewing model groups
By default, the Mapping Editor uses a simplified view of the XML inputs and outputs. There is some information that may be in the schema that is not shown by default in the Mapping Editor. For example, a choice defined in the schema is shown as a flat list in the mapping editor. To see such model group information in the XML Mapping Editor, edit the XML Mapping preferences to show the groups. To edit the preferences, click the Preferences (
In addition to the details shown in the Mapping Editor window, you can also see general information about the selected element in the properties view as well.
Moving mappings
- A map becomes disorganized because not enough container mappings are being used. In this case, you can create new container mapping and then cut (CTRL+X) the existing mappings that are outside the new container mapping and paste (CTRL+V) them onto the new container mapping. The pasted mapping will then be moved inside the new container mapping. For more information about organizing maps, see Organizing mappings .
- An existing mapping needs to be moved from one target to another. In some cases, you may have already created a mapping to a certain target and then realize that you meant to create that mapping from the same source but to a different target with the same type. In that case, you can cut (CTRL+X) the existing map, select the correct target field, and then select paste (CTRL+V).
- An existing mapping needs to be duplicated for a different source and target. If you have already created a mapping between a source and target, then you decide that you want to create the same mapping between a different source and target that have the same types as the original source and target, you can copy (CTRL+C) the existing mapping, select the new desired source and target elements (hold the CTRL key to multi-select), then invoke paste (CTRL+V).
- A mapping from one file needs to be duplicated in another file. As long as the source and target types are the same, you can copy a mapping from one file to another using copy and paste. Start by copying (CTRL+C) the mapping in one file, go to the new file, select the new source and target fields (using the CTRL key to multi-select), and then invoke the paste action (CTRL+V).
Problem determination
While creating a map, it is a good idea to test the map periodically to ensure that the desired results are being achieved.
Input files
To test a map in the tooling, the first step is to create or select an input document to test. The easiest way to accomplish this is to use the input document generation tools that are included in the Mapping Editor. These tools will create a basic input document based on the input XML schema. Once the input document has been generated, you can start testing immediately and can later enhance the input by adding additional elements and values. Use the following methods to create input documents:
- While using the Create New XML Mapping wizard from an XSL Transformation primitive in a mediation flow, you can check the Create a sample XML input file for testing the XML Map checkbox.
- From within the Mapping Editor, you can click the Associate XML files toolbar button, and then use the Generate Input button to create and associate a new sample input file.
The Generate Sample Input File button is disabled in cases where the root input of the map is not a global element. Maps with global element inputs can only be tested by calling them from another map.
- From within the Mapping Editor, you can click the Test Map toolbar button to open the Test Map view. From the Test Map view, click the Associate XML files toolbar button and then use the Generate Input button to create and associate a new sample input file.
As an alternative to creating a sample input file, if you already have a sample input file, you can associate the existing XML input file with the map file using the Associate XML files toolbar action. Currently, input files are generally saved in the same project as the maps they apply to and show up in the Business Integration view under the Transformations > Data Map Test Data category .
Iterative testing using the Test Map view
Once you have a sample input file associated with the map file, you can use the Test Map view to test the map file. This method of testing can be used as you are still developing your mappings. The view will perform transformations on the input document using whatever transformations you have implemented in your mapping file, even if you have not yet saved the changes to the mapping file. This allows you to ensure that the transforms you create have the desired result before committing changes to your mapping file. To open the Test Map view, use the Test Map action (
While using the Test Map view, you can refresh the output at anytime by clicking the Run transformations button on the Test Map view toolbar. You can also make updates to the input XML file from the Test Map view and can save those changes by clicking the Save selected input file toolbar button. Changes to input XML files can also be committed to a new input file by using the Save selected input file as toolbar button.
The Test Map view provides two methods for viewing the input and output XML. The visual tab represents the XML in a tree format allowing you to navigate and edit the values easily. The visual tab also provides some validation, such as verifying whether the value assigned to a simple type is valid.
Testing maps using the Integration Test Client
In addition to the Test Map view, you can also test a completed XML Map using the Integration Test Client. You can save tests that you create in the test client and re-run them multiple times. You can also debug mapping transformations while testing with the Integration Test Client.
To test a map file using the integration test client, right-click on an XML map file in the Business Integration view and select Test . You can also select an XSL Transformation node in a mediation flow and right-click to invoke the Test XML Map action as well.
To debug a map while using the integration test client, select the Stop for debug before transformations checkbox in the Invoke XML Map Event detailed properties before running the event. You can also set breakpoints on the transformations in the Mapping Editor by right-clicking the transformation and selecting an action from the "Debug" menu.
Testing maps on the server
When using the above methods of testing, the maps are being tested locally in the tooling. There may be cases where the map executes successfully in the tooling, but behaves incorrectly at runtime while running on the server. In these cases, you will need to debug the problem on the server.
Testing an XML map on the server is accomplished by testing the component that contains the XML Map to be tested. In the Assembly Editor, right-click the mediation flow or business process flow component that contains the map to be tested and invoke the Integration Test Client using Test Component or Test Component in Isolation.
To understand how an XSL Transformation primitive in a mediation flow is executed at runtime, consider the following scenario shown in Figure 14 .
Figure 14. XSLT primitive
- SMO input object is received by the "SortDestinations" XSL Transformation primitive.
- SMO input is serialized into XML for processing.
- XML input is transformed using the XSL file associated with the primitive and an XML output is produced.
- Output XML is de-serialized into the SMO output object.
Fine-grained trace in the Integration Test Client will allow you to see the inputs and outputs to each XSL Transformation primitive in the mediation flow. In most cases, if an XML map works during local testing and fails at runtime, the problem is in Step 4 from above, the conversion of the output XML to the SMO object. This is the point where an inconsistency between the output XML and the schema will cause a failure. To help diagnose and fix these types of problems, you can turn on server tracing to allow you to examine the messages.
Note : Currently, fine-grained trace is only available within a Mediation Flow component and is not available in a Business Process Flow.
To turn on server tracing:
- In the Servers view, while the server is running, right-click the applicable server and select Administration > Run administrative console .
- Log-in to the administrative console (
adminis the default ID and password). - In the Troubleshooting section, select Logs and Trace .
- In the Logging and Tracing area, click the server name, such as server1.
- Click Change Log Detail Levels .
-
In the Change Log Details Level entry field, add the following text to whatever text already exists in the entry field:
: com.ibm.ws.sibx.*=all.For example, if the entry field contains this before making a change:
*=info.The entry field will look like this after the changes:
*=info: com.ibm.ws.sibx.*=all. - 单击确定 。
- Click Save to save changes and promote the configuration changes to the server.
- Logout of the administration console.
- Restart the server.
Once the server tracing has been enabled, rerun your test and then review the trace.log file. To determine the location of the trace.log file:
- Open the Server Logs view.
- In the Server Logs view toolbar, click the Load server console or log button.
- Select Load from server log directory .
- Click Browse .
- Check the checkbox for the trace.log file and click OK .
- Note the location of the trace.log file and click Cancel .
Note : Although you can use the viewer to view the trace.log file, finding the required trace information is easier when using a text file editor to view the log file.
When you open the trace.log file, you can locate serialized SMO instances by searching for the string:
You can also view the raw XML data before and after a transformation primitive by looking for the following strings:
Serialized DataObject prior to transformation and Result of transformation .
Another option for debugging is to set a breakpoint on the XSL transformation primitive in the Mediation Flow Editor. The debugger will allow inspection of SMO values both before and after the XSL transformation primitive at runtime.
最佳实践
Organizing mappings
When working in the Mapping Editor, there are things you can do to make the maps easier to navigate, understand, and maintain. One technique for implementing a map is to start by looking at the fields in the target one by one. For each field in the target, consider:
- Does the target field need to be populated? (Is it required?)
- If the target field needs to be populated, where will the data come from?
- If the target is going to be populated from data that is in the source XML, where in the source is the data located?
- Is the data source of the same type as the target data type? If the types are the same, and the data does not need to be modified in any way, consider using a Move transform.
- If the data from the source and the target are not the same type or manipulation of the data is required, consider using a Local map or a Submap to map the source and target. By using a Local map or a Submap, you can nest the details of the mapping inside a child transform, leaving less clutter and confusion at the root level of your mapping file.
- Will there be a future requirement to map the source and target types in another mapping or multiple times in the current mapping? If you determine that these types are frequently mapped together, consider using a Submap which is re-usable. Otherwise, a Local map is the way to go.
- If there are multiple source inputs required to populate a single target, consider using a Merge which is a specialized Local map that accepts multiple inputs.
- Within a Submap or Local map, do many of the source and target fields have the same name and types? If there is a lot of similarity between the source and target, consider using Match Mapping to map the similar fields as a starting point for further customizations.
- For complex types that are the target of a mapping, ensure that none of the target types' children are targets of any other mappings other than those that are defined within a container mapping on the parent. For example, suppose that you wanted to copy all the context information from the source to the target, but you also wanted to add something from the body to the context or correlation as well. The correct way to accomplish this is shown in Figure 15 .
Figure 15. Correct way to handle nested mappings
Figure 16 is incorrect because there is a Move on context and another Move to contextor correlation.
Figure 16. Incorrect way to handle nested mappings
Figure 17 is also wrong because the Move to context or correlation is not within the Local map defined on context.
Figure 17. Incorrect way to handle nested mappings
Even if the Local map on context does not map the correlation element, the Move is still wrong, because it must be within the Local map.
Once you have determined the best type of mapping for each target field at the root level, you can use the same process to create mappings within the Local map, Merge, and Submap transforms that you have created.
While organizing mappings, the following actions might be helpful:
- Cut, copy, and paste : See Moving mappings for more information.
- Refactor to submap : If you already created a Local map and later decide it is better as a reusable submap, right-click the existing local map and invoke the Refactor to submap action.
Migrating maps to Integration Developer
In most cases, a .map file that was created in a previous version of Integration Developer will work correctly in the new versions of Integration Developer. In some cases, a warning message may appear to indicate that the XSL file associated with a given map was generated using an earlier version. In those cases, we recommend to regenerate the associated XSL file. The XSL can be regenerated using the quick fix associated with the warning message in the Problems view, or also when the .map file is open in the Mapping Editor by using the "Generate XSLT script" button on the Mapping Editor local toolbar.
One exception to the general migration rule is that the format of XML maps changed significantly between Integration Developer V6.0.2 and Integration Developer V6.1. A tool that migrates Integration Developer V6.0.2 XML mapping files (.xmx) to the newer Integration Developer V6.1.2 and later format (.map) is provided in Integration Developer. After importing projects containing *.xmx files, you will receive warnings in the Problems view. To launch the migration tool, right-click on a warning message and select Quick Fix , or try to open a *.xmx file in Integration Developer V6.1.2 or later.
Once you have completed the auto migration, you will still need to test your migrated map file to ensure that it produces the desired results. In V6.0.2, empty elements were created for required elements in the target XML even if those elements were not mapped in the mapping. However, in V6.1.2 and later, these empty elements are no longer created unless you explicitly create a mapping. Because of this and other differences in the two versions, we recommend that you test the maps after migration.
Part 2 of this series, Working with complex XML structures in the Mapping Editor , explains more advanced XML mapping topics.
结论
In this article, you learned how to create, build, and test XML maps using WebSphere Integration Developer V7, as well as how to create simple mappings using a variety of refinements available within the XML Mapping editor. You now have enough skills to design, develop, and deploy XML maps within WebSphere Integration Developer.
翻译自: https://www.ibm.com/developerworks/websphere/library/techarticles/1003_spriet1/1003_spriet1.html