org.jdom2.xpath
Class XPathHelper

java.lang.Object
  org.jdom2.xpath.XPathHelper

public final class XPathHelper
extends java.lang.Object

Provides a set of utility methods to generate XPath expressions to select a given node in a document. You can generate absolute XPath expressions to the target node, or relative expressions from a specified start point. If you request a relative expression, the start and target nodes must share some common ancestry.

XPaths are required to be namespace-aware. Typically this is done by using a namespace-prefixed query, with the actual namespace URI being set in the context of the XPath expression. This is not possible to express using a simple String return value. As a work-around, this method uses a potentially slower, but more reliable, mechanism for ensuring the correct namespace context is selected. The mechanism will appear like (for Elements):
.../*[local-name() = 'tag' and namespace-uri() = 'uri']
Similarly, Attributes will have a syntx similar to:
.../@*[local-name() = 'attname' and namespace-uri() = 'uri']
This mechanism makes it possible to have a simple namespace context, and a simple String value returned from the methods on this class.

This class does not provide ways to access document-level content. Nor does it provide ways to access data relative to the Document level. Use absolute methods to access data from the Document level.

The methods on this class assume that the Document is above the top-most Element in the XML tree. The top-most Element is the one that does not have a parent Element (although it may have a parent Document). As a result, you can use Element data that is not attached to a JDOM Document.

Detatched Attributes, and detached non-Element content are not treated the same. If you try to get an Absolute path to a detached Attribute or non-Element Content you will get an IllegalArgumentException. On the other hand it is legal to get the relative XPath for a detached node to itself ( but to some other node will cause an IllegalArgumentException because the nodes do not share a common ancestor).

Note: As this class has no knowledge of the document content, the generated XPath expression rely on the document structure. Hence any modification of the structure of the document may invalidate the generated XPaths.

Author:

Laurent Bihanic, Rolf Lear

Method Summary

static java.lang.String	getAbsolutePath(Attribute to) Returns the absolute path to the specified to Content.
static java.lang.String	getAbsolutePath(Content to) Returns the absolute path to the specified to Content.
static java.lang.String	getRelativePath(Attribute from, Attribute to) Returns the relative path from the given from Attribute to the specified to Attribute as an XPath expression.
static java.lang.String	getRelativePath(Attribute from, Content to) Returns the relative path from the given from Attribute to the specified to Content as an XPath expression.
static java.lang.String	getRelativePath(Content from, Attribute to) Returns the relative path from the given from Content to the specified to Attribute as an XPath expression.
static java.lang.String	getRelativePath(Content from, Content to) Returns the relative path from the given from Content to the specified to Content as an XPath expression.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getRelativePath

public static java.lang.String getRelativePath(Content from,
                                               Content to)

Returns the relative path from the given from Content to the specified to Content as an XPath expression.

Parameters:

from - the Content from which the the generated path shall be applied.

to - the Content the generated path shall select.

Returns:

an XPath expression to select the specified node.

Throws:

java.lang.IllegalArgumentException - if to and from are not part of the same XML tree

getRelativePath

public static java.lang.String getRelativePath(Content from,
                                               Attribute to)

Returns the relative path from the given from Content to the specified to Attribute as an XPath expression.

Parameters:

from - the Content from which the the generated path shall be applied.

to - the Attribute the generated path shall select.

Returns:

an XPath expression to select the specified node.

Throws:

java.lang.IllegalArgumentException - if to and from are not part of the same XML tree

getRelativePath

public static java.lang.String getRelativePath(Attribute from,
                                               Attribute to)

Returns the relative path from the given from Attribute to the specified to Attribute as an XPath expression.

Parameters:

from - the Attribute from which the the generated path shall be applied.

to - the Attribute the generated path shall select.

Returns:

an XPath expression to select the specified node.

Throws:

java.lang.IllegalArgumentException - if to and from are not part of the same XML tree

getRelativePath

public static java.lang.String getRelativePath(Attribute from,
                                               Content to)

Returns the relative path from the given from Attribute to the specified to Content as an XPath expression.

Parameters:

from - the Attribute from which the the generated path shall be applied.

to - the Content the generated path shall select.

Returns:

an XPath expression to select the specified node.

Throws:

java.lang.IllegalArgumentException - if to and from are not part of the same XML tree

getAbsolutePath

public static java.lang.String getAbsolutePath(Content to)

Returns the absolute path to the specified to Content.

Parameters:

to - the Content the generated path shall select.

Returns:

an XPath expression to select the specified node.

Throws:

java.lang.IllegalArgumentException - if to is not an Element and it is detached.

getAbsolutePath

public static java.lang.String getAbsolutePath(Attribute to)

Returns the absolute path to the specified to Content.

Parameters:

to - the Content the generated path shall select.

Returns:

an XPath expression to select the specified node.

Throws:

java.lang.IllegalArgumentException - if to is detached.