iWay Service Manager Component Reference Guide > Available Services > XQuery Expression Evaluation (com.ibi.agents.XDXQueryAgent)

XQuery Expression Evaluation (com.ibi.agents.XDXQueryAgent)

Topics:

Syntax:

com.ibi.agents.XDXQueryAgent

iIT Service Object:

misc: XQuery Agent

Description:

The XDXQueryAgent is used to evaluate an XQuery 1.0 expression against the incoming document. The results are available in an outgoing document. XQuery can be used to select portions of the document or to transform the document as a whole.

XQuery is a query and functional programming language that is designed to query collections of XML data. XQuery 1.0 was developed by the XML Query working group of the W3C. The work was closely coordinated with the development of XSLT 2.0 by the XSL Working Group. The two groups shared responsibility for XPath 2.0, which is a subset of XQuery 1.0.

Parameters:

Parameter

Description

XQuery Expression

The XQuery expression to evaluate. To put the expression in a file, you can use _file().

Evaluate Expression

When true, the XQuery Expression is evaluated by iFL to return the actual XQuery expression to use. The default is to take the XQuery expression as is, which simplifies quoting considerably.

Return

Determines how to return the result sequence in the output document. The following are examples:

  • Select value to return the value of each result sequence item in a flat document.
  • Select markup to return the serialization of each result sequence item in a flat document.
  • Select root to return the Element or Document in the first result sequence item as the root of a tree document.
  • Select wrap to return a tree where each result sequence item appears under an item element.

Minimum Occurrence

Minimum number of items in result sequence, otherwise return the edge fail_empty.

Include All Items

Determines if all items in the result sequence are part of the return document, otherwise only the first item is included.

Separator

The separator to insert between result sequence items when returning a flat document. The default is no separator.

Edges:

The following table lists the available line edges for the XQuery Expression Evaluation (com.ibi.agents.XDXQueryAgent).

Line Edge

Description

OnError

Error

OnSuccess

Success

OnFailure

Failure

OnCustom
  • OnError
  • OnSuccess
  • OnFailure
  • fail_parse: The parameters are incorrect. This includes syntax errors in the XQuery expression or missing a value for an external variable. The output document is an error status document.
  • fail_operation: Failed for another cause. The output document is an error status document.
  • fail_empty: The application indicated that it requires at least one item in the result sequence but the result sequence was empty. The output document is an error status document.

When the Evaluate Expression parameter is false, the XQuery Expression parameter contains the actual XQuery Expression. For example: 

//elem[@attr="1"]

When the Evaluate Expression parameter is true, the XQuery Expression parameter contains an iFL expression that is evaluated to obtain the actual XQuery Expression to use.

The following example is similar to the previous expression except the value to match against the attr attribute now depends on the special register, reg1: 

_concat("//elem[@attr=\"",sreg(reg1),"\"]")

Another example is to use the function _file() to read the XQuery expression from a file.

If the XQuery Expression cannot be parsed by the XQJ implementation, the agent returns an error status document and it follows the fail_parse edge.

The returned value of an XQuery expression is always a result sequence. The Return parameter determines how the result sequence is stored in the output document. Selecting value or markup will return a string in a flat document. Selecting root or markup will return a parsed XML tree.

Consider the input document <root><elem>e1</elem></root> and the XQuery Expression /root/elem. The following table shows the effect of the Return parameter.

Return Parameter

Return Parameter

Output Document

Output Document Value

value

flat

"e1"

markup

flat

"<elem>e1</elem>"

root

tree

<elem>e1</elem>

wrap

tree

<XQueryResult><item><elem>e1</elem></item></XQueryResult>

The root option can only return the first item in the result sequence. That item must be an element or a document. If the element inherits XML declarations from its ancestors, those XML Namespace declarations will be added directly to the element.

The wrap option can return zero or more items. The intermediate <item> element makes it possible to return any node, including attributes. The XQueryResult Element will have exactly the same number of item sub-elements as there are items in the result sequence. The order sequence will be preserved, including returned attributes. When a returned item is an element that inherits XML declarations from its ancestors, those XML Namespace declarations will be added directly to the element. When a returned item is an attribute in a namespace, the XML namespace declaration will be added to the enclosing item Element.

The Minimum Occurrence parameter is useful to reject empty results. When the application requires a value, it can set the Minimum Occurrence parameter to 1. If the result sequence is empty, the agent returns an error status document and it follows the fail_empty edge.

The Include All Items parameter determines if all items in the result sequence are part of the return document, otherwise only the first item is included. When all items are returned in a tree document, they must always be copied in case two items would overlap. When a single item is required in a tree document, the returned node can often be reparented instead.

The Separator parameter can be used to separate the values when Include All Items is true and the return document is a flat String. For example, if the separator is |, the expression is //e, the return selection is value and the input document is: 

<root><e>1</e><e>2</e><e><3></e></root>,

then the output string will be "1|2|3". Without the separator, the output would be "123".

External Variables

An XQuery expression can declare variables to be external. For example, the following expression declares two external variables, $v1 and $ns:v2. 

declare namespace ns="http://ns";
declare variable $v1 external;
declare variable $ns:v2 external;
<root><elem1>{$v1}</elem1><elem2>{$ns:v2}</elem2></root>

These variables must be given a value from the environment. The XDXQueryAgent accomplishes this with the help of User Defined Properties. The name of the User Property is related to the external variable name in the following way:

  • If the external variable is not in a namespace, then the User Property name is the external variable name.
  • If the external variable is in a namespace, then the User Property name follows the pattern {nsuri}localname. The nsuri is the namespace URI that is obtained by expanding the namespace prefix in the external variable name. This convention eliminates the need for namespace declarations in the parameters since the URI is used instead.

For example, the $v1 variable above is not in a namespace, therefore the corresponding User Property is v1. The $ns:v2 variable above is in the namespace http://ns, therefore, the corresponding User Property is {http://ns}v2.

The User Properties can be given a value in iIT Designer. First, create a Service Object for XDXQueryAgent.

Click Next twice and enter the agent parameters.

Click Next to display the User Properties. Click the label Click here to add to add the User Properties one at a time.

Click Finish to create the Service Object.

The User Properties can be modified after the object is created. Double-click on the Service Object and select the User Defined Properties tab.

Click OK to save the changes.

Recall the XQuery expression presented earlier. If that expression is evaluated with the User Properties shown, the result will be: 

<root><elem1>one</elem1><elem2>two</elem2></root>

If an external variable does not have a corresponding User Property, the agent returns an error status document and it follows the fail_parse edge instead.

XQuery Implementation

The evaluation engine is provided by a third-party XQJ implementation. By default, the agent is configured to call SaxonHE (Home Edition). The default can be modified by assigning a class name to the Java system property javax.xml.xquery.XQDataSource. The class specified must implement the XQDataSource interface. For example, this call to the java interpreter assigns the same XQDataSource as the default: 

java -Djavax.xml.xquery.XQDataSource=net.sf.saxon.xqj.SaxonXQDataSource