com.ibm.broker.plugin

Class MbMessage

  • java.lang.Object
    • com.ibm.broker.plugin.MbMessage
  • Direct Known Subclasses:
    MbMessageCollection


    public class MbMessage
    extends java.lang.Object
    MbMessage represents the message passed between the nodes in a message flow. A message in its raw form is a sequence of bytes known as the wire format. Nodes within the broker will navigate and manipulate the message using a logical format whereby the message is represented as a hierarchical tree of syntax elements. Conversion between these two formats is managed by parsers. Different parsers are invoked by the root parser as required during the parsing of a message. The following diagram shows a typical message.
                     +----+
                     |Root|
                     +----+
                       |   
                       |     
             +---------+-+--------+
             |           |        |
             |           |        |
        +----------+   +----+   +---+
        |Properties|   |MQMD|   |XML|
        +----------+   +----+   +---+
     
    The root parser at the top will invoke the parsers along the bottom in the order shown to parse the bit stream into a syntax element tree. This tree will then have same structure as shown in the diagram with sub-trees off each parser element representing its part of the message. For example the MQMD header is the first sibling of the first child of Root and the MQMD attributes are children of this.

    The syntax element representing the root is returned by getRootElement(). This is an object of type MbElement which contains methods to navigate and modify the tree.

    Warning: caching MbMessage objects over multiple message flow invocations is unsupported because the internal state may be reset at the end of the current message invocation.

    See Also:
    MbElement, "Working with Messages. Appendix A: Message Parsers - element definitions"
    • Constructor Summary

      Constructors 
      Constructor and Description
      MbMessage()
      Default constructor for MbMessage
      MbMessage(MbMessage message)
      Copy constructor for MbMessage.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method and Description
      void clearMessage()
      Deletes the resources associated with the message.
      void clearMessage(boolean deleteRootElement)
      Deletes the resources associated with the message.
      org.w3c.dom.Document createDOMDocument(java.lang.String parserName) 
      java.lang.Object evaluateXPath(MbXPath xpath)
      Evaluates the XPath 1.0 expression with the message body (last child of root) as the context node.
      java.lang.Object evaluateXPath(MbXPath xpath, MbXPathVariables xpathVariables)
      Evaluates the XPath 1.0 expression with the message body (last child of root) as the context node.
      java.lang.Object evaluateXPath(java.lang.String expression)
      Evaluates the XPath 1.0 expression with the message body (last child of root) as the context node.
      java.lang.Object evaluateXPath(java.lang.String expression, MbNamespaceBindings namespaceBindings)
      Evaluates the XPath 1.0 expression with the message body (last child of root) as the context node.
      java.lang.Object evaluateXPath(java.lang.String expression, MbNamespaceBindings namespaceBindings, MbXPathVariables xpathVariables)
      Evaluates the XPath 1.0 expression with the message body (last child of root) as the context node.
      java.lang.Object evaluateXPath(java.lang.String expression, MbXPathVariables xpathVariables)
      Evaluates the XPath 1.0 expression with the message body (last child of root) as the context node.
      void finalizeMessage(int options)
      Causes the broker to request parsers that support the finalize feature to perform their finalize processing on the message.
      byte[] getBuffer()
      Get a copy of the data buffer associated with (and owned by) the message object.
      org.w3c.dom.Document getDOMDocument()
      Returns the message body (last child of root) as an instance of the org.w3c.dom.Document interface
      org.w3c.dom.Document getDOMDocument(boolean emptyStringForNull)
      Returns the message body (last child of root) as an instance of the org.w3c.dom.Document interface.
      MbElement getRootElement()
      Get the root syntax element associated with the message.
      boolean isReadOnly()
      Return true if the message is read only.
      java.lang.String toString()
      Returns a String representation of the MbMessage.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • MbMessage

        public MbMessage(MbMessage message)
                  throws MbException
        Copy constructor for MbMessage. An MbMessage object can only be created based on an existing message.
        Throws:
        MbException
    • Method Detail

      • isReadOnly

        public boolean isReadOnly()
        Return true if the message is read only.
        Returns:
        True if read only.
      • clearMessage

        public void clearMessage()
                          throws MbException
        Deletes the resources associated with the message. Propagating the message or referencing it after clearMessage has been called will result in indeterminate behavior.
        Throws:
        MbException
      • clearMessage

        public void clearMessage(boolean deleteRootElement)
                          throws MbException
        Deletes the resources associated with the message. Propagating the message or referencing it after clearMessage has been called will result in indeterminate behavior.
        Parameters:
        deleteRootElement - indicates if the root element for this message is also to be deleted
        Throws:
        MbException
      • finalizeMessage

        public void finalizeMessage(int options)
                             throws MbException
        Causes the broker to request parsers that support the finalize feature to perform their finalize processing on the message. The behavior of this processing is specific to each parser.

        Of the options parameter is set to FINALIZE_VALIDATE, a parser should also perform validation processing to ensure that the element tree owned by it is of the correct structure. This helps prevent messages with incorrectly formed element trees being propagated to other nodes in the message flow.

        It is recommended that finalizeMessage is called prior to propagating a message.

        Parameters:
        options - The options governing the method. Acceptable values are: FINALIZE_NONE FINALIZE_VALIDATE
        Throws:
        MbException
      • getBuffer

        public byte[] getBuffer()
                         throws MbException
        Get a copy of the data buffer associated with (and owned by) the message object. Causes the syntax element tree associated with the message to be written to the data buffer owned by that message object. This operation serializes the element tree into a bit stream, which is then returned as a sequence of contiguous bytes. This method should be used when writing the bitsream to a target that is outside the broker (that is, when writing a user-defined output node).
        Returns:
        The byte array containing the message buffer.
        Throws:
        MbException
      • getRootElement

        public MbElement getRootElement()
                                 throws MbException
        Get the root syntax element associated with the message. When a message object is constructed by the broker, a root element is automatically created.
        Returns:
        MbElement representing the root element.
        Throws:
        MbException
      • evaluateXPath

        public java.lang.Object evaluateXPath(java.lang.String expression)
                                       throws MbException
        Evaluates the XPath 1.0 expression with the message body (last child of root) as the context node. The return type depends on the expression and can be one of:
        • Boolean
        • Double
        • String
        • java.util.List of MbElement objects representing an XPath 1.0 nodeset
        Parameters:
        expression - The XPath 1.0 expression.
        Throws:
        MbException - - An exception was thrown during the compilation of the expression.
      • evaluateXPath

        public java.lang.Object evaluateXPath(java.lang.String expression,
                                              MbNamespaceBindings namespaceBindings)
                                       throws MbException
        Evaluates the XPath 1.0 expression with the message body (last child of root) as the context node. The return type depends on the expression and can be one of:
        • Boolean
        • Double
        • String
        • java.util.List of MbElement objects representing an XPath 1.0 nodeset
        If the expression contains location steps with namespace prefixes, the mapping of these prefixes to namespace URIs must be supplied. This is done with the namespaceBindings parameter. The MbNamespaceBindings object must have an entry for each prefix used in the XPath expression.
        Parameters:
        expression - The XPath 1.0 expression.
        namespaceBindings - Associated object containing the namespace prefix to URI mappings for this expression.
        Throws:
        MbException - - An exception was thrown during the compilation of the expression.
      • evaluateXPath

        public java.lang.Object evaluateXPath(java.lang.String expression,
                                              MbXPathVariables xpathVariables)
                                       throws MbException
        Evaluates the XPath 1.0 expression with the message body (last child of root) as the context node. The return type depends on the expression and can be one of:
        • Boolean
        • Double
        • String
        • java.util.List of MbElement objects representing an XPath 1.0 nodeset
        If the expression contains variable references, these variables must be assigned values. This is done with the xpathVariables parameter. The MbXPathVariables object must have an entry for each variable used in the XPath expression.
        Parameters:
        expression - The XPath 1.0 expression.
        xpathVariables - Associated object containing the variable bindings for this expression.
        Throws:
        MbException - - An exception was thrown during the compilation of the expression.
      • evaluateXPath

        public java.lang.Object evaluateXPath(java.lang.String expression,
                                              MbNamespaceBindings namespaceBindings,
                                              MbXPathVariables xpathVariables)
                                       throws MbException
        Evaluates the XPath 1.0 expression with the message body (last child of root) as the context node. The return type depends on the expression and can be one of:
        • Boolean
        • Double
        • String
        • java.util.List of MbElement objects representing an XPath 1.0 nodeset
        If the expression contains location steps with namespace prefixes, the mapping of these prefixes to namespace URIs must be supplied. This is done with the namespaceBindings parameter. The MbNamespaceBindings object must have an entry for each prefix used in the XPath expression.

        If the expression contains variable references, these variables must be assigned values. This is done with the xpathVariables parameter. The MbXPathVariables object must have an entry for each variable used in the XPath expression.

        Parameters:
        expression - The XPath 1.0 expression.
        namespaceBindings - Associated object containing the namespace prefix to URI mappings for this expression.
        xpathVariables - Associated object containing the variable bindings for this expression.
        Throws:
        MbException - - An exception was thrown during the compilation of the expression.
      • evaluateXPath

        public java.lang.Object evaluateXPath(MbXPath xpath)
                                       throws MbException
        Evaluates the XPath 1.0 expression with the message body (last child of root) as the context node. The return type depends on the expression and can be one of:
        • Boolean
        • Double
        • String
        • java.util.List of MbElement objects representing an XPath 1.0 nodeset
        Parameters:
        xpath - The MbXPath object representing the XPath 1.0 expression.
        Throws:
        MbException - - An exception was thrown during the compilation of the expression.
      • evaluateXPath

        public java.lang.Object evaluateXPath(MbXPath xpath,
                                              MbXPathVariables xpathVariables)
                                       throws MbException
        Evaluates the XPath 1.0 expression with the message body (last child of root) as the context node. The return type depends on the expression and can be one of:
        • Boolean
        • Double
        • String
        • java.util.List of MbElement objects representing an XPath 1.0 nodeset
        If the expression contains variable references, these variables must be assigned values. This is done with the xpathVariables parameter. The MbXPathVariables object must have an entry for each variable used in the XPath expression.
        Parameters:
        xpath - The MbXPath object representing the XPath 1.0 expression.
        xpathVariables - Associated object containing the variable bindings for this expression.
        Throws:
        MbException - - An exception was thrown during the compilation of the expression.
      • getDOMDocument

        public org.w3c.dom.Document getDOMDocument()
                                            throws MbException
        Returns the message body (last child of root) as an instance of the org.w3c.dom.Document interface
        Throws:
        MbException
      • getDOMDocument

        public org.w3c.dom.Document getDOMDocument(boolean emptyStringForNull)
                                            throws MbException
        Returns the message body (last child of root) as an instance of the org.w3c.dom.Document interface.
        Parameters:
        emptyStringForNull - indicates the null element value to be returned as empty string.
        Throws:
        MbException
      • createDOMDocument

        public org.w3c.dom.Document createDOMDocument(java.lang.String parserName)
                                               throws MbException
        Throws:
        MbException
      • toString

        public java.lang.String toString()
        Returns a String representation of the MbMessage.
        Overrides:
        toString in class java.lang.Object
        Returns:
        String representing the message.
IBM Integration BusTM
JavaTM Plugin Node API