Document functions access information pertaining to the current document being processed.
The _isroot() function returns 'true' if the root of the current document matches the parameter. It uses the following format:
_isroot(name)
name | string | Name to be compared to the root element |
The _isroot() function is often used to drive a routing decision, such as _root('a') or _root('b') to cause the route to be selected for any document with a root of 'a' or 'b'.
The _root() function returns the root element name of the current document. It uses the following format:
_root()
This is equivalent to the _xpath function _xpath(/*/name()). It might be used in a routing decision, such as _cond(_root(),eqc,'a') which selects the route for documents with roots of 'a' or 'A'.
The current document can hold either XML or non-XML information. The _isxml function returns true if the current document holds XML. If the document has no contents, this function returns false. It uses the following format:
_isxml()
The current document can hold either XML or non-XML information. The _isflat function returns true if the current document holds non-XML. If the document has no contents, this function returns false. It uses the following format:
_isflat()
The current document can have errors posted to it by the system, or can be set into an error state by the actions of an application process. If the document is in error state, default replies are delivered to the configured error addresses, otherwise they are delivered to the configured reply addresses. The _iserror() function returns true if the document is in error state. It uses the following format:
_iserror()
_inflate(value , type)
value | string | The string inflate |
type | mnemonic | Type of input: “base64”, “string” |
The input is assumed to be a string version produced from a deflated message. How the string is created will depend on the input document, but can be expected to be either a base64 value or a string simply made from a byte array. Users are cautioned that if the input is in base64 format, do not attempt to use the _frombase64() function to preconvert the input to string. Doing so can result in loss of information.
The standard ZIP inflate algorithms are attempted, and if successful the result returned is the inflated string.
As the document passes through its execution route, a supplied rules-based validation system can be employed. Often the rules relate to eBusiness documents suchas SWIFT or EDI. If the rules system has posted a validation error to this document, the _hasruleerr() returns true. It uses the following format:
_hasruleerr()
During a document's life in the system, certain rules and services can detect schema violations. Whether such a violation has been detected can be tested with this function. A common use of this function is in a process flow test object. This function uses the following format:
_hasschemaerr()
The current document can hold either XML or non-XML information. This function returns true if the current document holds XML or holds flat information that can be parsed into XML. If it has not been parsed, a true response from this function assures that the message can be parsed into XML. It uses the following format:
_iswellformed()
Streamable input is used for handling large documents or documents for which the application desires to "split" the input into sections under the same transaction. Following the completion of the input stream handling, a "final pass" is made with a special document containing batch information:
<batch count='n'/>
The end of stream can also be tested with the_iseos() function. A common use of this function is in a process flow test object. This function uses the following format:
_iseos()
Creating a Process Flow to Test for an End of Stream Document
Splitting and streaming/splitting preparsers generate a special control document at the end of a batch to indicate that this batch was completely processed. This End of Stream document is a non-data XML document that is passed into a channel after all data documents. The _iseos() function will return as true if the current document contains an End of Stream message, else it will return as false. The End of Stream document may also contain additional statistics about the splitting process, such as how many iWay documents were generated from the batch.
To create a process flow using iWay Designer to test for an End of Stream document:
The new process flow should have a structure that resembles the example in the following image.
The new channel should have a structure that resembles the example in the following image.
<a> <b name="b1"> <c>value of input element a/b@name=b1/c is 1</c> <c>value of input element a/b@name=b1/c is 2</c> </b> <b name="b2"> <c>value of input element a/b@name=b2/c is 3</c> <c>value of input element a/b@name=b2/c is 4</c> </b> </a>
The _iseos() functions returns as true at the third (last) pass and a trace file is created which displays the End of Stream document.
The xpath() function is always an alias for one of the supported xpath functions: xpath1() or _iwxpath(). By default, xpath() is an alias for _iwxpath() but via compatibility flags it can be made to alias xpath1().
The _xpath() function uses the following format:
_xpath(expression [,nsmap [,object]])
The document is evaluated by the provided xpath expression. The start is always considered to be the root, so all expressions are assumed to begin with '/'.
The purpose of the xpath in the context of functions is to extract values from an input document to be used as configuration parameters. This use of xpath is not intended for general XML tree manipulation.
In some servers, xpath is a full xpath version 0 as specified by XML Xpath Language http://www.w3.org/TR/1999/REC-xpath-19991116, while others support only the portion of xpath specified in section 2.5, Abbreviated Syntax.
The _xpath1() function uses the following format:
_xpath1(expression [,nsmap [,object]])
expression | string | Expression in xpath language. |
nsmap | string | Name of a namespace map from a provider. If omitted, no namespace map is applied. |
object | document | A document to which xpath is applied. If omitted, the current document is evaluated. |
Note: In iWay Service Manager version 6.0.1 and lower, the _xpath() function has a single parameter, since namespaces are not supported.
The _xflat() function uses the following format:
_xflat(expression)
expression | string | Expression in xpath language. |
Note: In iWay Service Manager version 6.0.1 and lower, the _xflat() function has a single parameter, since namespaces are not supported.
The current document is evaluated by the provided xpath expression. As with xpath, the root of the current document is the "starting point". The sub tree addressed by this expression is returned in a flattened form suitable for reparsing.The parameters are as discussed under xpath(). This function is often used to provide "document segments" in the constant value service leading into a join. For example:
<a> <top> <b>one</b> <b>two</b> <x> <xroot> <xchild>rootchildvalue</xchild> </xroot> </x> </top> </a>
The expression _xflat(//xroot) yields the following subdocument:
<xroot> <xchild>rootchildvalue</xchild> </xroot>
The current document is flattened. If the current document is XML, the decl parameter determines whether an XML declaration will be included in the flattened output. The default is true. The _flatof() function uses the following format:
_flatof([decl])
decl | boolean | Is an XML declaration desired? |
Documents can hold attachments. This function has two forms. When used with no parameters, it returns the number of attachments associated with the document. When used with two parameters, it returns the index of the first attachment having the named header equal to the specified value. The _attcnt() function uses the following format:
_attcnt([name,value [,notfound]])
name | string | Name of an attachment header |
value | string | Value of the named header |
notfound | string | What to return if the named attachment header is not found |
The _atthdr() function returns the value of a specific header in the attachment. The IC (independent case) form tests the attachment header names in a case independent fashion. Number 0 is the first attachment. The _atthdr() function uses the following format:
_atthdr(index, name, default)
_atthdric(index, name, default)
index | integer | Index of the attachment, base 0 |
name | string | Name of the header desired |
default | string | Default if header not found |
When the _atthdr() function is used in a conditional expression in comparison against a string value, the default value must be specified.
For example, the following conditional expression would not compile, since it requires a default value in the expression:
COND(_atthdr(1,'mysample'),eq,'a')
Instead, the expression must be specified as follows:
COND(_atthdr(1,'mysample','defaultval'),eq,'a')
For example, to return the first header in the attachment, _atthdr(0,'mysample') could be used.
Returns the name of the terminate (end node) of the subflow through which the document reached the calling process flow. This allows the subflow to communicate information back to the parent flow.
Imagine a subflow that performs some operation that results in one of three possible situations: success or a failure caused by a security violation or a connection error.
The parent flow calls the subflow, and wishes to deal with the result from that flow. Within the subflow, the document that is produced is returned via a terminate or end node, as shown. The name of that terminate node becomes the edge name followed by the returned document. As this example shows, there are three activities (called do_<something>) in the outer flow, each of which handles the result returned from the inner subflow.
If the subflow returns multiple documents, each follows the edge of its own name. If more than one of any name is returned, the documents are associated as siblings, and can be split later using the sibling iterator. The source name can be used in a switch statement for more detailed routing.
_iwxpath(expression)
expression | string | Expression in xpath language |
The current document is evaluated by the provided xpath expression. The start is always considered to be the root, so all expressions are assumed to begin with '/'.
The purpose of the xpath in the context of functions is to extract values from an input document to be used as configuration parameters. This use of xpath is not intended for general XML tree manipulation.
The xpath language supported is specified in XML Xpath Language http://www.w3.org/TR/1999/REC-xpath-19991116, section 2.5, Abbreviated Syntax.
In those servers not providing full xpath support, both xpath and _iwxpath are identical. In other servers, it can be expected at _iwxpath should operate faster than full xpath. iWay recommends use of full xpath if _iwxpath does not provide the required services or results.
_xpath1(expression [,nsmap [,object]])
expression | string | Expression in xpath language |
nsmap | string | Name of a namespace map from a provider. If omitted, no namespace map is applied. |
object | document | A document to which xpath is applied. If omitted, the current document is evaluated. |
The purpose of the xpath in the context of functions is to extract values from an input document to be used as configuration parameters. This use of xpath is not intended for general XML tree manipulation.
The nsmap is the name of a namespace provider. Namespace providers relate the namespace portion of the xpath expression to the URI to which it relates. The xpath execution engine will map the URI to the namespace tokens used in the document being evaluated.
If the object parameter is omitted, the xpath is applied against the current document. Otherwise this must be the name of a special register holding a document or a register itself holding a document.
In some servers, xpath is a full xpath version 1 as specified by XML Xpath Language http://www.w3.org/TR/1999/REC-xpath-19991116, while others support only the portion of xpath specified in section 2.5, Abbreviated Syntax. iWay 6.0 supports full XPATH per the specification.
In some cases, XPATH syntax can be confusing. Consider a document in a default namespace:
<root xmlns='http://someuri.com'> <child name='whoami'/> </root>
A request for the child name would appear to be //child/@name, and if there were no default namespace, this would indeed work as expected. For the anonymous namespace, a solution is 1:
The default namespace throws in a twist. The XPath specification states the following:
A node test that is a QName is true if and only if the type of the node (see [5 Data Model]) is the principal node type and has an expanded-name equal to the expanded-name specified by the QName.
This means that an XPath processor does not deal with plain element names, except those element names for which no namespace has been declared. If there is any namespace declaration at all, including one for the default (unprefixed) namespace, the processor uses the expanded-name.
//*[namespace-uri()="http://someuri.com" and local-name()="child"]/@name
Alternatively, create a namespace provider name, for example, empty1. Add a specification for a namespace such as:
none | http://someuri.com |
Then use an _xpath statement such as the following:
_xpath(/none:root/none:child/@none:name,empty1)
The processor will map the 'none' namespace to the URI in the statement and select the proper nodes from the document.
XPATH Language support is an important feature of iWay and is used in a number of areas within the server. 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/fields), filter predicates, and functions on the XML document data. The result of the XPATH can be one or more values, a set of XML nodes, or a particular location in the XML structure. Using these XPATH results, iWay Service Manager can control the behavior of service agents, conditional routing, and decision-making inside of process flows. iWay Service Manager implements a subset of the XPATH location steps, predicates, and functions, which are expressed using abbreviated syntax. The fully proposed XPATH Language specification and information on the abbreviated syntax can be found at:
http://www.w3.org/TR/xpath.html
In iWay Service Manager, the node context from which location steps begin is always the root of the document. Furthermore, only the child axis is implemented and is implicit in all iWay XPATH location steps.
Expression (phrase) |
Action |
---|---|
/name |
Locate down one level, selecting children of the specified name. |
//name |
Locate down, selecting children of the specified name regardless of the depth. |
/* |
Locate down, selecting all children. |
//* |
Locate down, selecting all children. |
/. |
Locate all nodes that are already selected. |
/.. |
Locate upward one level, selecting the parent of each node in the node-set. |
The result of the location step phrase can be a set of XML document nodes consisting of zero, one, or many nodes. This set of nodes is referred to as a node-set. This node-set is provisional and may not be the final node-set returned by the XPATH expression, depending on subsequent predicates.
iWay supports two XPATH processors with different characteristics; selecting the right one for any specific situation can greatly improve the performance of an application.
_iwxpath(). This is an XPATH processor provided by iWay. It supports a limited subset of the XPATH language. If your document and query are appropriate to using _iwxpath, you can expect to achieve significant performance improvements. However, the limitations of this process are:
Very limited function support.
No advanced “XPATH” features such as math.
Surrounding functions such as count() are not supported.
Conjunctions (such as OR and AND) and complex tests are not supported.
Namespaces are not supported.
Note: For most applications, these omitted features are not used. If _iwxpath() does not return the results you desire, use _xpath1().
_xpath1(). This is the full XPATH. It may be slower for certain operations, but it does provide the complete language support of XPATH version 1.
_xpath(). This is the default xpath call. Whether it calls _iwxpath() or _xpath1() depends on a configuration setting on the iSM console.
In general, it is best practice to write your xpath expressions as simply as possible. Avoid expressions that may return multiple results when you are not expecting them. Select any (*) can slow down any XPATH processor, as can use of //. Use these language constructs if they are needed, but understand that there may be a penalty in performance.
Predicates are written after the location step, and are 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.
A predicate filters the node-set implied by a location step, to produce a new node-set. For each node in the node-set to be filtered, the predicates are evaluated with that node; if predicate expression evaluates to true for that node, the node is included in the new node-set; otherwise, it is not included.
Multiple predicates are written as sequential predicate terms and are applied left to right, behaving as if connected by a logical "AND":
/Book[Author='Smith'][Price<10]
Each predicate term consists of a single integer, a filter function or a relation of the form.
<left-value> operator <right-value>
A predicate can hold any number of terms, logically connected by AND and OR. The specification calls for left to right precedence, with AND taking higher precedence than OR. Terms may be grouped by parenthesis to force a particular order of evaluation. For example, the predicate [a=b OR c=d AND e=f] is evaluated as [a=b OR (c=d AND e=f)].
Integer predicates of the form /Tag[2] imply a numeric index into the current node-set (in this case, selecting the second node).
Symbol |
Description |
Example |
---|---|---|
= |
Equal |
//*[local-name(CustomerRecord/RecordDate)='OrderRecord'] |
!= |
Not Equal |
//*[local-name(CustomerRecord/RecordDate)!='OrderRecord'] |
< |
Less than |
/OrderRecord/LineItems[position() < 5] |
<= |
Less than or equal |
/OrderRecord/LineItems[position() <= 5] |
> |
Greater than |
/OrderRecord/LineItems[position() > 5] |
>= |
Greater than or equal |
/OrderRecord/LineItems[position() >= 5] |
Or |
Logical Or |
OrderRecord[salesman = 'Jones' or salesman='Scott] |
And |
Logical And |
OrderRecord[salesman = 'Jones' and salesman='Scott] |
Not |
Logical Not |
/a//*[not(starts-with(name(),'d'))] |
Expression |
Description |
---|---|
starts-with(string1, string2) |
Returns true if the first string starts with the second string, otherwise returns false. |
ends-with(string1, string2) |
Returns true if the first string ends with the second string, otherwise returns false. |
contains(string1, string2) |
Returns true if the first string is contained within the second string, otherwise returns false. |
In each of the preceding filter functions, string1 may be name(), @attribute, @* (all attributes) or the name of the child node.
A collection of functions is provided to operate on nodes and node-sets. A function operates on the current context (for example, the current node) or on characteristics of the current node-set, and returns a single value.
Function |
Description |
---|---|
count(<node-set>) |
Returns the number of nodes in the specified node set. |
last() |
Returns the position number of the last node in the context node-set. |
position() |
The position of a 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. Also used to return the value of CDATA. |
name() |
Returns the name of the nodes in the selected nodeset. Example //sql/*/name() returns the names of the grandchildren of each sql node. |
local-name |
Returns the local name of each node in the node set. |
sreg(name[,default]) |
The value of a named special register (iWay extension to XPATH). |
@attrib, @* |
Returns the values of the specified attribute, * returns the set of all attribute values. |
concat(string1, string2) |
Returns the concatenation of all its arguments.Two or more strings may be concatenated. |
Substring(string, position, length) |
Returns the substring of the first argument starting at the position specified in the second argument with length specified in the third argument. |
Substring-before(string1, string2) |
Returns the substring of string1 that precedes the first occurrence of string2 in string1, or the empty string if string1 does not contain string2. |
Substring-after(string1, string2) |
Returns the substring of string1 that follows the first occurrence of string2 in string1, or the empty string if string1 does not contain string2. |
namespace-uri() |
Returns the namespace uri of each node in the node set. |
iWay Software |