11 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:

  1. Node set functions - for working with node-sets, either the implicit current node set or one passed as a parameter.

  2. String functions: For working with strings and include type coercions.

  3. Boolean functions: For working with Booleans, including type coercions.

  4. 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'

string ends-with(string, string)

Determines if the first argument ends with the second argument string.

Example - /journal/article[ends-with(title, 'Advanced')]

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 true()

The Boolean value is true.

Boolean false()

The Boolean value is false.

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)

object if(boolean,object,object)

Evaluates the first parameter as a Boolean, returning the second parameter when true, otherwise the third parameter.

Example - if(/journal/article/author/last[.='Jones'],'Match found','No match')

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 sum(node-set)

Sums the node set value.

Example - sum(/journal/article/author/age)

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 round(number)

Rounds the number argument.

Example - ceiling(100.3)=100

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)

number count-not-empty(node-set)

Returns the number of non-empty nodes in argument node-set. A node is considered non-empty if it is convertible into a string with a greater-than zero length.

Example - count-not-empty(/journal/article/author/middle)

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

Location Paths [XPath §2]

Optional '/', zero or more location steps, separated by '/'

Location Paths [XPath §2.1]

Axis specifier, node test, zero or more predicates

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 11-1 Abbreviated Syntax for Location Paths

Abbreviation Syntax

(nothing)

child::

@

attribute::

//

/descendant-or-self::node()/

.

self::node()

..

parent::node()

/

Node tree root

Predicate [XPath §2.4]

[expr]

Variable Reference [XPath §3.7]

$qname

XPath

http://www.w3.org/TR/xpath

XPath Operators

Parentheses may be used for grouping.

Node-sets [XPath §3.3]

| [expr] / //

Booleans [XPath §3.4]

<=, <, >=, >=, != and or

Numbers [XPath §3.5]

-expr *, div, mod +, -

Node Types [XPath §5]

Root	            Processing Instructions	
Element         Comment
Attribute       Test
Namesspace

Object Types [§11.1, XPath §1]

Table 11-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()
Number Functions [XPath §4.4]
number number(object?)
number sum(node-set)
number floor(number)
number ceiling(number)
number round(number)

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)
Boolean Functions
boolean boolean-from-string(string)
object if(boolean, object, object)
Number Functions
number avg(node-set)
number min(node-set)
number max(node-set)
number count-not-empty(node-set)