10 Using XPath Functions
This chapter describes how to use XPath functions when modeling orders in Oracle Communications Order and Service Management (OSM).
About XPath Functions
The XPath language provides for a core library of functions that deal with:
-
node sets
-
strings
-
Booleans
-
numbers
The following are some examples of XPath functions:
-
Determine the number of articles written by Mr. Jones:
count(/journal/article[author/last="Jones"])
-
Find all authors whose last name begins with Mc:
/journal/article[starts-with(author/last,"Mc")]
In addition to the core XPath functions defined by the XPath standard, a number of extended functions are also supported with OSM. These extended functions provide additional functionality that is useful to create behaviors, but does not conform to the XPath standard.
Note:
OSM supports XPath 1.0.
The XPath function library is divided into four groups, each of which is described in more detail, below:
-
Node set functions - for working with node-sets, either the implicit current node set or one passed as a parameter.
-
String functions: For working with strings and include type coercions.
-
Boolean functions: For working with Booleans, including type coercions.
-
Number functions: For working with numbers, including type coercions.
Node Set Functions
The following describes the Node Set functions.
number last()
Returns the index of the last item of the current node set.
Example - /journal/article[last()]
number position()
Returns the index of the current item in the current node set.
Example - /journal/article[position()<3]
number count(node-set)
Returns the number of items in the argument node set.
Example - count(/journal/article)
node-set id(object)
Returns the elements with the ID specified.
Example - id("article.1")/author/last
string local-name(node-set?)
Returns the non-namespace portion of the node name of either a node set passed as a parameter or the current node in the current node set.
Example - local-name(/wj:journal)
Example - /journal/*[local-name()= "article"]
string namespace-uri(node-set?)
Returns the namespace URI of the node name of either a node set passed as a parameter or the current node in the current node set.
Example - namespace-uri(/wj:journal)
Example - /journal/*:*[namespace-uri()="http://werken.com/werken-journal/"]
string name(node-set?)
Returns the complete textual node name of either a node set passed as a parameter or the current node in the current node set.
Example - name(/journal)
Example - [name()="soap:Envelope"]
node-set evaluate(string)
Returns the node set resulting from the Xpath expression defined by the provided argument. Allows XPath expressions to be dynamically created. The argument is converted to a string as if by a call to the string function.
Example - evaluate('/GetOrder.Response/*')
node-set match(node-set, string)
Returns the node set that matches a regular expression pattern.
Example - match('GetOrder.Response/*, 'blur[f]+le[0-9]')
node-set instance(string)
Returns the content of the named XML instance.
Note:
This function is only available to XPath expressions within behaviors.
The argument is converted to a string as if by a call to the string function. This string, along with the user's preferred language is matched against instance elements that are within scope of the containing document. If a match is located this function returns a node-set containing the content of the root element node (also called the document element node) of the referenced instance data. In all other cases, an exception is thrown and an error is displayed.
Example: For instance data corresponding to the following XML:
<instance name="order_form" lang="en" xsi:type="inlineInstanceType"> <orderForm> <shipTo> <firstName>John</firstName> </shipTo> </orderForm> </instance>
The following expression selects the firstName node (assuming the logged-in the user's preferred language is English, or that English is the default system language).
Note:
The instance function returns an element node, effectively replacing the left most location step from the path:
instance('order_form')/shipTo/firstName
String Functions
The following describes the String functions.
string string(object?)
Converts an object (possibly the current context node) to its string value.
Example - /journal/article/author[string()='Jones']
string concat(string, string, string*)
Concatenates two or more strings together.
Example - concat(author/salutation, ' ', author/last)
string starts-with(string, string)
Determines if the first argument starts with the second argument string.
Example - /journal/article[starts-with(title, 'Advanced')]
string contains(string, string)
Determines if the first argument contains the second argument string.
Example - /journal/article[contains(title, 'XPath')]
string substring-before(string, string)
Retrieves the substring of the first argument that occurs before the first occurrence of the second argument string.
Example - substring-before(/journal/article[1]/date, '/')
string substring-after(string, string)
Retrieves the substring of the first argument that occurs after the first occurrence of the second argument string.
Example - substring-after(/journal/article[1]/date, '/')
string substring(string, number, number?)
Retrieves the substring of the first argument starting at the index of the second number argument, for the length of the optional third argument.
Example - substring('Jones', 3)
number string-length(string?)
Determines the length of a string, or the current context node coerced to a string.
Example - /journal/article[string-length(author/last) > 9]
string normalize-space(string?)
Retrieves the string argument or context node with all space normalized, trimming white space from the ends and compressing consecutive white space elements to a single space.
Example - normalize-space(/journal/article[1]/content)
string translate(string, string, string)
Retrieves the first string argument augmented so that characters that occur in the second string argument are replaced by the character from the third argument in the same position.
Example - translate('bob', 'abc', 'ZXY')='XoX'
string lower-case(string?)
Retrieves the string argument or context node with all characters converted to lower case.
Example - lower-case('Foo')='foo'
string upper-case(string?)
Retrieves the string argument or context node with all characters converted to upper case.
Example - upper-case('Foo')='FOO'
Boolean Functions
The following describes the Boolean functions.
Boolean boolean(object)
Converts the argument to a Boolean value.
Example - boolean(/journal/article/author/last[.='Jones'])
Boolean not(boolean)
Negates the boolean value.
Example - not(/journal/article/author/last[.='Jones'])
Boolean boolean-from-string(string)
Returns true if the required parameter string is true, 1,
or Yes
. In all other conditions, false is returned.
Example - boolean-from-string(../pay_entire_amount)
Number Functions
The following describes the Number functions.
number number(object?)
Converts the argument or context node to a number value.
Example - /journal[number(year)=2003]
number floor(number)
Returns the largest integer that is not greater than the number argument.
Example - floor(100.5)=100
number ceiling(number)
Returns the smallest integer that is not less than the number argument.
Example - ceiling(100.5)=101
number avg(node-set)
Returns the arithmetic average of the string-values conversion of each node in the argument node-set to a number. The sum is computed with sum()
, and divided with div()
by the value computed with count()
. If the parameter is an empty node-set, the return value is NaN.
Example - avg(/journal/article/author/age)
number min(node-set)
Returns the minimum value that results from converting the string-values of each node in argument node-set to a number. The minimum is determined with the < operator. If the parameter is an empty node-set, or if any of the nodes evaluate to NaN, the return value is NaN.
Example - min(/journal/article/author/age)
number max(node-set)
Returns the maximum value that results from converting the string-values of each node in argument node-set to a number. The maximum is determined with the < operator. If the parameter is an empty node-set, or if any of the nodes evaluate to NaN, the return value is NaN.
Example - max(/journal/article/author/age)
XPath 1.0 Reference
Complete XPath reference information is available at the World Wide Web Consortium website (http://www.w3.org/TR/xpath/
). The abbreviated XPath highlights below are reproduced with permission from Mulberry Technologies, Inc. http://www.mulberrytech.com
Axis Specifiers [XPath §2.2]
ancestor:: ancestor-or-self:: attribute:: child:: descendant:: descendant-or-self:: following:: following-sibling:: namespace:: parent:: preceding:: preceding-sibling:: self::
Node Tests [XPath §2.]
name node()prefix:name text()* comment()prefix:* processing-instruction() processing-instruction(literal)
Abbreviated Syntax for Location Paths
Table 10-1 Abbreviated Syntax for Location Paths
Abbreviation | Syntax |
---|---|
(nothing) |
child:: |
@ |
attribute:: |
// |
/descendant-or-self::node()/ |
. |
self::node() |
.. |
parent::node() |
/ |
Node tree root |
Object Types [§11.1, XPath §1]
Table 10-2 Object Types
Type | Values |
---|---|
boolean |
True or False |
number |
Floating-point number |
string |
UCS characters |
node-set |
Set of nodes selected by a path |
XPath Core Function Library
XPath core functions:
Node Set Functions [XPath §4.1]
number last() number position() number count(node-set) node-set id(object) string local-name(node-set?) string namespace-uri(node-set?) string name(node-set?)
String Functions [XPath §4.2]
string string(object?) string concat(string, string, string*) string starts-with(string, string) string contains(string, string) string substring-before(string, string) string substring-after(string, string) string substring(string, number, number?) number string-length(string?) string normalize-space(string?) string translate(string, string, string)
Boolean Functions [XPath §4.3]
boolean boolean(object) boolean not(boolean) boolean true() boolean false()
OSM Behavior XPath Functions
OSM Behavior XPath Functions:
Node Set Functions
string matrix-concat(node-set,node-set,node-set?) node-set evaluate(string) node-set instance(string?) [Declarative Rules Only] node-set match(node-set?, string)
String Functions
string lower-case(string?) string upper-case(string?) string ends-with(string, string)