com.ibm.broker.plugin

Class MbXPath

  • java.lang.Object
    • com.ibm.broker.plugin.MbXPath


  • public class MbXPath
    extends java.lang.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 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().

    Namespace support

    The namespace axis is not implemented exactly according to the W3C recommendation because an XPath 1.0 namespace node is a virtual node generated on the fly during evaluation to represent the namespaces in scope for an element. Since all nodes in this implementation map to an actual MbElement, this concept is not applicable to the broker. The namespace axis in this implementation will return the actual XML namespace declaration nodes for a particular element. This is included to allow users to manipulate XML prefix/URI declarations within an XPath expression.

    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.

    Limitations

    The XPath 1.0 function id() is not supported and, if called, will always return an empty nodeset.

    Broker extensions

    The XPath 1.0 specification allows for an XPath implementation to provide additional functions on top of the compulsory core function library that are useful to the application. For example, XSLT defines extra functions relevant to its usage. The broker's XPath implementation provides the following extra functions for changing the message tree:
    set-local-name(object)
    sets the local part of the expanded-name of the context node to the value specified in the argument. The argument can be any valid expression and will be converted to a string as if by a call to the string function. This function always returns true.
    set-namespace-uri(object)
    sets the namespace URI part of the expanded-name of the context node to the value specified in the argument. The argument can be any valid expression and will be converted to a string as if by a call to the string function. This function always returns true.
    set-value(object)
    sets the string-value of the context node to the value specified in the argument. The argument can be any valid expression and will be converted to a string as if by a call to the string function. This function always returns true.
    To allow for syntax element trees to be built as well as modified, a new axis is supported in addition to the 13 that are defined in the XPath 1.0 specification:
    select-or-create:: (abbreviated form'?')
    This will select child nodes matching the specified nametest or create new nodes according to the following rules:

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

    Notes:
    • The first form will only create a new element if one matching name does not exist. The other forms will always create a new element in the given position regardless of the existence of a matching element.
    • ?name is equivalent to select-or-create::name.
    • If name is @name, an attribute (Name/Value element) will be created/selected.

    Broker XPath examples

    Examples of XPath 1.0 usage can be found in the W3C recommendation as well as numerous books and websites. The expressions presented here demonstrate the extended syntax supported by the broker for modifying messages and creating sub-trees. The examples refer to the following XML document:

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

    ExpressionResultant document
    //price[set-value(. * 2)]

    This expression selects all price descendants of root and doubles their value.
    <example>
      <items>
        <item>
          <price>6.9</price>
        </item>
        <item>
          <price>13.14</price>
        </item>
        <item>
          <price>3.9</price>
        </item>
        <item>
          <price>1</price>
        </item>
      </items>
    </example>
    //price[set-local-name("cost")]

    This expression selects all price descendants of root and changes their name to cost.
    <example>
      <items>
        <item>
          <cost>3.45</cost>
        </item>
        <item>
          <cost>6.57</cost>
        </item>
        <item>
          <cost>1.95</cost>
        </item>
        <item>
          <cost>0.50</cost>
        </item>
      </items>
    </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();
    vars.assign("three", 3);
    List<MbElement> nodeset = (List<MbElement>)message.evaluateXPath(xp, vars);
    <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>
      <item><price>4.5</price></item></items>
    </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>
      <items>
        <item index="1">
          <price>3.45</price>
        </item>
        <item index="2">
          <price>6.57</price>
        </item>
        <item index="3">
          <price>1.95</price>
        </item>
        <item index="4">
          <price>0.50</price>
        </item>
      </items>
    </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>
      <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>
      <total>12.47</total></items>
    </example>
    • Constructor Detail

      • MbXPath

        public MbXPath(java.lang.String expression)
                throws MbException
        Creates an MbXPath object from an XPath 1.0 expression.

        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

        Parameters:
        expression - An XPath 1.0 expression.
        Throws:
        MbException - - An exception was thrown during the compilation of the expression.
      • MbXPath

        public MbXPath(java.lang.String expression,
                       MbNamespaceBindings namespaceBindings)
                throws MbException
        Creates an MbXPath object from an XPath 1.0 expression.

        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

        Parameters:
        expression - An XPath 1.0 expression.
        namespaceBindings - A set of namespace prefix/URI bindings
        Throws:
        MbException - - An exception was thrown during the compilation of the expression.
      • MbXPath

        @Deprecated
        public MbXPath(java.lang.String expression,
                                    MbElement root)
                             throws MbException
        Deprecated. The root element should no longer be set on this object. Instead use setRootElement(rootElement)
        Creates an MbXPath object from an XPath 1.0 expression. The expression may contain external variable bindings. 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. 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.
    • Method Detail

      • setNamespaceBindings

        public void setNamespaceBindings(MbNamespaceBindings namespaceBindings)
        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.
        Parameters:
        namespaceBindings - A set of namespace prefix/URI bindings the expression.
      • assignVariable

        @Deprecated
        public 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)
        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 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().
        Throws:
        java.lang.ArrayStoreException - - A List was passed in which contains one or more objects which are not of type MbElement.
      • assignVariable

        @Deprecated
        public void assignVariable(java.lang.String variable,
                                                double value)
        Deprecated. Variable bindings should no longer be held in this class. Instead use assign(variable, 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 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.
      • assignVariable

        @Deprecated
        public void assignVariable(java.lang.String variable,
                                                boolean value)
        Deprecated. Variable bindings should no longer be held in this class. Instead use assign(variable, 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 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.
      • removeVariable

        @Deprecated
        public void removeVariable(java.lang.String variable)
        Deprecated. Variable bindings should no longer be held in this class. Instead use remove(variable)
        Removes the currently assigned value of the named external variable binding.
        Parameters:
        variable - The name of the variable to remove.
      • removeAllVariables

        @Deprecated
        public void removeAllVariables()
        Deprecated. Variable bindings should no longer be held in this class. Instead use removeAll()
        Removes the currently assigned values of all the named external variable bindings.
      • addNamespacePrefix

        @Deprecated
        public 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)
        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.
      • removeNamespacePrefix

        @Deprecated
        public void removeNamespacePrefix(java.lang.String prefix)
        Deprecated. Namespace bindings should no longer be held directly in this class. Instead use removeBinding(prefix)
        Removes the currently assigned prefix to namespace URI mapping.
        Parameters:
        prefix - The prefix to be removed.
      • setDefaultNamespace

        @Deprecated
        public void setDefaultNamespace(java.lang.String uri)
        Deprecated. Namespace bindings should no longer be held directly in this class. Instead use setDefaultNamespace(uri)
        Sets the default namespace URI for this XPath 1.0 expression.
        Parameters:
        uri - The default namespace URI.
      • clearMbXPath

        public void clearMbXPath()
                          throws MbException
        Deletes the resources associated with the xpath object. Attempting to use the MbXPath object after clearMbXPath has been called will result in indeterminate behavior.
        Throws:
        MbException
IBM Integration BusTM
JavaTM Plugin Node API