public class MbXPath
extends java.lang.Object
XPath, although designed for XML documents, can be applied to any tree structure for querying purposes. Within the broker it is used to select elements within the logical message model regardless of the format of the bit stream. Care has to be taken over the difference in terminology between IIB and XPath. An XML node is represented in the broker by an instance of class MbElement. The broker's concept of a message flow node is not relevant to this discussion.
MbXPath provides a complete implementation of the XPath 1.0 query syntax as described in the W3C recommendation at http://www.w3.org/TR/xpath.
This class can used to hold a pre-prepared XPath expression plus an optional reference
to a set of namespace prefix/URI bindings contained in a
MbNamespaceBindings
object.
Note that as of version 10, the methods used to store variable and namespace bindings
directly on objects of MbXPath have been deprecated.
Instead these bindings should be maintained in separate
MbXPathVariableBindings
and
MbNamespaceBindings
objects and applied to
the expression when it is evaluated using
evaluateXPath()
or
evaluateXPath()
.
For XML messages, namespaces are referred to using a mapping from an abbreviated
namespace prefix to the full namespace URI as shown in the following XML snippet:
<aaa xmlns='http://mydomain.com/namespace1'
xmlns:other='http://mydomain.com/namespace2'>
<other:aaa>
<bbb/>
</other:aaa>
<aaa>
While the namespace prefix is convenient shorthand for representing the namespace,
it is only meaningful within the document that defines that mapping.
It is the namespace URI that defines the global meaning.
Also the concept of namespace prefix becomes even more meaningless for documents
that are generated within a message flow since a namespace URI can be assigned
to a syntax element without an xmlns
mapping having been defined.
Although the broker only works internally with namespace URIs, the MbXPath provides
the ability to map namespace prefixes to the full URIs.
The prefixes in the XML snippet above could be used in an XPath expression by
calling the namespace mapping methods prior to evaluation:
MbNamespaceBindings ns = new MbNamespaceBindings();
ns.addBinding("other", "http://mydomain.com/namespace2");
ns.setDefaultNamespace("http://mydomain.com/namespace2");
MbXPath xp = new MbXPath("/aaa/other:aaa/bbb", ns);
List<MbElement> nodeset = (List<MbElement>)message.evaluateXPath(xp);
The broker will not use the prefixes used by the namespace declarations
in the XML document and the prefixes assigned in the above method calls do not
need to be the same as those in the XML namespace declarations.
Also, the namespace mappings attached to the MbXPath object are global mappings
for the whole document rather than the structured (hierarchical) mappings
of XML namespace declarations.
?name | - select children called 'name'. Create one (as last child) if none exist, then select it. |
?$name | - create 'name' as last child, then select it. |
?^name | - create 'name' as first child, then select it. |
?>name | - create 'name' as next sibling, then select it. |
?<name | - create 'name' as previous sibling, then select it. |
<example>
<items>
<item>
<price>3.45</price>
</item>
<item>
<price>6.57</price>
</item>
<item>
<price>1.95</price>
</item>
<item>
<price>0.50</price>
</item>
</items>
</example>
Expression | Resultant document |
---|---|
//price[set-value(. * 2)] This expression selects all price descendants of root and doubles their value. |
<example>
|
//price[set-local-name("cost")] This expression selects all price descendants of root and changes their name to cost. |
<example>
|
/example/?items/?$item/?price[set-value($three * 1.5)] This expression introduces the select-or-follow axis (in the abbreviated form). items already exists, so is selected. ?$item says create item as last child of items regardless of whether one already exists. This item is selected and the ?price creates a new child under it. Finally, the value of the price element is set by evaluating the argument. The variable three was assigned the value '3' prior to evaluation using:
MbXPathVariables vars = new MbXPathVariables();
|
<example>
|
(//item/?@index)[set-value(position())] This expression selects all item descendants of root and creates a new attribute (@) called index. All index attributes are selected and grouped within the parentheses. The argument of set-value() uses the core XPath function position() which returns the position of each node within the group. |
<example>
|
/example/items/?total[set-value(sum(/example/items/item/price))] This expression creates (or selects if it already existed) the element total as last child of items and sets its value to the sum of all the price values for all items. |
<example>
|
Constructor and Description |
---|
MbXPath(java.lang.String expression)
Creates an MbXPath object from an XPath 1.0 expression.
|
MbXPath(java.lang.String expression,
MbElement root)
Deprecated.
The root element should no longer be set on this object.
Instead use
setRootElement(rootElement) |
MbXPath(java.lang.String expression,
MbNamespaceBindings namespaceBindings)
Creates an MbXPath object from an XPath 1.0 expression.
|
Modifier and Type | Method and Description |
---|---|
void |
addNamespacePrefix(java.lang.String prefix,
java.lang.String uri)
Deprecated.
Namespace bindings should no longer be held directly in this class.
Instead use
addBinding(prefix, uri) |
void |
assignVariable(java.lang.String variable,
boolean value)
Deprecated.
Variable bindings should no longer be held in this class.
Instead use
assign(variable, value) |
void |
assignVariable(java.lang.String variable,
double value)
Deprecated.
Variable bindings should no longer be held in this class.
Instead use
assign(variable, value) |
void |
assignVariable(java.lang.String variable,
java.lang.Object value)
Deprecated.
Variable bindings should no longer be held in this class.
Instead use
assign(variable, value) |
void |
clearMbXPath()
Deletes the resources associated with the xpath object.
|
void |
removeAllVariables()
Deprecated.
Variable bindings should no longer be held in this class.
Instead use
removeAll() |
void |
removeNamespacePrefix(java.lang.String prefix)
Deprecated.
Namespace bindings should no longer be held directly in this class.
Instead use
removeBinding(prefix) |
void |
removeVariable(java.lang.String variable)
Deprecated.
Variable bindings should no longer be held in this class.
Instead use
remove(variable) |
void |
setDefaultNamespace(java.lang.String uri)
Deprecated.
Namespace bindings should no longer be held directly in this class.
Instead use
setDefaultNamespace(uri) |
void |
setNamespaceBindings(MbNamespaceBindings namespaceBindings)
Associates an MbNamespaceBindings object with this expression.
|
public MbXPath(java.lang.String expression) throws MbException
The expression may contain external variable bindings. This must be
associated with values using and instance of the
MbXPathVariables
class and applied to the expression
when it is evaluated using the
evaluateXPath(xpath, variables)
method.
By default the document root element is set as the last child
of the MbMessage root. This is an attempt to locate the message
'Body' and might not be suitable if the XPath is being evaluated
on the Environment, LocalEnvironment, or ExceptionList, or on a
detached MbElement tree.
To redefine the root element, use the
setRootElement(rootElement)
method in the MbXPathVariables class
expression
- An XPath 1.0 expression.MbException
- - An exception was thrown during the compilation of
the expression.public MbXPath(java.lang.String expression, MbNamespaceBindings namespaceBindings) throws MbException
This constructor associates an MbNamespaceBindings object with this expression. The MbNamespaceBindings object must contain an entry for each namespace prefix used within the XPath expression. This association is 'by reference', meaning that any subsequent modifications to the MbNamespaceBindings object will affect all MbXPath objects that are associated with that MbNamespaceBindings object.
The expression may contain external variable bindings. This must be
associated with values using and instance of the
MbXPathVariables
class and applied to the expression
when it is evaluated using the
evaluateXPath(xpath, variables)
method.
By default the document root element is set as the last child
of the MbMessage root. This is an attempt to locate the message
'Body' and might not be suitable if the XPath is being evaluated
on the Environment, LocalEnvironment, or ExceptionList, or on a
detached MbElement tree.
To redefine the root element, use the
setRootElement(rootElement)
method in the MbXPathVariables class
expression
- An XPath 1.0 expression.namespaceBindings
- A set of namespace prefix/URI bindingsMbException
- - An exception was thrown during the compilation of
the expression.@Deprecated public MbXPath(java.lang.String expression, MbElement root) throws MbException
setRootElement(rootElement)
expression
- An XPath 1.0 expression.root
- The MbElement object that represents the document root.MbException
- - An exception was thrown during the compilation of
the expression.public void setNamespaceBindings(MbNamespaceBindings namespaceBindings)
namespaceBindings
- A set of namespace prefix/URI bindings
the expression.@Deprecated public void assignVariable(java.lang.String variable, java.lang.Object value)
assign(variable, value)
variable
- The name of the variable reference. This can be referred to
in the XPath 1.0 expression by inserting a dollar ($) symbol before the variable name.value
- The value to be assigned to the variable. Must be one of:
Boolean
- representing an XPath 1.0 boolean.
Double
- representing an XPath 1.0 number.
String
- representing an XPath 1.0 string.
MbElement
- representing an XPath 1.0 nodeset (single node).
MbElement[]
- an array of MbElement objects,
representing an XPath 1.0 nodeset.
java.util.List
- a list of MbElement objects,
such as a nodeset returned by MbElement.evaluateXPath().
java.lang.ArrayStoreException
- - A List was passed in which contains one or more
objects which are not of type MbElement.@Deprecated public void assignVariable(java.lang.String variable, double value)
assign(variable, value)
variable
- The name of the variable reference. This can be referred to
in the XPath 1.0 expression by inserting a dollar ($) symbol before the variable name.value
- The value to be assigned to the variable. The value represents
an XPath 1.0 numeric type.@Deprecated public void assignVariable(java.lang.String variable, boolean value)
assign(variable, value)
variable
- The name of the variable reference. This can be referred to
in the XPath 1.0 expression by inserting a dollar ($) symbol before the variable name.value
- The value to be assigned to the variable. The value represents
an XPath 1.0 boolean type.@Deprecated public void removeVariable(java.lang.String variable)
remove(variable)
variable
- The name of the variable to remove.@Deprecated public void removeAllVariables()
removeAll()
@Deprecated public void addNamespacePrefix(java.lang.String prefix, java.lang.String uri)
addBinding(prefix, uri)
prefix
- The prefix part of the qualified name.uri
- The namespace URI to which the prefix refers.@Deprecated public void removeNamespacePrefix(java.lang.String prefix)
removeBinding(prefix)
prefix
- The prefix to be removed.@Deprecated public void setDefaultNamespace(java.lang.String uri)
setDefaultNamespace(uri)
uri
- The default namespace URI.public void clearMbXPath() throws MbException
MbException