IWXPATH Language Support

XPATH Language support is an important feature of iWay and is used in a number of areas within iWay Service Manager (iSM). XPATH is a non-procedural language used to access and manipulate sections of an XML document. The XPATH expression gathers information from the document, as if the XML document is a self-contained hierarchical database. The XPATH expression specifies levels (segments or fields), filter predicates, and functions on the XML document data. The result of the iwxpath can be one or more values, a set of XML nodes, or a particular location in the XML structure. Using these XPATH results, iSM can control the behavior of services (agents), conditional routing, and decision making inside of process flows. The fast iwxpath() function that is provided by iSM implements a subset of the XPATH location steps, predicates, and functions, which are expressed using abbreviated syntax.

The iwxpath() function is not intended to be a full implementation of the XPATH specification, but rather a very fast subset offering commonly used Xpath() searches. If additional functionality is required, iSM offers full Xpath() using the Xpath1() function. You can configure iSM to have the default xpath() function use iwxpath() if required.

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 node-set. In general, XPATH phrase support of iSM 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.

Steps

/<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 node-set).

/..

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

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 node-set.

Multiple predicates are written as sequential predicate terms: /x[p1][2]... applied left to right, with the predicate affecting the node-set as returned by the prior predicate. In essence, the predicates used by AND.

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 node-set that are the nth child of their parent.

last()

Selects the members of the node-set 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 node-set returned is used to select the members of the incoming node-set 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 node-set with children of the specified name. The test will be on the value of the children in the node-set.

@<attname>

Operate on nodes in the node-set with attributes of the specified name. The test will be on the value of the attribute in the node-set.

*

Operate on all nodes in the node-set with children of any name.

@*

Operate on all nodes in the node-set 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 node-set.

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] indicate that the function optionally operates on a node-set. For example, the localname() function returns the local name of either the current node being tested, or that of the first node in the node-set 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 the node-set returned from the xpath parameter. The xpath of the count() function 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.

Arithmetic

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.

Final Functions

A set of final functions are supported to operate on the node-set 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 node-set. 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 node-set. Example //sql/*/name() returns the names of the grandchildren of each sql node.

position()

The position of each node in the node-set relative to its parent.

count()

The number of children of each node in the node-set.

text()

Returns the value of each node in the node-set.

localname()

Returns the local name of each node in the node-set.

namespace-uri()

Returns the namespace uri of each node in the node-set.

/<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 node-set).
/..	Step up one level, selecting the parent of each node in the node-set.

Number, such as 3	Selects the members of the node-set that are the nth child of their parent.
last()	Selects the members of the node-set 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 node-set returned is used to select the members of the incoming node-set 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'))]

<name>	Operate on nodes in the node-set with children of the specified name. The test will be on the value of the children in the node-set.
@<attname>	Operate on nodes in the node-set with attributes of the specified name. The test will be on the value of the attribute in the node-set.
*	Operate on all nodes in the node-set with children of any name.
@*	Operate on all nodes in the node-set 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 node-set. 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] indicate that the function optionally operates on a node-set. For example, the localname() function returns the local name of either the current node being tested, or that of the first node in the node-set located by the xpath expression represented in the ns parameter.

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 the node-set returned from the xpath parameter. The xpath of the count() function 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.

name()	Returns the name of the nodes in the selected node-set. Example //sql/*/name() returns the names of the grandchildren of each sql node.
position()	The position of each node in the node-set relative to its parent.
count()	The number of children of each node in the node-set.
text()	Returns the value of each node in the node-set.
localname()	Returns the local name of each node in the node-set.
namespace-uri()	Returns the namespace uri of each node in the node-set.