Section 9.9. Axis

9.9. Axis Although it's not usually associated with evil (although cursing is a different story), an axis is a node set starting at a particular node that is based on the relationship between the nodes in an XML document. The basic format for using an axis follows: axis::context-node Table 9-3 describes the properties of the various axes available in XPath. Table 9-3. XPath Axes Axis Description ancestor Selects all nodes that are ancestors of the context node, farther up the document tree, in a direct line to the document root node. The resulting node set is in reverse document orderin other words, moving up the tree starting from the document's parent node. ancestor-or-self Selects the same nodes as the ancestor axis. However, it starts with the context node instead of the context node's parent. attribute Selects all the context node's attributes, if any. child Selects all the child nodes of the context node, excluding attributes and namespace nodes. descendant Recursively selects all children of the context node and their children until the end of each tree branch. descendant-or-self Selects the same nodes as the descendant axis, with the exception of starting with the context node. following Selects, in document order, all nodes at any level in the document tree that follow the context node. following-sibling Selects, in document order, all nodes at the same level and with the same parent node in the document tree that follow the context node. namespace Selects the namespace nodes that are in scope for the context node. If no namespace nodes are in scope, the namespace axis is empty. parent Selects the parent node of the context node. If the context node is the root node, the parent axis will be empty. preceding Selects all nodes, in reverse document order, excluding ancestor nodes, in the document tree that are before the context node. preceding-sibling Selects all nodes, in reverse document order, that are at the same level that have the same parent node as the context node. self Selects the context node. The use of an axis is arguably the most formidable concept for developers new to XPath, who often have difficulty trying to visualize the results of using an axis. Fortunately, tools such as the XPath Evaluator in Altova's XMLSPY make it easier to see the results of specifying a particular axis. Starting with the original XML document from Listing 9-1, the following sections present examples of each of the various axes. 9.9.1. Ancestor Axis Example XPath Statement //book[3]/ancestor::* Result Node Set library Explanation Because the context node, the third book node, is a child of the root element, there is only a single ancestor. 9.9.2. ancestor-or-self Axis Example XPath Statement //book[3]/ancestor-or-self::* Result Node Set book library Explanation In addition to the ancestor nodes, the ancestor-or-self axis returns the context node. Also, because the results are in reverse document order, the context node is the first node in the node set, followed by the parent node and so on up the tree. 9.9.3. attribute Axis Example XPath Statement //book[3]/attribute::* Result Node Set publisher Explanation Because the context node has only one attribute, it is the only attribute returned in the node set. 9.9.4. child Axis Example XPath Statement //book[3]/child::* Result Node Set series "The Lord of the Rings" title "The Two Towers" author "J.R.R. Tolkien" Explanation The resulting node set consists of the three child nodes of the context node. I have shown the contents of the individual nodes to distinguish these nodes from similar nodes with different contents. 9.9.5. descendant Axis Example XPath Statement //book[3]/descendant::* Result Node Set series "The Lord of the Rings" title "The Two Towers" author "J.R.R. Tolkien" Explanation The results shown here are identical to the results from the child axis. This is because of the structure of the XML document. For instance, if any of the child nodes shown here had children of their own, the descendant axis would have returned their children, and so on down the line in document order, whereas the child axis would not. 9.9.6. descendant-or-self Axis Example XPath Statement //book[3]/descendant-or-self::* Result Node Set book series "The Lord of the Rings" title "The Two Towers" author "J.R.R. Tolkien" Explanation As with the descendant axis, all child nodes are returned recursively. However, instead of starting with the first child, the context node is the first node in the node set. 9.9.7. following Axis Example XPath Statement //book[3]/following::* Result Node Set book series "The Lord of the Rings" title "The Return of the King" author "J.R.R. Tolkien" book series "Lord Darcy" title "Too Many Magicians" author "Randall Garrett" book series "Lord Darcy" title "Murder and Magic" author "Randall Garrett" book series "Lord Darcy" title "The Napoli Express" author "Randall Garrett" book series "Lord Darcy" title "Lord Darcy Investigates" author "Randall Garrett" Explanation The resulting node set for the following axis is always all the nodes that occur after the context node in document order. 9.9.8. following-sibling Axis Example XPath Statement //book[3]/following-sibling::* Result Node Set book book book book book Explanation These five book nodes retrieved using the following-sibling axis are the same nodes that were retrieved by the following axis. The only difference is that the following-sibling axis retrieves only those nodes on the same level as the context node and have the same parent as the context node. 9.9.9. namespace Axis Example XPath Statement //book[3]/namespace::* Result Node Set Empty node set Explanation Because no namespace was in scope on the context node, the resulting node set is empty. However, if one or more namespaces had been in scope, the resulting node set would have contained those in scope. 9.9.10. parent Axis Example XPath Statement //book[3]/parent::* Result Node Set library Explanation The resulting node set will always consist of either an empty node set or a single node. For example, the parent axis of the library element would have retrieved an empty node set. 9.9.11. preceding Axis Example XPath Statement //book[3]/preceding::* Result Node Set author "J.R.R. Tolkien" title "The Fellowship of the Ring" series "The Lord of the Rings" book author "Clifford D. Simak" title "Way Station" series book Explanation The resulting node set of the preceding axis is made up of those nodes that occur in the XML document before the context node, in reverse document order. 9.9.12. preceding-sibling Axis Example XPath Statement //book[3]/preceding-sibling::* Result Node Set book book Explanation These book nodes retrieved using the preceding-sibling axis are the same nodes that were retrieved by the preceding axis. However, the difference is that the preceding-sibling axis retrieves only those nodes that are on the same level as the context node and that have the same parent as the context node. 9.9.13. self Axis Example XPath Statement //book[3]/self::* Result Node Set book Explanation The self axis returns the context node; essentially, the result is the same as if the axis were omitted.