Cloud Software Group, Inc. EBX®
Documentation > Reference Manual > Integration
Navigation mode Documentation > 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 (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.

##### See also

- Quick Search

The predicate `osd:search` is localized.

##### Note

The locale can be set by the methods of the Java API `Request.setLocale` or `Request.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')`

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

  ##### Note

  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(<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> | `=` or `!=` |
<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> | `contains` `osd:contains-case-insensitive` `osd:contains-record-label` `osd:is-equal-case-insensitive` `osd:is-empty` `osd:is-empty-or-nil` `osd:is-neither-empty-nor-nil` `osd:is-not-empty` `ends-with` `osd:ends-with-case-insensitive` `matches` `osd:search` `starts-with` or `osd:starts-with-case-insensitive` |
<criterion> | <boolean criterion> <date criterion> <dateTime criterion> <numeric criterion> <string criterion> or <time criterion> |
<boolean criterion> | `true` , `false` |
<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).

##### See also

- `SchemaNode.displayOccurrence`

#### 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. The criterion value must be a single value. That means that aggregated lists are not allowed as the target of the contextual path.

##### 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.

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.

##### 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.

Documentation > Reference Manual > Integration