扩展的 XPath 2.0 支持

业务事件可以包含复杂的 XML，而 XML 可能包含诸如重复元素（序列）等构造、父、子或同代节点认为合格的信息或者其位置或解释取决于其他内容的信息。

为处理此类复杂事件内容，Business Monitor 提供了一些内置函数。

表 1. 内置函数
函数	目的
`wbm:serialize(...)`	从入站事件抽取 XML 文档片段并将其转换为单个字符串。
`wbm:evaluate(...)`	针对 XML 文档的字符串表示求值 XPath 2.0 表达式并产生字符串结果。
`wbm:send-events(...)`	此函数与公共事件基础结构 (CEI) 配合使用。针对序列中的每个项创建并发送出站事件。这些事件可以作为入站事件接收并用于创建新的监控上下文，每项一个。
`send-events(...)`	此函数与动态事件框架配合使用。针对序列中的每个项创建并发送出站事件。这些事件可以作为入站事件接收并用于创建新的监控上下文，每项一个。
`wbm:escape-special-characters(...)`	替换所有特殊字符以便使 XML 的字符串表示可以显示在 Web 浏览器中（例如，将 `<` 替换为 `<`）。

上述每个函数描述如下。描述中使用的样本表达式假设入局顺序事件包含类似于以下示例的内容，即 orderPart 事件部分定义引用的内容：

<ord:order xmlns:ord="http://www.example.org/order">
        <ord:orderNumber>F0004391</ord:orderNumber>
        <ord:orderEntryTimestamp>2009-01-17T17:56:25-05:00</ord:orderEntryTimestamp>
        <ord:customer>
            <ord:name>The Other Company</ord:name>
            <ord:shippingAddress>
                <ord:street>1000 Main Street</ord:street>
                <ord:city>Any Town</ord:city>
                <ord:state>XY</ord:state>
                <ord:zip>10001</ord:zip>
            </ord:shippingAddress>
        </ord:customer>
        <ord:items>
            <ord:item ord:sku="190123">
                <ord:description>my item</ord:description>
                <ord:due>2009-01-20-05:00</ord:due>
                <ord:quantity>32</ord:quantity>
                <ord:price>12.20</ord:price>
            </ord:item>
            <ord:item ord:sku="030234">
                <ord:description>your item</ord:description>
                <ord:due>2009-01-22-05:00</ord:due>
                <ord:quantity>12</ord:quantity>
                <ord:price>1604.98</ord:price>
            </ord:item>
            <ord:item ord:sku="030405">
                <ord:description>her item</ord:description>
                <ord:due>2009-01-23-05:00</ord:due>
                <ord:quantity>125</ord:quantity>
                <ord:price>199.25</ord:price>
            </ord:item>
        </ord:items>
        <ord:deliveryDates>
            <ord:date>2009-01-20-05:00</ord:date>
            <ord:date>2009-01-22-05:00</ord:date>
            <ord:date>2009-01-23-05:00</ord:date>
        </ord:deliveryDates>
        <ord:tax>2673.38</ord:tax>
        <ord:total>44556.41</ord:total>
    </ord:order>

本页使用以下名称空间声明。

xmlns:wbm="http://www.ibm.com/xmlns/prod/websphere/monitoring/6.2.0/functions"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ord="http://www.example.org/order"

`wbm:serialize(...)`

要将某个事件的 XML 内容（xs:any 槽中的内容）的部分或全部检索为字符串，请使用 wbm:serialize(...) 函数进行处理。

wbm:serialize( $xml as xs:anyType? ) as xs:string? 

wbm:serialize( $xml as xs:anyType?, $delimiter as xs:string? ) as xs:string?

其中：

$xml 是入局事件的路径，它遵从表 2：引用事件内容的入站事件路径中的约束。
$delimiter 用作定界符，当 $xml 求值生成两个或多个项，并且它们的字符串表示合并以形成结果时，使用该定界符。

wbm:serialize(...) 函数从入局事件检索 XML 片段，将它们序列化，然后返回为一个字符串。该函数的第一版等效于带空定界符字符串的第二版。该函数仅在 $xml 求值产生空序列时返回空序列。

以下示例假设 newOrderEvent 指定模型元素定义表达式作用域内的入站事件预订，并且 orderPart 是其中一个事件部分：

wbm:serialize( newOrderEvent/orderPart/ord:customer/ord:shippingAddress )

wbm:serialize( newOrderEvent/orderPart/ord:items/ord:item/@ord:sku, ", " )

第一个示例可能会返回装运地址的字符串表示。第二个示例可能会返回以逗号分隔的已订购项目 SKU 编号的列表。

要获取使用 wbm:serialize() 和 wbm:evaluate() 函数的另一个示例，请参阅“添加度量值和关键业绩指标 (KPI)”。

`wbm:evaluate(...)`

要对序列化的 XML 文档求值 XPath 2.0 表达式，请使用 wbm:evaluate(...) 函数进行处理。

wbm:evaluate( $xml as xs:string?, $xpath as xs:string, $delimiter as xs:string ) as xs:string?

wbm:evaluate( $xml as xs:string?, $xpath as xs:string, $delimiter as xs:string, $var1 as xs:string? ) as xs:string?

wbm:evaluate( $xml as xs:string?, $xpath as xs:string, $delimiter as xs:string, $var1 as xs:string?, $var2 as xs:string? ) as xs:string?
...

其中：

$xml 是序列化的 XML 文档。
$xpath 是有效的 XPath 2.0 表达式（请参阅 http://www.w3.org/TR/xpath20/）。
$delimiter 用作定界符，当 $xml 求值生成两个或多个项，并且它们的字符串表示合并以形成结果时，使用该定界符。
$var1 到 $var5 是可选自变量（最多可传递五个自变量），并可代替 $xpath 中的 XPath 自变量 $var1 到 $var5。

wbm:evaluate(...) 函数对序列化的 XML 文档求值 XPath 2.0 表达式，并返回序列化格式的结果。如果第一个自变量 ($xml) 为空，那么将返回空序列。

如果 XPath 表达式 ($xpath) 的 $var1 到 $var5 集合中包含任何变量而没有传递该集合的任何自变量，那么这些变量将替换为空序列。如果传递的变量值多于表达式中找到的变量数，那么将忽略多余的值。$xpath 自变量必须是字面值。

以下示例假设 newOrderEvent 指定模型元素定义表达式作用域内的入站事件预订，并且 orderPart 是其中一个事件部分：

wbm:evaluate( wbm:serialize( newOrderEvent/orderPart/ord:items ), "fn:sum( ord:items/ord:item[ord:price > 1000]/ord:quantity )", "" )

wbm:evaluate( wbm:serialize( newOrderEvent/orderPart/ord:items ), "ord:items/ord:item[ord:due < xs:date($var1)]/@ord:sku", ", ", xs:string(earlyDate) )

两个示例都使用 wbm:serialize() 函数从订单事件抽取项列表。然后第一个示例计算超过 1000 美元的项总数。由于该表达式的结果将始终是一个数字，因此定界符字符串此时无意义。

第二个示例返回以逗号分隔的项 SKU 编号的列表，这些项的到期日早于 earlyDate 度量中的日期。请注意，该度量中的 xs:date 值转换为要传递到 wbm:evaluate() 函数的 xs:string，然后返回到要用于比较的 xs:date。

要获取使用 wbm:serialize() 和 wbm:evaluate() 函数的其他示例，请参阅“监控来自 SAP 企业信息系统 (EIS) 的事件而不进行调解”中的EIS 方案：添加度量值与关键业绩指标 (KPI)。

注：尽管 wbm:evaluate() 函数的第一个自变量必须是有效的 XML 文档，但 wbm:serialize() 函数返回的 XML 片段可能并非始终是有效的 XML 文档。出于此原因，wbm:serialize() 必须返回具有一个根元素的 XML 字符串。

`wbm:send-events(...)`

要使用 CEI 针对序列中的每个项发送出站事件，请使用 wbm:send-events(...) 函数进行处理。

wbm:send-events( $xml as xs:string?, $forEachItemIn as xs:string, $outboundXml as xs:string ) as xs:integer

wbm:send-events( $xml as xs:string?, $forEachItemIn as xs:string, $outboundXml as xs:string, $var1 as xs:string? ) as xs:integer

wbm:send-events( $xml as xs:string?, $forEachItemIn as xs:string, $outboundXml as xs:string, $var1 as xs:string?, $var2 as xs:string? ) as xs:integer
...

其中：

$xml 是序列化的 XML 文档。
$forEachItemIn 是用于确定序列的 XPath 表达式。它必须是有效的 XPath 表达式（请参阅 http://www.w3.org/TR/xpath20/）。
$outboundXml 是针对序列中每项进行求值的 XPath 表达式。求值结果将成为稍后发送的新出站事件的内容。$outboundXml 也必须是有效的 XPath 表达式。
$var1 到 $var5 是可选自变量（最多可传递五个自变量），用于定义 $forEachItemIn 中 XPath 变量 $var1 到 $var5 以及 $outboundXml 的值。

wbm:send-events(...) 函数针对序列中每个项发送出站事件，一个项发送一个事件。该序列通过对 XML 文档求值 $forEachItemIn 来确定。对于生成序列中的每个项，将求值 $outboundXml，并且求值结果将成为稍后发送的新出站事件的内容。通常，这些事件返回给 Business Monitor 并用于为每个项创建新监控上下文。可以在以下任何位置接收事件：子上下文中、父上下文中、返回到产生事件的同一上下文中或完全不相关的监控上下文中。它们是新的入局事件，处理方法与其他任何入局事件相同。

可在 $outboundXml 表达式中使用内置变量 $currentItem，以引用当前序列项，内置变量 $currentItemPos 可用于引用自己在序列中的位置。序列位置从 1 开始。

如果 XPath 表达式的 $var1 到 $var5 集合中包含任何变量而没有传递该集合的任何自变量，那么这些变量将替换为空序列。如果传递的变量值多于表达式中找到的变量数，那么将忽略多余的值。

wbm:send-events(...) 函数返回已发送事件的数量。如果第一个自变量为空，那么将返回 0 并且不发送任何事件。第二个和第三个自变量必须是字面值。

以下示例假设 xs:string 度量 allItems 包含一个项列表（可能由类似 wbm:serialize( newOrderEvent/orderPart/ord:items ) 的函数产生）：

wbm:send-events( allItems, "ord:items/ord:item[ord:due < xs:date($var1)]", "$currentItem", xs:string(earlyDate) )

作为第二个自变量传递的表达式将生成到期日早于 earlyDate 度量中存储日期的所有项的集合。对于其中每个项，将使用当前项作为内容创建并发送出站事件。

以下示例假设 xs:string 度量 theOrder 包含订单文档的字符串表示（可能由类似 wbm:serialize( newOrderEvent/orderPart ) 的函数产生）：

wbm:send-events( theOrder, "ord:order/ord:items/ord:item", "$currentItem, ord:order/ord:deliveryDates/ord:date[$currentItemPos]" )

对作为第二个自变量传递的表达式求值，并生成所有订单项的序列。对于其中每个项，创建并发送出站事件。事件内容是项本身，后跟对应于该项在交付日期列表中位置的日期。

`send-events(...)`

要使用动态事件框架发送出站事件，请使用监控模型中的 send-events(...) 函数。

要使用此函数，请将 BusinessMonitorFunctions855.jar 文件复制到 IBM® Integration Designer 中的监控模型项目。

在 install_root/scripts.wbm/xpath-ext 中找到 BusinessMonitorFunctions855.jar 文件。
将 UDF JAR 文件添加到 Integration Designer 中的监视模型项目。请参阅管理用户定义的函数。
要点：将 JAR 文件添加到监视模型项目后，会在“外部函数库”面板中记录一个错误。错误消息末尾指示 a required class com.ibm.bpm.def.spi.EventPointData was not found。忽略此错误。请勿通过将 com.ibm.bpm.def.jar 文件添加到类路径来尝试解决此错误。向此类路径添加此文件会导致无法生成监控模型。

以下示例显示如何使用 send-events 函数：

your prefix:send-events(wbm:serialize(IB_DEF_OrderReceived/RootData), "xmlns:order='http://VinnysPizza/pizzaOrder.xsd' order:Order/order:lineItems","$currentItem")

其中：

第一个自变量是序列化的 XML 文档（示例中的 wbm:serialize(IB_DEF_OrderReceived/RootData）。
第二个自变量确定发出出站事件的顺序（示例中的 "xmlns:order='http://VinnysPizza/pizzaOrder.xsd' order:Order/order:lineItems"）。名称空间声明（如 xmlns:order）需要使用单引号括起来。可以使用多个名称空间声明，但需要由空格进行分隔。自变量的 order:Order/order:lineItems 部分指定出站事件内容在 XSD 结构中的位置。
第三个自变量是 XPath 表达式，针对序列中的每项都会进行计算，用于设置出站事件的内容。

由 send-events 函数发送的出站事件将与以下事件点关键字一起发送。这些事件点关键字是自动生成的，无法进行更改。

应用程序名称：监控模型标识
版本：监控模型版本
组件类型：MC（表示“监控上下文”）
组件名称：通常为监控上下文标识
元素类型：INBOUND_EVENT、TRIGGER 或 UNKNOWN
元素名称：通常为元素的标识
性质：FIRE、ENTRY 或 UNKNOWN

使用 send-events 函数发出的事件的入站事件定义应当指定与以下示例相似的事件点过滤器：

monitor model ID/*/*/*/*/*/*

事件点过滤器的第二部分可以包含监控模型版本，但建议使用通配符代替。如果事件点过滤器中包含模型版本信息，请除去任何连字符、冒号、T 或 Z 字符。格式为 20150602110500，而不是 2015-06-02T11:05:00Z。

`wbm:escape-special-characters(...)`

要替换序列化 XML 中的特殊字符以使生成的 XML 能够显示在 Web 浏览器中，请使用 wbm:escape-special-characters(...) 函数进行处理。您可以对 wbm:serialize() 或 wbm:evaluate() 产生的序列化 XML 运行该函数。

wbm:escape-special-characters( $xml as xs:string? ) as xs:string?

wbm:escape-special-characters( $xml as xs:string?, $spacesForTab as xs:integer? ) as xs:string?

其中：

$xml 是序列化的 XML 文档。
$spacesForTab 是要替换跳进字符的不间断空格数量。在该函数只包含一个自变量时，此数字是 4。在包含两个自变量时，如果该自变量为空或为负，将不进行替换，并且跳进字符保持不受影响。

wbm:escape-special-characters(...) 函数执行以下字符替换。

表 2. 字符替换
原件	运行 wbm:escape-special-characters() 后
<	`<`
>	`>`
&	`&`
"	`"`
'	`'`
<tab>	`    `（除非通过 `$spacesForTab` 自变量设置为其他数量的空格）

以下示例格式化装运地址以显示在 Web 浏览器中。第二个示例将每个跳进字符替换为两个空格。

wbm:escape-special-characters( wbm:serialize( newOrderEvent/orderPart/ord:customer/ord:shippingAddress ) )

wbm:escape-special-characters( wbm:serialize( newOrderEvent/orderPart/ord:customer/ord:shippingAddress ), 2 )