Simple XPath Expressions

The "simple" XPath expressions supported by these marshal plug-ins are not true XPath expressions, though they aim to be as similar as possible to a very small and simple subset of the location paths defined by the W3C XPath 1.0 recommendation.

The paths operate on a DOM document created by parsing the XML string that is returned as the value of a server interface property. Each step in the path selects one or more nodes in the document and subsequent steps are evaluated within the context of each of those selected nodes. The context starts with the document node, so the first step will identify the root element of the document.

The selector of a step (that part of the step before the predicate) defines the name of the element or attribute to be selected. The prefix @ is used to indicate an attribute name; an element name requires no prefix. An element name may be followed by a single, optional predicate with an integer index value (starting from one) or an attribute selection expression.

Figure 1. A Sample XML Document

<values id="a1" locale="en">
  <value domain="SVR_INT32">1234</value>
  <value domain="SVR_DATE">20080131</value>
  <value domain="ADDRESS_DATA">
    <address>Apt. 86</address>
    <address>1000 Main St.</address>
    <city>Hometown</city>
  </value>
</values>

For example, if the XML document has the form shown in Simple XPath Expressions, then the path /values selects the values root element; /values/value[3] selects the third value element within the values root element; /values/value[@domain='SVR_DATE'] selects the value element with the domain attribute value SVR_DATE within the values root element; /values/value[2]/@domain selects the domain attribute of the second value element within the values root element; /values/value selects all three value elements within the values root element; /values/value/@domain selects the three domain attributes from the three value elements within the values root element; and the paths /values/value[3]/address and /values/value/address both select the two address elements of the third value element within the values root element. When more than one node is selected, the selected nodes are returned in the order in which they appear in the document.

An attribute value expression can be used to select elements that have an attribute with a particular value. An example was given above. The expression is limited to a single attribute name, prefixed with @ followed by an equals sign and a quoted string value. The attribute name must be on the left-hand side of the equals sign only. The string can be quoted with single quotes or double quotes. If single quotes are used, then the string can contain double quotes and vice versa. The string cannot contain any /, [ or ] characters; it is intended to be used only for matching ID values or other simple identifiers.

The selector * selects any element and the selector @* selects any attribute. For example, the path /values/value[3]/* selects the two address elements and the city element of the third value element within the values root element; the path /values/@* selects the id and locale attributes of the values root element; the path /values/*/@* selects all of the attributes of all of the child elements of the values root element; the path /values/value[3]/*[3] selects the third child element of any name of the third value element within the values root element, the city element in the case of the document above.

There are a number of restrictions on the steps that can be used and on their positions in a path. Where an element or attribute name appears below, a * can replace it. The allowed forms are as follows (the examples refer to the above sample document):

element-name: An element name identifying the elements to be selected within the context provided by the previous path step. For example, /values selects the values root node, while /values/value selects all three value elements within the values root element.
element-name [ index ]: An element name and an integer index value identifying one of several elements with that name in the context provided by the previous path step. For example, /values[1] selects the first values element, which, as it is the root element and the only values element, selects the same element as the simpler path /values; /values/value[2] selects the second value element that is a child of the values root element.
element-name [@ attribute-name = quoted-string ]: An element name and an attribute selection expression identifying elements with that name and with that value for the named attribute in the context provided by the previous path step. See above for more details.
@ attribute-name: An attribute name identifying an attribute of the element or elements selected by the previous steps in the path. An attribute selection step is only allowed as the last step in a path unless it is followed by a single function step (described below).

For convenience, the following step form may also be used in leading steps or the terminal step:

element-name []: An element name followed by an empty predicate. This is treated in the same way as a simple element name. This is not a true XPath expression, but it is convenient for situations when a path has an empty predicate to which an index will later be applieda common scenario if all that is required is a count of the nodes.

A valid path may select zero or more nodes. The values returned for these nodes depend on which method of the DataAccessor was called from the renderer class. The details are provided in the next section.

The Path interface does not support the representation of full XPath expression. Notably, XPath function calls that accept location paths as arguments cannot be represented, so a non-standard notation is used to provide some basic functionality. Instead of an expression of the form function-name (location-path) , the form location-path / function-name () is used instead. For example, to the get the qualified name of the third child element of the third value element in the sample document above, the path would be /values/value[3]/*[3]/name(); this is treated as if it were the expression name(/values/value[3]/*[3]).

A function may only appear as the last step in a path. The supported functions are as follows:

name(): Gets the qualified name of the first node selected by the path. This will be the element or attribute name including any namespace prefix.
local-name(): Gets the name of the first node selected by the path. This will be the element or attribute name not including any namespace prefix.