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.
The general XPath expression is:
path[predicate]
/library/books/
./Author
../Title
//books
../../books/[author_id = 0101 and (publisher = 'harmattan')]
/library/books/[not(publisher = 'dumesnil')]
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') )
author_id = $param1 and publisher = $param2where the parameters$param1and$param2refer respectively to0101and'harmattan'
col1 < $param1 and col4 = $param2where the parameters$param1and$param2refer respectively to100and'true'
contains(col3,$param1) and date-greater-than(col2,$param2)where the parameters$param1and$param2refer respectively to'xxx'and'2007-12-30'
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.
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 (in case of history table), or all optimized fields (in all other cases). See Limitations for more information about optimized / unoptimized fields.
Optimized text search filters cannot be OR-combined with non-optimized filters or filters that involve a different table. See Technical limitation 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 Value-labeling for more information.
For a more advanced usage, the query string supports specialized operators, see Special characters for more information.
The predicate osd:search is localized.
The locale can be set by the methods of the Java API Request.setLocale or Request.setSession.
The identifier of a search template can be specified, to customize the behavior of the search.
osd:has-validation-item()
osd:has-validation-item('error,info')
osd:contains-validation-message('xxx')
osd:contains-validation-message('xxx','info,warning')
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.
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.
Expression | Format | Example |
|---|---|---|
XPath expression | <container path>[predicate] |
|
<container path> | <absolute path> or <relative path> | |
<absolute path> |
|
|
<relative path> |
|
|
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>) |
|
<path> | <relative path> or osd:label(<relative path>) | Relative to the table that contains it:
|
<comparator> |
| |
<boolean comparator> |
| |
<numeric comparator> |
| |
<string comparator> |
| |
<method> |
| |
<date, time & dateTime method> |
| |
<string method> |
| |
<criterion> |
| |
<boolean criterion> |
| |
<numeric criterion> | An integer or a decimal |
|
<string criterion> | Quoted character string |
|
<date criterion> | Quoted and formatted as 'yyyy-MM-dd' |
|
<time criterion> | Quoted and formatted as 'HH:mm:ss' or 'HH:mm:ss.SSS' |
|
<dateTime criterion> | Quoted and formatted as 'yyyy-MM-ddTHH:mm:ss' or 'yyyy-MM-ddTHH:mm:ss.SSS' |
|
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.
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'");
It is forbidden to use the osd:label function if the right part of the predicate is a contextual value.
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).
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. The criterion value must be a single value. That means that aggregated lists are not allowed as the target of the contextual path.
When calling a method, the criterion is the second parameter, and the first parameter cannot be a relative value.
For predicates on aggregated lists, the predicate returns true regardless of the comparator if one of the list elements verifies the predicate.
In addition, the predicates osd:is-empty and osd:is-not-empty can be applied on any node which type is a list to very if the list is empty or not.
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 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)].
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 d'Alene" |
| 'He said: "They live in Coeur d''Alene".' |
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.
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).
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.