com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_link3' is unknown.

XPath Extensions

Owned by Former user (Deleted)
Last updated: Nov 06, 2012Version comment
7 min read

WSO2 BPS extends the default XPath coverage provided by the WS-BPEL specification, mostly by adding support for XPath 2.0 and offering a few utility extension functions to make some assignments easier. To use XPath 2.0 in processes, use the "queryLanguage" and "expressionLanguage' attributes as shown in the example below.

queryLanguage="urn:oasis:names:tc:wsbpel:2.0:sublang:xpath2.0"expressionLanguage="urn:oasis:names:tc:wsbpel:2.0:sublang:xpath2.0"

To make the XPath 2.0 default for the process, add these attributes to the root process element. If you want to stick with XPath 1.0 but want XPath 2.0 support for a specific assignment, you can also define these attributes on an assign element.

Extension Functions

All extension functions are defined in the ODE extension namespace: http://www.apache.org/ode/type/extension. This namespace will be associated with the ode prefix in the examples discussed below.

insert-before

Allows to insert one or more siblings (specified by the $siblings argument in the signature below) before the first node of children (specified by the $children argument), all of whose nodes must have the same parent (specified by the $context argument).

ode:insert-before($contextas node(),$childrenas node()*,$siblingsas node()*)as node()

By design, this function is non-updating in that it preserves the identity and properties of its arguments (i.e., they don't try to change the XML in-place). Instead, a modified copy of the context node is created, essentially giving it a new identity. Further, it returns a single R-value item, as opposed to a sequence.

Example in the context of an assign activity:

<assign>
   <copy>
      <from>ode:insert-before($parent, $parent/child::node[position()=last()], $siblings)</from>
      <tovariable="parent"/>
   </copy>
</assign>

For those familiar with the XQuery Update Facility (http://www.w3.org/TR/2008/CR-xquery-update-10-20080801), the above example is semantically equivalent to the expression shown below:

insert nodes $siblings before $parent/child::node[position()=last()]

insert-after

Allows to insert one or more siblings (specified by the $siblings argument in the signature below) after the last node of children (specified by the $children argument), all of whose nodes must have the same parent (specified by the $context argument).

ode:insert-after($contextas node(),$childrenas node()*,$siblingsas node()*)as node()

By design, this function is non-updating in that it preserves the identity and properties of its arguments (i.e., they don't try to change the XML in-place). Instead, a modified copy of the context node is created, essentially giving it a new identity. Further, it returns a single R-value item, as opposed to a sequence.

Example in the context of an assign activity:

<assign>
    <copy>
        <from>ode:insert-after($parent, $parent/child::node(), $siblings)</from>
        <tovariable="parent"/>
    </copy>
</assign>

For those familiar with the XQuery Update Facility (http://www.w3.org/TR/2008/CR-xquery-update-10-20080801), the above example is semantically equivalent to the expression shown below:

insert nodes $siblings after $parent/child::node()

insert-as-first-into

This is a function that allows you to insert the node(s) (specified by the $children argument in the signature below) as the first child(ren) of a given context node (specified by the $context argument).

ode:insert-as-first-into($contextas node(),$childrenas node()*)as node()

By design, this function is non-updating in that it preserves the identity and properties of its arguments (i.e., they don't try to change the XML in-place). Instead, a modified copy of the context node is created, essentially giving it a new identity. Further, it returns a single R-value item, as opposed to a sequence.

Example in the context of an assign activity:

<assign>
    <copy>
        <from>ode:insert-as-first-into($parent, $children)</from>
        <tovariable="parent"/>
    </copy>
</assign>

For those familiar with the XQuery Update Facility (http://www.w3.org/TR/2008/CR-xquery-update-10-20080801), the above example is semantically equivalent to the expression shown below:

insert nodes $childrenas first into $parent

insert-as-last-into

This is a function that allows you to insert the node(s) (specified by the $children argument in the signature below) as the last child(ren) of a given context node (specified by the $context argument).

ode:insert-as-last-into($contextas node(),$childrenas node()*)as node()

By design, this function is non-updating in that it preserves the identity and properties of its arguments (i.e., they don't try to change the XML in-place). Instead, a modified copy of the context node is created, essentially giving it a new identity. Further, it returns a single R-value item, as opposed to a sequence.

Example in the context of an assign activity:

<assign>
    <copy>
        <from>ode:insert-as-last-into($parent, $children)</from>
        <tovariable="parent"/>
    </copy>
</assign>

For those familiar with the XQuery Update Facility (http://www.w3.org/TR/2008/CR-xquery-update-10-20080801), the above example is semantically equivalent to the expression shown below:

insert nodes $childrenas last into $parent

delete

This is a function that allows you to delete one or more node(s) (specified by the $children argument in the signature below) from its parent (specified by the $context argument).

ode:delete($contextas node(),$childrenas node()*)as node()

By design, this function is non-updating in that it preserves the identity and properties of its arguments (i.e., they don't try to change the XML in-place). Instead, a modified copy of the context node is created, essentially giving it a new identity. Further, it returns a single R-value item, as opposed to a sequence.

Example in the context of an assign activity:

<assign>
    <copy>
       <from>ode:delete($parent, $children)</from>
       <tovariable="parent"/>
    </copy>
</assign>

For those familiar with the XQuery Update Facility (http://www.w3.org/TR/2008/CR-xquery-update-10-20080801), the above example is semantically equivalent to the expression shown below:

delete nodes $children

rename

This is a function that allows you to rename the context node (specified by the $context argument in the signature below) as per the given name (specified by $item, which is either a QName, Element or String).

ode:rename($contextas node(),$nameas item())as node()

By design, this function is non-updating in that it preserves the identity and properties of its arguments (i.e., they don't try to change the XML in-place). Instead, a modified copy of the context node is created, essentially giving it a new identity. Further, it returns a single R-value item, as opposed to a sequence.

Example in the context of an assign activity:

<assign>
    <copy>
        <from>ode:rename($person, fn:QName("http://www.example.com/example", "manager"))</from>
        <tovariable="person"/>
    </copy>
</assign>

For those familiar with the XQuery Update Facility (http://www.w3.org/TR/2008/CR-xquery-update-10-20080801), the above example is semantically equivalent to the expression shown below:

rename$personas fn:QName("http://www.example.com/example","manager")

Assign Assumption

WS-BPEL requires that for a copy operation to be valid, the data referred to by the from-spec and the to-spec MUST be of compatible types. Therefore, make sure that when you rename an element, the new name refers to a type that is compatible with the target variable. In other words, it should be of a substitutable (essentially stronger) complex type.

split-to-elements

It is impossible to split a given string into a sequence of elements using assignments. The only possible alternative is XSL, which has a lot of complexity for a very simple usage pattern. The ode:splitToElements function splits a given string (that can be a variable reference) into several elements by using specific separators. Here is an example:

<assign>
    <from>ode:split-to-elements($authorizeMessage.credential/userList, ',', 'user')</from>
    <to>$authorizedUsers</to>
</assign>

If the source element contains a list like "joe, paul, fred" the target variable will be assigned the sequence of elements:

<user>joe</user>
<user>paul</user>
<user>fred</user>

Alternatively this function can take a fourth parameter that would be the namespace of the elements used to wrap the split strings:

ode:split-to-elements(stringToSplit, separator, targetElement, targetNamespace)

Note

This function was formerly known as splitToElements, which can still be used, but is deprecated.

combine-url(base, relative)

Takes the relative URL and combines it with the base URL to return a new absolute URL. If the relative parameter is an absolute URL, returns it instead. This function is similar to func-resolve-uri (http://www.w3.org/TR/2004/WD-xpath-functions-20040723/#func-resolve-uri). However the latter is available in XPath 2.0 only.

compose-url(template, [name, value]*)

compose-url(template, pairs)

Expands the template URL by substituting place holders in the template; for example, ('/order/{id}', 'id', 5) returns '/order/5'. Substitute values are either name/value pairs passed as separate parameters, or a node-set returning elements with name mapping to value. The functions apply proper encoding to the mapped values. Undefined variables are replaced with an empty string. This function returns a URL. Also refer to URI Template spec (http://code.google.com/p/uri-templates).

expand-template(template, [name, value]*)

expand-template(template, pairs)

Similar to "composeURL" but undefined variables are not replaced with an empty string. They are ignored. As a result, with incomplete mapping, a new URL template may be returned.

dom-to-string

This is a function that serialises a DOM node (specified by the $node argument in the signature below) into a string.

ode:dom-to-string($nodeas node())as xs:string

process-property

<To be added>

This is a function that allows you to retrieve the value of a property defined in deploy.xml for the current process, with the given name (specified by the $name argument in the signature below, which is either a QName, String, Element or Single-Valued List).

ode:process-property($nameas item())as node()

Basically, this method gives you a way to reference properties, defined in deploy.xml for a given process, directly in the BPEL code for that process. The $name argument refers to any schema item that resolves to a QName. The return value is the child node of the property element with the given name.

Example usage in the context of an assign activity:

<assign>
   <copy>
       <from>ode:process-property("auctionEpr")</from>
       <topartnerLink="partnerLink"/>
   </copy>
</assign>

The property called "epr" is defined in the corresponding deploy.xml as follows:

<deployxmlns="http://www.apache.org/ode/schemas/dd/2007/03"xmlns:tns="http://ode/bpel/process">
   <processname="tns:negotiate">
      <propertyname="auctionEpr">
         <sref:service-refxmlns:sref=" http://docs.oasis-open.org/wsbpel/2.0/serviceref"xmlns:addr="http://example.com/addressing"xmlns:as="http://example.com/auction/wsdl/auctionService/">
             <addr:EndpointReference>
                <addr:Address>http://example.com/auction/RegistrationService&lt;/addr:Address>
                <addr:ServiceName>as:RegistrationService</addr:ServiceName>
             </addr:EndpointReference>
         </sref:service-ref>
      </property>...
   </process>
</deploy>


com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.