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. |
Predicates on label
osd:label(./delivery_date)=’12/30/2014’ and ends-with(osd:label(../adress),’Beijing - China’)
Predicates on record label
osd:contains-record-label(‘dumesnil’) or osd:contains-record-label(‘harmattan’)
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’)
| Note: XPath functions for validation search cannot be used on XPath predicates defined on associations and foreign key filters. The predicates osd:label, osd:contains-record-label and osd:contains-validation-message are localized. The locale can be set by the methods of the Java API Request.setLocale or Request.setSession. |
| 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(
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:
-
/root/tableA[ fkB = ‘123 2008-01-21’ ], where the string “123 2008-01-21” is a representation of the entire primary key value. - See Syntax of the internal String representation of primary keys for more information.
- /root/tableA[ fkB/id = 123 and date-equal(fkB/date, ‘2008-01-21’) ], where this predicate is a more efficient equivalent to the one in the previous example.
- /root/tableA[ fkB/id >= 123 ], where any number operator could be used, as the targeted primary key field is of type xs:int.
- /root/tableA[ date-greater-than( ./fkB/date, ‘2007-01-01’ ) ], where any date operator could be used, as the targeted primary key field is of type xs:date;
- /root/tableA[ fkB = “” ] is not valid as the targeted primary key has two columns.
- /root/tableA[ osd:is-null(fkB) ] checks if a foreign key is null (not defined).
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.