TIBCO EBX®
Documentation > Reference Manual > Integration
Navigation modeDocumentation > Reference Manual > Integration

Supported XPath syntax

Overview

The XPath notation used in TIBCO EBX® must conform to the abbreviated syntax of the XML Path Language (XPath) Version 1.0 standard, with certain restrictions. This document details the abbreviated syntax that is supported.

Example expressions

The general XPath expression is:

path[predicate]

Absolute path

/library/books/

Relative paths

./Author

../Title

Root and descendant paths

//books

Table paths with predicates

../../books/[author_id = 0101 and (publisher = 'harmattan')]

/library/books/[not(publisher = 'dumesnil')]

Complex predicates

starts-with(col3,'xxx') and ends-with(col3,'yyy') and osd:is-not-null(./col3))

contains(col3 ,'xxx') and ( not(col1=100) and date-greater-than(col2,'2007-12-30') )

Predicates with parameters

author_id = $param1 and publisher = $param2 where the parameters $param1 and $param2 refer respectively to 0101 and 'harmattan'

col1 < $param1 and col4 = $param2 where the parameters $param1 and $param2 refer respectively to 100 and 'true'

contains(col3,$param1) and date-greater-than(col2,$param2) where the parameters $param1 and $param2 refer respectively to 'xxx' and '2007-12-30'

Note

The use of this notation is restricted to the Java API since the parameter values can only be set by the method Request.setXPathParameter of the Java API.

Search predicate

  • Syntax: osd:search(fields, queryString[, templateKey])

  • Examples:

    • osd:search('col1', 'xxx')

    • osd:search('col1,col2','xxx')

    • osd:search('','xxx')

    • osd:search(col1,'xxx', myTemplate@myModule)

The osd:search function tries to match a term, or a list of terms, against the set of fields of the current table. This function is generic, handling every field datatype supported by EBX®. When no fields are specified, it searches against all fields for current table. For a more advanced usage, the query string supports specialized operators, see Special characters for more information.

For any concerned field, if a label exists, the search targets the label, rather than the value; however, this is not yet supported in some cases. See Limitations for more information.

The predicate osd:search is localized.

Note

The locale can be set by the methods of the Java API Request.setLocale orRequest.setSession .

Note

The identifier of a search template can be specified, to customize the behavior of the search.

Predicates for validation search

osd:has-validation-item()

osd:has-validation-item('error,info')

osd:contains-validation-message('xxx')

osd:contains-validation-message('xxx','info,warning')

Attention

To ensure that the search is performed on an up-to-date validation report, it is necessary to perform an explicit validation of the table just before using these predicates.

Syntax specifications for XPath expressions

Overview

Expression

Format

Example

XPath expression

<container path>[predicate]

/books[title='xxx']

<container path>

<absolute path> or <relative path>

<absolute path>

/a/b or //b

//books

<relative path>

../../b, ./b or b

../../books

Predicate specification

Expression

Format

Notes/Example

<predicate>

Example: A and (B or not(C)) A,B,C: <atomic expression>

Composition of: logical operators parentheses, not() and atomic expressions.

<atomic expression>

<path><comparator><criterion> or method(<path>,<criterion>)

royalty = 24.5

starts-with(title, 'Johnat')

booleanValue = true

<path>

<relative path> or osd:label(<relative path>)

Relative to the table that contains it:

../authorstitle

<comparator>

<boolean comparator>, <numeric comparator> or <string comparator>

<boolean comparator>

= or !=

<numeric comparator>

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

<string comparator>

=

<method>

<date method>, <string method>, osd:is-null method or osd:is-not-null method

<date, time & dateTime method>

date-less-than, date-equal or date-greater-than

<string method>

matches, starts-with, ends-with, contains, osd:is-empty, osd:is-not-empty, osd:is-empty-or-nil, osd:is-neither-empty-nor-nil, osd:is-equal-case-insensitive, osd:starts-with-case-insensitive, osd:ends-with-case-insensitive, osd:contains-case-insensitive, osd:contains-record-label

, or osd:search

<criterion>

<boolean criterion>, <numeric criterion>, <string criterion>, <date criterion>, <time criterion>, or <dateTime criterion>

<boolean criterion>

truefalse

<numeric criterion>

An integer or a decimal

-4.6

<string criterion>

Quoted character string

'azerty'

<date criterion>

Quoted and formatted as 'yyyy-MM-dd'

'2007-12-31'

<time criterion>

Quoted and formatted as 'HH:mm:ss' or 'HH:mm:ss.SSS'

'11:55:00'

<dateTime criterion>

Quoted and formatted as 'yyyy-MM-ddTHH:mm:ss' or 'yyyy-MM-ddTHH:mm:ss.SSS'

'2007-12-31T11:55:00'

XPath 1.0 formula

It is possible to use an XPath 1.0 formula in the criterion value part of an atomic predicate expression (right-hand side).

For example, instead of [./a=3], you may use the expression [./a=(floor(./d)+ 2.0)].

Due to the strong dependence of predicates on the data model node and the node type of the criterion, the path portion of the atomic predicate expression (left-hand side) must be a node path and cannot be an XPath formula. For example, the expression /table[floor(./a) > ceiling(./d)] is not valid.

Predicate on label

The osd:label() function can be applied to the path portion of the atomic predicate, in order to resolve the predicate on the label instead of the value. In this case, only string operators and string criteria can be used, i.e. ends-with(osd:label(./price),'99').

A predicate on label is localized, so the criterion must be expressed in the same locale as the predicate-filtered request. For example: request.setLocale(Locale.FRENCH); request.setXPathFilter("osd:label(./delivery_date)='30/12/2014'");

Note

It is forbidden to use the osd:label function if the right part of the predicate is a contextual value.

Note

If the osd:label function is used in a data model, for example on a selection or in the filter predicate of a table reference node, the default locale of the data model (as defined in its module declaration) must be used for the criterion format (even though this is generally not recommended).

Contextual values

For predicates that are relative to a selected node, the criterion value (that is, the right-hand side of the predicate) can be replaced with a contextual path using the syntax ${<relative-path>} where <relative-path> is the location of the element relative to the selected node.

Note

When calling a method, the criterion is the second parameter, and the first parameter cannot be a relative value.

Aggregated lists

For predicates on aggregated lists, the predicate returns true regardless of the comparator if one of the list elements verifies the predicate.

Note

Special attention must be paid to the comparator !=. For example, for an aggregated list, ./list != 'a' is not the same as not(./list = 'a'). Where the list contains the elements (e1,e2,..), the first predicate is equivalent to e1 != 'a' or e2 != 'a' ..., while the second is equivalent to e1 != 'a' and e2 != 'a' ....

'Null' values

Null values must be explicitly treated in a predicate using the operators osd:is-null and osd:is-not-null.

For example, /root/products[./price<100] or /root/products[./price!=100] will not return any products whose prices are not set (null). For the latter case to return unset values as well, the predicate must instead be: /root/products[./price!=100 or osd:is-null(./price)].

How to manage single and double quotes in literal expressions

By default, a literal expression is delimited by single quotes ('). If the literal expression contains single quotes and no double quotes, the expression must be delimited by double quotes ("). If the literal expression contains both single and double quotes, the single quotes must be doubled.

The method XPathExpressionHelper.encodeLiteralStringWithDelimiters in the Java API handles this.

Examples of using encodeLiteralStringWithDelimiters

Value of Literal Expression

Result of this method

Coeur

'Coeur'

Coeur d'Alene

"Coeur d'Alene"

He said: "They live in Coeur d'Alene".

'He said: "They live in Coeur d''Alene".'

Extraction of foreign keys

In EBX®, the foreign keys are grouped into a single field with the osd:tableRef declaration.

The standard XPath syntax has been extended so as to extract the value of any targeted primary key field.

Example

If the table /root/tableA has an osd:tableRef field named 'fkB' whose target is /root/tableB and the primary key of tableB has two fields, id of type xs:int and date of type xs:date, then the following expressions would be valid:

Java API

Using the XPath in the Java API:

In the Java API, the XPathFilter class allows to define XPath predicates and to execute requests on them.

The XPathExpressionHelper class provides utilitarian methods to handle XPath predicates and paths.

Documentation > Reference Manual > Integration