Custom output functions

Custom output functions are provided to allow you to specify the entity/attribute mapping. Each of these functions requires an XPath expression (xPathExpn) that is relative to the trigger expression or to each other. These combined XPath expressions describe a nodeset upon which some action is taken.

If an XPath expression fails to match, the output attribute is set by using the default initializer for the type (0 for numeric, empty for strings and lists).

If an output expression for an SPL attribute does not reference the XPath, XPathList, or XPathMap expression, then the expression is resolved from the input stream and SPL logic state variables as usual (for example, x in the output clause).


output O : a = XPath("a/text()"), b = x + 5;

If an SPL attribute in the output stream is not assigned, then it is assigned using a default XPath or XPathList expression that uses the implicit Xpath mechanism.

Note: While the typical behavior of an operator is to try to satisfy an unassigned output parameter from an attribute of the same name in an input stream, the XMLParse operator tries to satisfy the output attribute from an element of the same name in the XML.

rstring XPath(rstring xPathExpn)

splAttribute = XPath(xPathExpn) is used to extract a scalar value from a nodeset containing a single node.

For the following XML (where q can contain only one b):


<q>
   <b>value</b>
</q>

The text content of the b element is read into the b attribute of the SPL tuple:


stream<rstring b> O = XMLParse(...){ param trigger : "/q";

Using:


output O : b = XPath ("b/text()");

The XPath expression "b/text()" is used to get the text content of the /q/b element. The assumption of this function is that there is a single node in the nodeset specified by XPath expression "/q/b". If there is more than one node in the nodeset, the value of the last node is be used in the assignment. To extract multiple values, use XPathList().

If the type of splAttribute is not rstring, a cast must be used to ensure the correct type:


stream<int32 b> O = XMLParse(...){ param trigger : "/q";
output O : b = (int32) XPath("b/text()") ...

<tuple T> XPath(rstring xPathExpn, T tupleLiteral)

splAttribute = XPath(xPathExpn, tupleLiteral) is used to extract a nested tuple value from a nodeset containing a single node. This function is necessary to address the nested tuple attributes.

For the following XML:


<q>
   <a>
      <b>value</b>
      <c fred="hi"/>
 </a>
</q>

The text content of the b element is read into the b attribute of the SPL tuple:


stream<tuple <rstring b, rstring c> a> O = XMLParse(...){ param trigger : "/q";

Using:


output O : a= XPath ("a", { b = XPath("b/text()", c = XPath("c/@fred") } );

The XPath expression "a" is used to get the content of the /q/a element. In this example, b is set from "/q/a/b/text()", and c from "/q/a/c/@fred". This form allows the XMLParse operator to know that the nested tuple is complete when /q/a is complete.

list<rstring> XPathList(rstring xPathExpn)

splAttribute = XPathList(xPathExpn) is used to extract a list of scalars from XML. xPathExpn determines the nodeset for this list of values. The nodeset described by the XPath expression contains one or more nodes from which the values are extracted and returned as a list.

For the following XML:


<a>
   <b>text1</b>
   <b>text2</b>
</a>

The text content is read into an SPL tuple:


stream<list<rstring> b> O = XMLParse(...) { param trigger : "/a";

Using:


output O : b = XPathList ("b/text()");

A cast may need to be added to ensure the correct type:


stream<list<int32> b> O = XMLParse(...) { param trigger : "/a";
output O : b = (list<int32>) XPathList ("b/text()");

<any T> list<T> XPathList(rstring xPathExpn, T elements)

splAttribute = XPathList(xPathExpn, elements) is used to extract a list of objects from XML. In this function, the xPathExpn serves two purposes: it defines a nodeset upon which the expression in elements is applied and it is a sub-trigger. The elements expression applies XPath and XPathList custom output functions on the node set given by /trigger/xPathExpn.

For the following XML:


<x>
   <a>
      <b>text1</b>
      <b>text2</b>
   </a>
   <a>
      <b>text3</b>
   </a>
</x>

The text content is read into an SPL list<list<rstring>>:


stream<list<list<rstring>> b> O = XMLParse(...){ param trigger : "/x";

Using:


output O : b = XPathList ("a", XPathList("b/text()"));

A list of lists is built where there is one outer list entry for each element a in x and each outer list entry has a list of each b value in the containing x/a. The "a" XPath expression in the outer XPathList defines the set of nodes /x/a and triggers an entry in the outer list for each node. The inner expression extracts the values from the nodeset /x/a/b. With nested XPath and XPathList functions, the XPath expressions concatenate, giving an absolute XPath expression starting with the expression specified in the trigger parameter.

In other words, this XPathList function returns a list where each entry in the list contains the value(s) returned by the value expression.

If the type of splAttribute is not list<list<rstring>>, a cast must be used to ensure the correct type:


stream<list<list<int32>> b> O = XMLParse(...){ param trigger : "/x"; 
output O : b = XPathList("a", (list<int32>)XPathList("b/text()")) ...

The value expression argument can be a nested tuple initializer which itself contains nested XPath or XPathList functions. For the following XML:


<x>
   <a>
      <b>text1</b>
      <c>text2</c>
   </a>
   <a>
      <b>text3</b>
      <c>text2</c>
   </a>
</x>

The text content is read into an SPL list<tuple<rstring b, rstring c>> a>:


stream<list<tuple<rstring b, rstring c>> a> O = XMLParse(...){ param trigger : "/x";

Using:


output O : a = XPathList ("a", { b = XPath ("b/text()"), c = XPath("c/text()" });

If the type of splAttribute is list<tuple<rstring b, int32 c>> a>, a cast must be used to ensure the correct type:


stream<list<tuple<rstring b, int32 c>> a> O = XMLParse(...){ param trigger : "/x";
output O : a = XPathList ("a", { b = XPath ("b/text()"), 
                                 c = (int32) XPath("c/text()" }) ...

map<rstring,rstring> XPathMap(rstring xPathExpn)

splAttribute = XPathMap(xPathExpn) is used to extract a map of SPL attributes. The type of the SPL attribute must be map<rstring, rstring>. xPathExpn must only reference one or more attributes. These can be @name, or @*. @* adds all attributes to the map.

For example:


stream<map<rstring,rstring> manyAttrs> O = XMLParse(...) { param trigger: "/x";
output O : manyAttrs = XPathMap ("b/@*|c/@c");

manyAttrs is set to the union of all the attributes of /x/b/@* and /x/c/@c.