In this section: |
XPATH is a language used to "step into" an XML document, eventually locating one or more points in the document. Uses of XPATH in systems vary; iSM uses XPATH to select values from the target document for testing as part of its conditional routing capability, both at the exit level and in the Adapter Designer switch and test nodes. iWay's XPATH language is oriented directly to this use; it is not intended to be a full XPATH suitable for use in, say, XSL.
The language always returns a string suitable for use in configuring other components. It is most suitable for locating element values and attributes. When multiple values are selected, they are separated by a vertical bar |, and empty values are denoted by &.
The XPATH statement used to step into an XML document is known as a phrase. Phrases support both steps used to descend into the document and predicates used to determine how the step is to be applied. Currently selected XML nodes are called the nodeset. In general, iAM's XPATH phrase support is based on the formal XPATH specification section 2.5, "abbreviated syntax." The specification is available at http://www.w3.org/TR/xpath.
In IWXPATH the node context is always the root of the document; as such only the child axis is implemented.
iSM's XPATH phrase support is as follows:
|
/<name> |
Step down one level selecting children of the specified name. |
|
//<name> |
Step down, selecting children of the specified name regardless of the level. |
|
/* |
Step down, selecting all children. |
|
//* |
Step down, selecting all children. |
|
/. |
Select all nodes already selected (used to apply predicates to the current nodeset). |
|
/.. |
Step up one level, selecting the parent of each node in the node set. |
These step specifications are fully covered in the appropriate RFC for XPATH, section 2.5.
Predicates are written after the step, enclosed in square brackets. There can be one or more predicates in a step, each of which is applied left to right to control the membership of the nodeset.
Multiple predicates are written as sequential predicate terms: /x[p1][2]... applied left to right, with the predicate affecting he nodeset as returned by the prior predicate. In essence, this AND's the predicates.
Any single predicate can hold any number of terms, separated by AND or OR. Terms can be grouped in parenthesis. Each term consists of a single term or a relation of <left>op<right>. The specification calls for left to right binding, AND taking higher precedence. For example the predicate [a=b OR c=d AND e=f] is evaluated as [a=b OR (c=f AND e=f)].
Single term predicates such as /x[2] operate as an index into the node set so far.
Supported are:
|
Number such as 3 |
Selects the members of the nodeset that are the nth child of their parent. |
|
last() |
Selects the members of the nodeset that are the last child of their parent. |
|
count(parm) |
The parm must be an iWay XPATH expression. The expression is processed against the original document being evaluated from the root context. The number of elements in the nodeset returned is used to select the members of the incoming nodeset that are the nth child of their parent. |
|
sreg(name[,default])* |
The value of a named special register. |
|
starts-with(p1,p2) ends-with(p1,p2)* contains(p1,p2) |
Evaluates the incoming context, testing whether the name, attribute, or child values meet the p2 criterion. P1 can be name(), @attribute, @*any attribute or the name of the child. |
|
not(filter) |
Inverts the meaning of a selection filter. For example, /a//*[not(starts-with(name(),'d'))] |
Filter functions marked with * are iWay extensions to the XPATH specification.
Left terms can be:
|
<name> |
Operate on nodes in the nodeset with children of the specified name. The test will be on the value of the children in the nodeset. |
|
@<attname> |
Operate on nodes in the nodeset with attributes of the specified name. The test will be on the value of the attribute in the nodeset. |
|
* |
Operate on all nodes in the nodeset with children of any name. |
|
@* |
Operate on all nodes in the nodeset with attributes of any name. The test will be on the values of any attribute, such as selecting all nodes with any attribute of value "iway". |
|
<function>() |
One of a specified set of functions. count([ns]). Number of children of the selected node. last(). Position() of the last node in the nodeset. local-name([ns]). URI of the namespace within which the node exists. position(). The position of the selected node in the children of the parent. Functions shown with optional parameters [ns] inficate that the function optionally operates on a nodeset. For example, the localname() function returns the local name of either the current node being tested, or that of the first node in the nodeset located by the xpath expression represented in the ns parameter. |
Operators are the standard =, !=, <, <=, >, >=. Data is automatically case, such that if both the operators are numeric, a numeric comparison will be performed. Otherwise a character comparison will be performed.
The right term is a literal, which can be:
|
String literal enclosed in single or double quotes |
Example "IWAY" |
|
Value not in quotes, such as a number. Simple string values can be entered this way for convenience. |
Example 3 or xyz |
|
count(xpath) |
The function to return the number of nodes in thenodeset returned from the xpath parameter. The count() function's xpath examines the original document being processed, from the root node context. |
|
sreg(name[,default]) |
Value of the named special register, or the default value if the register is not defined. This is an iWay extension. |
|
Standard string function to build test |
Standard string functions concat, substring, substring-before, substring-after. |
Standard groupings are allowed. For example, the following specification is now legal in iSM.
//greet/*[*=hello or (@addr=fred@ibi.com or position()<3 and child1=audit)]
which selects all greet nodes with children having themselves children with the value "hello" or with attribute addr having the value of fred@ibi.com or those having both a position of one or two (first two children) and having a child with the node name child1 which has a value of "audit". This overly complicated example is intended to demonstrate how grouping is used.
Similarly, the expression /edxax/dest[position() = count(//sql)] selects the single dest node that matches in position the number of sql statements in the document.
Simple arithmetic is supported in predicates. Only plus and minus are supported. For example
//password[count(//user)+1]
returns the password tag value related to the number of user tags in the document.
A set of "final functions" are supported to operate on the nodeset being returned, such that the values from the XPATH operation reflect the value returned by the function rather than the values of the nodes in the nodeset. These functions are not strictly supported by the XPATH specification, but are included to further the use of XPATH in setting adapter parameters.
|
name() |
Returns the name of the nodes in the selected nodeset. Example //sql/*/name() returns the names of the grandchildren of each sql node. |
|
position() |
The position of each node in the nodeset relative to its parent. |
|
count() |
The number of children of each node in the nodeset. |
|
text() |
Returns the value of each node in the nodeset. |
|
local-name() |
Returns the local name of each node in the nodeset. |
|
namespace-uri() |
Returns the namespace uri of each node in the nodeset. |
The function Support Table denotes which functions are available in specific version of the server. If the function is not mentioned in this table, it is available in all Service Manager versions.
|
Function |
Support |
|---|---|
|
_attcnt(<parms>) |
iWay Service Manager, Version 6.0. The non-parameterized form is available in all SM editions. |
|
_atthdric() |
iWay Service Manager, Version 6.0. |
|
_ldap(...[,<provider>]) |
iWay Service Manager, Version 6.0. The non-provider version is available in all SM editions. |
|
_tpa(),_tpp(), _tpn(), _tpaw(), _tpid(), _tpt(), _tpah(), _tpr(), _tps(), _tpsql(), _tpxmlsql() |
iWay Trading Partner Manager. The description this function is found in the documentation for that product. |
|
_xpath |
Full xpath is provided in iWay Service Manager Version 6.0. In other servers, only a limited xpath is supported (see _iwxpath) |
|
_iwxpath |
Supported in iWay Service Manager, Version 6.0 and iWay ISM servers of sp2 and above. |
|
math: modulus %, _mul, _div, _add, _sub |
Supported in iWay Service Manager iWay ISM servers of sp2 and above. Others support only plus and minus. |
|
_uuid, _printable, _inflate, _if, _intmask, |
iWay Service Manager, Version 6.0. |
|
_jdbc, _lock, _md5 | |
|
_property() |
Support for 'keep' is iWay Service Manager, Version 6.0 only. |
| iWay Software |