JDOM 2.0.6.1 · org.jdom2.xpath.XPathHelper

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

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

Constructor Summary

Access	Constructor and Description
private	XPathHelper() Private constructor.

Method Summary

Modifier and Type	Method and Description
public static String	Returns: an XPath expression to select the specified node. getAbsolutePath(final Content the Content the generated path shall select. to) Returns the absolute path to the specified to Content.
public static String	Returns: an XPath expression to select the specified node. getAbsolutePath(final Attribute the Content the generated path shall select. to) Returns the absolute path to the specified to Content.
private static StringBuilder	Returns: the XPath sub-expression to select the target node among its siblings. getPositionPath(Object the target node for the XPath expression. node, List<?> the siblings of the target node. siblings, String the path token identifying the target node. pathToken, StringBuilder the buffer to which appending the XPath sub-expression or `null` if the method shall allocate a new buffer. buffer) Appends the specified path token to the provided buffer followed by the position specification of the target node in its siblings list (if needed).
private static StringBuilder	Returns: an XPath expression to select the specified node. getRelativeElementPath(final Element the Element the generated path shall select relative to. from, final Parent the Content the generated path shall select. to, final StringBuilder the StringBuilder to append the path to. sb) Returns the path to the specified `to`Element from the specified `from` Element.
public static String	Returns: an XPath expression to select the specified node. getRelativePath(final Content the Content from which the the generated path shall be applied. from, final Content the Content the generated path shall select. to) Returns the relative path from the given from Content to the specified to Content as an XPath expression.
public static String	Returns: an XPath expression to select the specified node. getRelativePath(final Content the Content from which the the generated path shall be applied. from, final Attribute the Attribute the generated path shall select. to) Returns the relative path from the given from Content to the specified to Attribute as an XPath expression.
public static String	Returns: an XPath expression to select the specified node. getRelativePath(final Attribute the Attribute from which the the generated path shall be applied. from, final Attribute the Attribute the generated path shall select. to) Returns the relative path from the given from Attribute to the specified to Attribute as an XPath expression.
public static String	Returns: an XPath expression to select the specified node. getRelativePath(final Attribute the Attribute from which the the generated path shall be applied. from, final Content the Content the generated path shall select. to) Returns the relative path from the given from Attribute to the specified to Content as an XPath expression.
private static final StringBuilder	Returns: The same buffer as was input. getSingleStep(final NamespaceAware The token to get the relative-to-parent XPath for nsa, final StringBuilder The buffer to append the relative stage to buffer) Calculate a single stage of an XPath query.
private static int	Returns: the position of the f value in the tostack. locate(final Parent The Element to search for. f, final List<Parent> The list to search in. tostack) Do an identity search in an array for a specific value.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

XPathHelper	back to summary
private XPathHelper() Private constructor.

Method Detail

getAbsolutePath back to summary

getAbsolutePath	back to summary
public static String getAbsolutePath(final Content to) Returns the absolute path to the specified to Content. Parameters to:Content the Content the generated path shall select. Returns:String an XPath expression to select the specified node. Exceptions IllegalArgumentException: if `to` is not an Element and it is detached.

public static String getAbsolutePath(final Content to)

Returns the absolute path to the specified to Content.

Parameters

to:Content: the Content the generated path shall select.

Returns:String

an XPath expression to select the specified node.

Exceptions

IllegalArgumentException:: if to is not an Element and it is detached.

getAbsolutePath back to summary

getAbsolutePath	back to summary
public static String getAbsolutePath(final Attribute to) Returns the absolute path to the specified to Content. Parameters to:Attribute the Content the generated path shall select. Returns:String an XPath expression to select the specified node. Exceptions IllegalArgumentException: if `to` is detached.

public static String getAbsolutePath(final Attribute to)

Returns the absolute path to the specified to Content.

Parameters

to:Attribute: the Content the generated path shall select.

Returns:String

an XPath expression to select the specified node.

Exceptions

IllegalArgumentException:: if to is detached.

getPositionPath back to summary

getPositionPath	back to summary
private static StringBuilder getPositionPath(Object node, List<?> siblings, String pathToken, StringBuilder buffer) Appends the specified path token to the provided buffer followed by the position specification of the target node in its siblings list (if needed). Parameters node:Object the target node for the XPath expression. siblings:List<?> the siblings of the target node. pathToken:String the path token identifying the target node. buffer:StringBuilder the buffer to which appending the XPath sub-expression or `null` if the method shall allocate a new buffer. Returns:StringBuilder the XPath sub-expression to select the target node among its siblings.

private static StringBuilder getPositionPath(Object node, List<?> siblings, String pathToken, StringBuilder buffer)

Appends the specified path token to the provided buffer followed by the position specification of the target node in its siblings list (if needed).

Parameters

node:Object: the target node for the XPath expression.
siblings:List<?>: the siblings of the target node.
pathToken:String: the path token identifying the target node.
buffer:StringBuilder: the buffer to which appending the XPath sub-expression or null if the method shall allocate a new buffer.

Returns:StringBuilder

the XPath sub-expression to select the target node among its siblings.

getRelativeElementPath back to summary

getRelativeElementPath	back to summary
private static StringBuilder getRelativeElementPath(final Element from, final Parent to, final StringBuilder sb) Returns the path to the specified `to`Element from the specified `from` Element. The from Element must have a common ancestor Element with the to Element. Parameters from:Element the Element the generated path shall select relative to. to:Parent the Content the generated path shall select. sb:StringBuilder the StringBuilder to append the path to. Returns:StringBuilder an XPath expression to select the specified node. Exceptions IllegalArgumentException: if the from and to Elements have no common ancestor.

private static StringBuilder getRelativeElementPath(final Element from, final Parent to, final StringBuilder sb)

Returns the path to the specified toElement from the specified from Element. The from Element must have a common ancestor Element with the to Element.

Parameters

from:Element: the Element the generated path shall select relative to.
to:Parent: the Content the generated path shall select.
sb:StringBuilder: the StringBuilder to append the path to.

Returns:StringBuilder

an XPath expression to select the specified node.

Exceptions

IllegalArgumentException:: if the from and to Elements have no common ancestor.

getRelativePath back to summary

getRelativePath	back to summary
public static String getRelativePath(final Content from, final Content to) Returns the relative path from the given from Content to the specified to Content as an XPath expression. Parameters from:Content the Content from which the the generated path shall be applied. to:Content the Content the generated path shall select. Returns:String an XPath expression to select the specified node. Exceptions IllegalArgumentException: if `to` and `from` are not part of the same XML tree

public static String getRelativePath(final Content from, final Content to)

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

Parameters

from:Content: the Content from which the the generated path shall be applied.
to:Content: the Content the generated path shall select.

Returns:String

an XPath expression to select the specified node.

Exceptions

IllegalArgumentException:: if to and from are not part of the same XML tree

getRelativePath back to summary

getRelativePath	back to summary
public static String getRelativePath(final Content from, final Attribute to) Returns the relative path from the given from Content to the specified to Attribute as an XPath expression. Parameters from:Content the Content from which the the generated path shall be applied. to:Attribute the Attribute the generated path shall select. Returns:String an XPath expression to select the specified node. Exceptions IllegalArgumentException: if `to` and `from` are not part of the same XML tree

public static String getRelativePath(final Content from, final Attribute to)

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

Parameters

from:Content: the Content from which the the generated path shall be applied.
to:Attribute: the Attribute the generated path shall select.

Returns:String

an XPath expression to select the specified node.

Exceptions

IllegalArgumentException:: if to and from are not part of the same XML tree

getRelativePath back to summary

getRelativePath	back to summary
public static String getRelativePath(final Attribute from, final Attribute to) Returns the relative path from the given from Attribute to the specified to Attribute as an XPath expression. Parameters from:Attribute the Attribute from which the the generated path shall be applied. to:Attribute the Attribute the generated path shall select. Returns:String an XPath expression to select the specified node. Exceptions IllegalArgumentException: if `to` and `from` are not part of the same XML tree

public static String getRelativePath(final Attribute from, final Attribute to)

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

Parameters

from:Attribute: the Attribute from which the the generated path shall be applied.
to:Attribute: the Attribute the generated path shall select.

Returns:String

an XPath expression to select the specified node.

Exceptions

IllegalArgumentException:: if to and from are not part of the same XML tree

getRelativePath back to summary

getRelativePath	back to summary
public static String getRelativePath(final Attribute from, final Content to) Returns the relative path from the given from Attribute to the specified to Content as an XPath expression. Parameters from:Attribute the Attribute from which the the generated path shall be applied. to:Content the Content the generated path shall select. Returns:String an XPath expression to select the specified node. Exceptions IllegalArgumentException: if `to` and `from` are not part of the same XML tree

public static String getRelativePath(final Attribute from, final Content to)

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

Parameters

from:Attribute: the Attribute from which the the generated path shall be applied.
to:Content: the Content the generated path shall select.

Returns:String

an XPath expression to select the specified node.

Exceptions

IllegalArgumentException:: if to and from are not part of the same XML tree

getSingleStep	back to summary
private static final StringBuilder getSingleStep(final NamespaceAware nsa, final StringBuilder buffer) Calculate a single stage of an XPath query. Parameters nsa:NamespaceAware The token to get the relative-to-parent XPath for buffer:StringBuilder The buffer to append the relative stage to Returns:StringBuilder The same buffer as was input.

getSingleStep

back to summary

private static final StringBuilder getSingleStep(final NamespaceAware nsa, final StringBuilder buffer)

Calculate a single stage of an XPath query.

Parameters

nsa:NamespaceAware: The token to get the relative-to-parent XPath for
buffer:StringBuilder: The buffer to append the relative stage to

Returns:StringBuilder

The same buffer as was input.

locate	back to summary
private static int locate(final Parent f, final List<Parent> tostack) Do an identity search in an array for a specific value. Parameters f:Parent The Element to search for. tostack:List<Parent> The list to search in. Returns:int the position of the f value in the tostack.

locate

back to summary

private static int locate(final Parent f, final List<Parent> tostack)

Do an identity search in an array for a specific value.

Parameters

f:Parent: The Element to search for.
tostack:List<Parent>: The list to search in.

Returns:int

the position of the f value in the tostack.

public final Class XPathHelper

Constructor Summary

Method Summary

Constructor Detail

Method Detail