Web Services, La Trobe, Bendigo

Introduction to XPath

Revise: an XPath location path is a series of location steps that (conceptually) get us from one point in an XML document to another. If the location path begins with "/" it is an absolute path, otherwise it's a relative path, relative to the current (or context) node, or "place" in the document.
A location step has three parts:

An axis which describes the direction.
A node test to determine which particular nodes are applicable.
One or more optional predicates (see later) which are used to further narrow down the set of applicable (or selected) nodes. Predicates are Boolean tests on node sets that evaluate to true or false for each node.

Preview: Our Example XML Document

We shall refer to this XML document thoughout today's lecture. You may also download this as weather.xml.

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="weather.xsl"?>
<report>
   <date>Wed Aug 14 11:14:30</date>

   <weather-station>
      <location>
         <latitude>-36.82</latitude>
         <longitude>144.30</longitude>
         <place-name>Mandurang</place-name>
      </location>
      <rainfall unit="mm">5.0</rainfall>
      <max-temp>18.1</max-temp>
      <min-temp>6.2</min-temp>
    </weather-station>
  
  <weather-station>
      <location>
         <latitude>-36.77</latitude>
         <longitude>144.28</longitude>
         <place-name>Bendigo</place-name>
      </location>
      <rainfall unit="inches">0.20</rainfall>
      <max-temp>19.1</max-temp>
      <min-temp>7.0</min-temp>
  </weather-station>
   
  <weather-station>
    <location>
       <latitude>unknown</latitude>
       <longitude>unknown</longitude>
       <place-name>Swan Hill</place-name>
    </location>
    <rainfall unit="inches">0.0</rainfall>
    <max-temp>29.1</max-temp>
    <min-temp>7.0</min-temp>
  </weather-station>
</report>

Location Path Shortcuts

Location paths tend to be rather verbose. XPath defines some useful shortcut forms:

Shortcut syntax	Matches
`@unit`	Matches an attribute of the current node called `unit`. This is exactly equivalent to `attribute::unit`.
`.`	"Dot" matches the current node. We have already seen this one.
`/*`	Matches the document root element, since a leading `/` indicates an absolute path and `*` matches any element.
`..`	"dotdot" matches the parent node, equivalent to `parent::node()`.
`.//food`	Matches any element `food` that is a descendent of the context node. The double-slash is shorthand for `descendent-or-self::food` (?)
`//food`	Matches any element `food` in the entire document.
`../*`	Matches all sibling elements, and the context node itself if it is an element.

Predicates

A predicate is a Boolean expression enclosed in square brackets ([ ... ]) and used to narrow-down the set of selected nodes. Typical usage:
```
/report/weather-station/location[place-name = "Mandurang"]
```

Some more examples:

location path	context	axis	node test	predicate	node set
`child::myElement[postion()=5]`	`.`	`child::`	`myElement`	`position()=5`	a single node - the fifth child of the context node called "myElement"
`/e1/e2/myElement/text()`	`/`	-	text node	-	a node set consisting of all text nodes that are children of any `/e1/e2/myElement` element
`./../room[. = 'B1.30']`	`.`	-	-	`. = 'B1.30'` Note: predicate is relative to the last step in the Xpath expression.	all siblings with room equal to "B1.30"
`./../room[. = 'B1.30' and ../day = 'Monday']`	`.`	-	-	`. = 'B1.30' and ../day = 'Monday'`	all siblings with room equal to "B1.30" with a sibling named 'day' that contains the string "Monday"
`//rainfall[@unit="mm" and . >= 2]`	`/`	-	-	`@unit="mm" and . >= 2` Note: encoding of "`>=`" in an XML document	all nodes named 'rainfall' (wherever they appear in the document) where the unit is 'mm' and the value is greater than or equal to '2'.

Boolean Expressions in Predicates

These Boolean operators have their usual meanings, and note that entity encoding will be necessary for those containing "<" and ">":
```
=  <  >  <=  >=  !=
```
Expressions formed using these XPath Boolean operators can be logically combined via the usual "and" and "or" operators.
Expressions which evaluate to a number are used to indicate an index into a sequence of elements, eg: //weather-station[2] indicates the second weather-station node (indices start at 1, NOT zero as in most modern programming languages).
Predicates can also be the name of an element: if a child element (of the context node) with the specified name exists and has a value, then the context node is selected. So for example, in the weather.xml document if the "location" element for "Swan Hill" was simply omitted (instead of being present with child elements valued "unknown"), this could be used to select only weather station whose location is known.
Finally, all location steps in a location path can have a predicate. So to select the first weather station only if the units given for rainfall are "inches" we can do.

/report/weather-station[1]/child::rainfall[attribute::unit="inches"]

Non-Boolean XPath Expressions

XPath expressions can also evaulate to types other than Boolean. These are not used for selecting node sets, but have other uses in (eg) XSLT. The types are:
Number
XPath numbers are 8-byte IEEE-standard floating point, just like Java's double type. The available numerical operators, which have their usual meanings, are:

+  -  *  div  mod

Numbers can be positive, negative or zero, as expected. They can also be "NaN" (for "Not a Number" -- the result of illegal operations such as divide-by-zero), "Inf" (positive infinity) and "-Inf" (negative infinity).
String
An XPath string is simply a string of zero or more Unicode characters. The only restriction is that a string can't contain the same kind of quotes as are used to delimit it.

XPath Functions

XPath defines a large-ish set of useful functions. Functions return one of four data types: Boolean, Number, Node-set and String. Functions are indentified by ( ... ) parentheses on the end of the name.
Node-set Functions
These operate on, or return, information about node-sets.
String Functions
These functions return information about strings, and perform operations on string data. They are reasonably powerful, but are greatly inferior to the facilities in (eg) Perl.
Number Functions
These perform some basic arithmetic operations -- taking one or more numbers (or other data types) and returning a numeric result.
Boolean Functions
These four functions simply return "true" or "false" values. They are true(), false(), not() (Boolean negation) and boolean(), which evaluates other data types to Boolean.

Node-set Functions Reference

`position()`	Returns a number corresponding to the current node.
`last()`	Returns the number of nodes in the current (context) node-set. This is the same as the position of the last node in ths set.
`count()`	Works a little like `last()` except it returns the number of nodes in its node-set argument. So `count(//weather-station)` gives the number of elements named "`weather-station`" in the document
`id()`	Argument is a string containing one or more IDs, declared in the DTD as being attributes of type ID -- may also be named `ID` or `id`. The return value is a node-set of all nodes containing those IDs. The DTD must be present for this to work.
Others: `local-name()` `namespace-uri()` `name()`	Each of these functions takes a node-set and returns (1) the "local part" of the first node, (2) the namespace URI of the first node and (3) the qualified name of the first node.

String Functions Reference

`string()`	Converts its argument to a string. Booleans are converted to "`true`" or "`false`", node-sets are converted to the string value of the first node in the set (just like "`xsl:value-of`"), etc.
`starts-with()`	Returns true if the first string argument "starts with" the second string argument. So "`starts-with("Philip", "Phil")`" is true.
`contains()`	Returns true if the first string argument "contains" the second string argument. So "`starts-with("service", "vice")`" is true.
Extracting substrings: `substring()` `substring-left()` `substring-right`	The first of these functions takes a string, and index value and an optional length and returns an extracted substring. The second two take two string and return the substring of the first string either before or after the second string. They're easier to use than to explain. :-)
`string-length()`	Returns the length of its parameter in characters, or the length of the context node if no paramter.
`concat()`	Concatenates multiple strings into a single longer string.
`normalize-space()`	Compacts successive whitespace characters into a single SPACE.
Others: `lang()` `translate()`	The first of these returns true if the context node is written in its language code parameter. The second does character-by-character replacement (not language translation). If you need to use this function, read the manual first; it's not obvious.

Number Functions Reference

`number()`	Converts its parameter (or the context node if no parameter) to a number . Makes reasonable assumptions (eg, Boolean `true` is converted to "1"), and returns `NaN` if conversion isn't possible.
`sum()`	Takes a node-set argument, converts each of the elements to a number and adds them up, returning the result.
Integer conversions: `floor()` `ceiling()` `round()`	Have their usual (POSIX-like) meanings, and all return the appropriate integer value.
Other functions that are also number functions: `position()` `last()` `count()` `string-length()`	All defined earlier. These return integer values.

XPointer

The XML Pointer Language is used to identify abitrary locations inside an external XML document. It can be thought of as an extension to the HTML <a name="..."/> "fragment identifier" technique, but has advantages:

It's not necessary to have "modify" access to the target XML document to create an HTML-style <a name="..."/> target: XPointer can "point" to any location in any document by the use of XPath Expressions.
Can select specific points in, and ranges of, the XML document that are not necessarily a node or set of nodes.

The following are acceptable XPointers, and note that not all of these evaluate to a single node:

xpointer(/)
xpointer(//weather-station)
xpointer(/resport/weather-station/place-name/text())
xpointer(/child::report/child::date)

XPointers can be used as a component of a URI, although it's not specified how a browser will handle it, eg:
```
http://asdf.com/weather.xml#xpointer(//weather-station[1])
```
XPointer instroduces two new concepts: points and ranges, and some new functions to support them. This is outside the scope of our subject. A related technology, XLink has faded from view but is still mentioned in the texts.