public class MbXPath extends 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 WBIMB logical message model regardless of the format of the bit stream. Care has to be taken over the difference in terminology between WBIMB 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.
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 above XML snippet could used in an XPath expression by
calling the namespace mapping methods prior to evaluation:
MbXPath xp = new MbXPath("/aaa/other:aaa/bbb");
xp.addNamespacePrefix("other", "http://mydomain.com/namespace2");
xp.setDefaultNamespace("http://mydomain.com/namespace2");
List nodeset = (List)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 created in 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:
xp.assignVariable("three", 3);
|
<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(String expression)
Creates an MbXPath object from an XPath 1.0 expression.
|
MbXPath(String expression,
MbElement root)
Creates an MbXPath object from an XPath 1.0 expression.
|
Modifier and Type | Method and Description |
---|---|
void |
addNamespacePrefix(String prefix,
String uri)
Add a mapping between a namespace prefix and the full namespace URI.
|
void |
assignVariable(String variable,
boolean value)
Assigns a new value to the named external variable binding in the
current object.
|
void |
assignVariable(String variable,
double value)
Assigns a new value to the named external variable binding in the
current object.
|
void |
assignVariable(String variable,
Object value)
Assigns a new value to the named external variable binding in the
current object.
|
void |
removeAllVariables()
Removes the currently assigned values of all the named external variable bindings.
|
void |
removeNamespacePrefix(String prefix)
Removes the currently assigned prefix to namespace URI mapping.
|
void |
removeVariable(String variable)
Removes the currently assigned value of the named external variable binding.
|
void |
setDefaultNamespace(String uri)
Sets the default namespace URI for this XPath 1.0 expression.
|
public MbXPath(String expression) throws MbException
expression
- An XPath 1.0 expression.MbException
- - An exception was thrown during the compilation of
the expression.public MbXPath(String expression, MbElement root) throws MbException
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 assignVariable(String variable, Object 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().
ArrayStoreException
- - A List was passed in which contains one or more
objects which are not of type MbElement.public void assignVariable(String variable, double 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.public void assignVariable(String variable, boolean 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.public void removeVariable(String variable)
variable
- The name of the variable to remove.public void removeAllVariables()
public void addNamespacePrefix(String prefix, String uri)
prefix
- The prefix part of the qualified name.uri
- The namespace URI to which the prefix refers.public void removeNamespacePrefix(String prefix)
prefix
- The prefix to be removed.public void setDefaultNamespace(String uri)
uri
- The default namespace URI.