java.lang.Object com.ibm.broker.plugin.MbXPath
public class MbXPath
extends Object
XPath is a query language for addressing parts of an XML document. It navigates the hierarchical structure of a document using a directional select and predicate based syntax.
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 bitstream. Care has to be taken over the difference in terminology between WBIMB and XPath. Specifically, the terms node and element could cause confusion. The following table highlights some important differences:
XPath 1.0 | WBIMB |
---|---|
node | object of class MbElement |
element node | 'Name' MbElement |
attribute node | 'Name/Value' MbElement |
text node | 'Value' MbElement |
The broker's definition of a 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 | Description |
---|---|
MbXPath(String) | Creates an MbXPath object from an XPath 1.0 expression. |
MbXPath(String, MbElement) | Creates an MbXPath object from an XPath 1.0 expression. |
Method | Description |
---|---|
void addNamespacePrefix(String, String) | Add a mapping between a namespace prefix and the full namespace URI. |
void assignVariable(String, boolean) | Assigns a new value to the named external variable binding in the current object. |
void assignVariable(String, double) | Assigns a new value to the named external variable binding in the current object. |
void assignVariable(String, Object) | 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) | Removes the currently assigned prefix to namespace URI mapping. |
void removeVariable(String) | Removes the currently assigned value of the named external variable binding. |
void setDefaultNamespace(String) | Sets the default namespace URI for this XPath 1.0 expression. |
public MbXPath(String expression) throws MbExceptionCreates an MbXPath object from an XPath 1.0 expression. The expression may contain external variable bindings. By default the root element is the message 'Body' (i.e. last child of MbMessage root).
- Parameters
- expression - An XPath 1.0 expression.
- Throws
MbException
- An exception was thrown during the compilation of the expression.
public MbXPath(String expression, MbElement root) throws MbExceptionCreates an MbXPath object from an XPath 1.0 expression. The expression may contain external variable bindings. By default the root element is the message 'Body' (i.e. last child of MbMessage root). This constructor allows the document root to be defined. Absolute path locations start at this root element.
- Parameters
- expression - An XPath 1.0 expression.
- root - The MbElement object that represents the document root.
- Throws
MbException
- An exception was thrown during the compilation of the expression.
public void addNamespacePrefix(String prefix, String uri)Add a mapping between a namespace prefix and the full namespace URI.
- Parameters
- prefix - The prefix part of the qualified name.
- uri - The namespace URI to which the prefix refers.
public void assignVariable(String variable, boolean value)Assigns a new value to the named external variable binding in the current object.
- Parameters
- variable - The name of the variable reference. This can be referred to in the XPath 1.0 expression by prepending the dollar ($) symbol.
- value - The value to be assigned to the variable. The value represents an XPath 1.0 boolean type.
public void assignVariable(String variable, double value)Assigns a new value to the named external variable binding in the current object.
- Parameters
- variable - The name of the variable reference. This can be referred to in the XPath 1.0 expression by prepending the dollar ($) symbol.
- value - The value to be assigned to the variable. The value represents an XPath 1.0 numeric type.
public void assignVariable(String variable, Object value)Assigns a new value to the named external variable binding in the current object.
- Parameters
- variable - The name of the variable reference. This can be referred to in the XPath 1.0 expression by prepending the dollar ($) symbol.
- 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().- Throws
ArrayStoreException
- A List was passed in which contains one or more objects which are not of type MbElement.
public void removeAllVariables()Removes the currently assigned values of all the named external variable bindings.
public void removeNamespacePrefix(String prefix)Removes the currently assigned prefix to namespace URI mapping.
- Parameters
- prefix - The prefix to be removed.
public void removeVariable(String variable)Removes the currently assigned value of the named external variable binding.
- Parameters
- variable - The name of the variable to remove.
public void setDefaultNamespace(String uri)Sets the default namespace URI for this XPath 1.0 expression.
- Parameters
- The - default namespace URI.