Class Hierarchy All Classes All Fields and Methods

Class com.ibm.broker.plugin.MbElement

java.lang.Object
        com.ibm.broker.plugin.MbElement

public class MbElement
extends Object

MbElement represents the syntax elements in the logical (hierarchical) view of the message. Methods are provided for navigating and modifying the hierarchy.

                           getParent
                                ^
                                |
                         +-------------+
                         |             |  
 getPreviousSibling <--|  MbElement  |--> getNextSibling
                         |             |  
                         +-------------+
                            |       |
                            v       v
                getFirstChild   getLastChild
 
When creating a new message from scratch, it is important that the parser-owning folders (elements whose parent is the root element) are created using only the following methods passing in the parser name as the argument: Children of these folders should be created with the other create methods only.

Field Index
Field Description
TYPE_NAME A name element has associated with it a string, which is the name of the element.
TYPE_NAME_VALUE A name-value element is an optimization of the case where a name element contains only a value element and nothing else.
TYPE_UNKNOWN The element type is undefined.
TYPE_VALUE A value element has a value associated with it.
VALUE_STATE_INVALID Returned by getValueState.
VALUE_STATE_UNDEFINED Returned by getValueState.
VALUE_STATE_VALID Returned by getValueState.
Method Index
Method Description
void addAfter(MbElement) Adds an unattached syntax element after this element.
void addAsFirstChild(MbElement) Adds an unattached syntax element as the first of this element.
void addAsLastChild(MbElement) Adds an unattached syntax element as the last of this element.
void addBefore(MbElement) Adds an unattached syntax element before this element.
MbElement copy()  
void copyElementTree(MbElement) Copies the element tree from the element passed as an argument to the current element.
MbElement createElementAfter(int) Creates a new syntax element and inserts it after this element.
MbElement createElementAfter(int, String, Object) Creates a new syntax element and inserts it after this element.
MbElement createElementAfter(String) Creates a new syntax element, inserts it after this element, and associates it with the specified parser class name.
MbElement createElementAsFirstChild(int) Creates a new syntax element as the first child of this element.
MbElement createElementAsFirstChild(int, String, Object) Creates a new syntax element as the first child of this element.
MbElement createElementAsFirstChild(String) Creates a new syntax element as the first child of this element, and associates it with the specified parser class name.
MbElement createElementAsLastChild(int) Creates a new syntax element as the last child of this element.
MbElement createElementAsLastChild(int, String, Object) Creates a new syntax element as the last child of this element.
MbElement createElementAsLastChild(String) Creates a new syntax element as the last child of this element, and associates it with the specified parser class name.
MbElement createElementAsLastChildFromBitstream(byte[], String, String, String, String, int, int, int) Creates a new syntax element tree as the last child of this element, and associates it with the specified parser.
MbElement createElementBefore(int) Creates a new syntax element and inserts it before this element.
MbElement createElementBefore(int, String, Object) Creates a new syntax element and inserts it before this element.
MbElement createElementBefore(String) Creates a new syntax element, inserts it before this element, and associates it with the specified parser class name.
void detach() Detaches this element from the syntax element tree.
Object evaluateXPath(MbXPath) Evaluates the XPath 1.0 expression with the current element as the context node.
Object evaluateXPath(String) Evaluates the XPath 1.0 expression with the current element as the context node.
MbElement[] getAllElementsByPath(String) Deprecated. Path selection should be done using the XPath 1.0 methods.
MbElement getFirstChild() Returns the syntax element representing the first child of this element.
MbElement getFirstElementByPath(String) Gets the first element matching the path specification.
MbElement getLastChild() Returns the syntax element representing the last child of this element.
String getName() Returns the name of the element.
String getNamespace() Returns the namespace URI of the element.
MbElement getNextSibling() Returns the syntax element representing the next sibling (right sibling) of this element.
MbElement getParent() Returns the syntax element representing the parent of this element.
String getParserClassName() Gets the name of the parser associated with the element.
int getParserContext() Deprecated. getSpecificType should be used instead.
MbElement getPreviousSibling() Returns the syntax element representing the previous sibling (left sibling) of this element.
int getSpecificType() Returns the full type information of this element including the parser specific type.
int getType() Gets the generic type of the element.
Object getValue() Gets the value of the element as a java Object.
int getValueState() Gets the state of the value of the element.
boolean is(MbElement) is: Returns true if the MbElement actually refers to the same element in the logical message tree.
void setName(String) Sets the name of the element, any previous name is overwritten.
void setNamespace(String) Sets the namespace URI of the element, any previous namespace is overwritten.
void setSpecificType(int) Sets the full type information for this element including the parser specific type.
void setValue(Object) Sets the value of the element as a java Object.
byte[] toBitstream(String, String, String, int, int, int) Returns the bit stream representation of the element.
String toString() Returns a String representation of the MbElement.

Fields

TYPE_NAME

public static final int TYPE_NAME

A name element has associated with it a string, which is the name of the element.

TYPE_NAME_VALUE

public static final int TYPE_NAME_VALUE

A name-value element is an optimization of the case where a name element contains only a value element and nothing else. The element contains both a name and value.

TYPE_UNKNOWN

public static final int TYPE_UNKNOWN

The element type is undefined.

TYPE_VALUE

public static final int TYPE_VALUE

A value element has a value associated with it.

VALUE_STATE_INVALID

public static final int VALUE_STATE_INVALID

Returned by getValueState. Indicates the value is invalid.

VALUE_STATE_UNDEFINED

public static final int VALUE_STATE_UNDEFINED

Returned by getValueState. Indicates the value is undefined.

VALUE_STATE_VALID

public static final int VALUE_STATE_VALID

Returned by getValueState. Indicates the value is valid.

Methods

addAfter

public void addAfter(MbElement element) throws MbException

Adds an unattached syntax element after this element. The currently unattached syntax element, and any child elements it might possess, is connected to the syntax element tree after the target (this) element. The newly added element becomes the next sibling of this element. The target (this) element must be attached to a tree (that is, it must have a parent element).

addAsFirstChild

public void addAsFirstChild(MbElement element) throws MbException

Adds an unattached syntax element as the first of this element. The currently unattached syntax element, and any child elements it might possess, is connected to the syntax element tree as the first child of the target (this) element. The target (this) element need not be attached.

addAsLastChild

public void addAsLastChild(MbElement element) throws MbException

Adds an unattached syntax element as the last of this element. The currently unattached syntax element, and any child elements it might possess, is connected to the syntax element tree as the last child of the target (this) element. The target (this) element need not be attached.

addBefore

public void addBefore(MbElement element) throws MbException

Adds an unattached syntax element before this element. The currently unattached syntax element, and any child elements it might possess, is connected to the syntax element tree before the target (this) element. The newly added element becomes the previous sibling of this element. The target (this) element must be attached to a tree (that is, it must have a parent element).

copy

public MbElement copy() throws MbException

copyElementTree

public void copyElementTree(MbElement element) throws MbException

Copies the element tree from the element passed as an argument to the current element. Only the child elements of the source element are copied. Before the copy is performed, all existing child elements of the target (this) element are deleted, to be replaced by the child elements of the source element.

createElementAfter

public MbElement createElementAfter(int type) throws MbException

Creates a new syntax element and inserts it after this element. The new element becomes the next sibling of this element and shares the same parent. Do not use this method when creating a message body folder (such as XML, XMLNS, MRM, BLOB). This method should be used only when the message body folder has been created. To create the message body folder, use createElementAfter

createElementAfter

public MbElement createElementAfter(int type,
                                    String name,
                                    Object value) throws MbException

Creates a new syntax element and inserts it after this element. The new element becomes the next sibling of this element and shares the same parent. Do not use this method when creating a message body folder (such as XML, XMLNS, MRM, BLOB). This method should be used only when the message body folder has been created. To create the message body folder, use createElementAfter

createElementAfter

public MbElement createElementAfter(String parserName) throws MbException

Creates a new syntax element, inserts it after this element, and associates it with the specified parser class name. The new element becomes the next sibling of this element and shares the same parent.

The portion of the syntax element tree that is owned by the parser may only have its effective root at the first generation of elements (that is, as immediate children of root). The user-defined node interface does not restrict the ability to create a subtree that appears to be owned by a different parser. However, it is not possible to serialize these element trees into a bit stream when outputting a message.

createElementAsFirstChild

public MbElement createElementAsFirstChild(int type) throws MbException

Creates a new syntax element as the first child of this element. Do not use this method when creating a message body folder (such as XML, XMLNS, MRM, BLOB). This method should be used only when the message body folder has been created. To create the message body folder, use createElementAsFirstChild

createElementAsFirstChild

public MbElement createElementAsFirstChild(int type,
                                           String name,
                                           Object value) throws MbException

Creates a new syntax element as the first child of this element. Do not use this method when creating a message body folder (such as XML, XMLNS, MRM, BLOB). This method should be used only when the message body folder has been created. To create the message body folder, use createElementAsFirstChild

createElementAsFirstChild

public MbElement createElementAsFirstChild(String parserName) throws MbException

Creates a new syntax element as the first child of this element, and associates it with the specified parser class name.

The portion of the syntax element tree that is owned by the parser may only have its effective root at the first generation of elements (that is, as immediate children of root). The user-defined node interface does not restrict the ability to create a subtree that appears to be owned by a different parser. However, it is not possible to serialize these element trees into a bit stream when outputting a message.

createElementAsLastChild

public MbElement createElementAsLastChild(int type) throws MbException

Creates a new syntax element as the last child of this element. Do not use this method when creating a message body folder (such as XML, XMLNS, MRM, BLOB). This method should be used only when the message body folder has been created. To create the message body folder, use createElementAsLastChild

createElementAsLastChild

public MbElement createElementAsLastChild(int type,
                                          String name,
                                          Object value) throws MbException

Creates a new syntax element as the last child of this element. Do not use this method when creating a message body folder (such as XML, XMLNS, MRM, BLOB). This method should be used only when the message body folder has been created. To create the message body folder, use createElementAsLastChild

createElementAsLastChild

public MbElement createElementAsLastChild(String parserName) throws MbException

Creates a new syntax element as the last child of this element, and associates it with the specified parser class name.

The portion of the syntax element tree that is owned by the parser may only have its effective root at the first generation of elements (that is, as immediate children of root). The user-defined node interface does not restrict the ability to create a subtree that appears to be owned by a different parser. However, it is not possible to serialize these element trees into a bit stream when outputting a message.

createElementAsLastChildFromBitstream

public MbElement createElementAsLastChildFromBitstream(byte[] bitstream,
                                                       String parserName,
                                                       String messageType,
                                                       String messageSet,
                                                       String messageFormat,
                                                       int encoding,
                                                       int ccsid,
                                                       int options) throws MbException

Creates a new syntax element tree as the last child of this element, and associates it with the specified parser. The new syntax element tree is populated by parsing the specified bit stream. This method can only be used to create a message body i.e. last child of message root.

createElementBefore

public MbElement createElementBefore(int type) throws MbException

Creates a new syntax element and inserts it before this element. The new element becomes the previous sibling of this element and shares the same parent. Do not use this method when creating a message body folder (such as XML, XMLNS, MRM, BLOB). This method should be used only when the message body folder has been created. To create the message body folder, use createElementBefore

createElementBefore

public MbElement createElementBefore(int type,
                                     String name,
                                     Object value) throws MbException

Creates a new syntax element and inserts it before this element. The new element becomes the previous sibling of this element and shares the same parent. Do not use this method when creating a message body folder (such as XML, XMLNS, MRM, BLOB). This method should be used only when the message body folder has been created. To create the message body folder, use createElementBefore

createElementBefore

public MbElement createElementBefore(String parserName) throws MbException

Creates a new syntax element, inserts it before this element, and associates it with the specified parser class name. The new element becomes the previous sibling of this element and shares the same parent.

The portion of the syntax element tree that is owned by the parser may only have its effective root at the first generation of elements (that is, as immediate children of root). The user-defined node interface does not restrict the ability to create a subtree that appears to be owned by a different parser. However, it is not possible to serialize these element trees into a bit stream when outputting a message.

detach

public void detach() throws MbException

Detaches this element from the syntax element tree. The element is detached from its parent and siblings, but any child elements are left attached. Calling detach on the root element of a message or an element that is already detached will have no effect.

evaluateXPath

public Object evaluateXPath(MbXPath xpath) throws MbException

Evaluates the XPath 1.0 expression with the current element as the context node. The return type depends on the expression and can be one of:

evaluateXPath

public Object evaluateXPath(String expression) throws MbException

Evaluates the XPath 1.0 expression with the current element as the context node. The return type depends on the expression and can be one of:

This is a convenience method for evaluateXPath(new MbXPath(expression));

getAllElementsByPath

Deprecated. Path selection should be done using the XPath 1.0 methods.

public MbElement[] getAllElementsByPath(String path) throws MbException

Get all the elements matching the path specification

The path is a list of steps separated by a slash '/' character. Each step moves the selection pointer further into the element tree using the following rules:
nameselects all children of the current element whose name attribute is name.
*selects all children of the current element.
.selects the current element.
..selects the parent of the current element.

The steps can also be separated by a double slash ('//'), which causes all descendants of the current node to be searched rather than just the children. Descendants are children, children of children and so on.

Paths are relative to the current element unless they start with a /, in which case they are absolute (that is, they are relative to the root element of the message).

Examples: (click on (xml...) to show the result on an XML message)
item selects all the child elements named 'item' of the current element. (xml...)
order/item selects all grandchildren named 'item' that have a parent named 'order'. (xml...)
../item selects all siblings named 'item' (children of the parent). (xml...)
order//item selects all 'item' descendants of all children named 'order'. (xml...)
order/* selects all the children of all children named 'order'. (xml...)
//item selects all elements named 'item' in the whole message. (xml...)
.//item selects all elements named 'item' which are descendants of the current element. (xml...)
/MQMD/ReplyToQselect the element representing the reply-to queue in the MQMD header.

getFirstChild

public MbElement getFirstChild() throws MbException

Returns the syntax element representing the first child of this element.

getFirstElementByPath

public MbElement getFirstElementByPath(String path) throws MbException

Gets the first element matching the path specification.

The format of the path specification is the same as that described in getAllElementsByPath except that the descendant separator ('//') is not supported. This method returns the first element matched by the path specification only and is intended for use when you know the exact unique path to an element in the tree. In this case, this method is far more efficient than calling getAllElementsByPath and selecting the first element from the array.

Example paths:
item select the first child element named 'item' of the current element.
/MQMD/ReplyToQselect the element representing the reply-to queue in the MQMD header.

getLastChild

public MbElement getLastChild() throws MbException

Returns the syntax element representing the last child of this element.

getName

public String getName() throws MbException

Returns the name of the element.

getNamespace

public String getNamespace() throws MbException

Returns the namespace URI of the element.

getNextSibling

public MbElement getNextSibling() throws MbException

Returns the syntax element representing the next sibling (right sibling) of this element.

getParent

public MbElement getParent() throws MbException

Returns the syntax element representing the parent of this element.

getParserClassName

public String getParserClassName() throws MbException

Gets the name of the parser associated with the element.

getParserContext

Deprecated. getSpecificType should be used instead.

public int getParserContext() throws MbException

Gets parser specific information for this element. In the 'C' interface this is refered to as the Specific Type.

getPreviousSibling

public MbElement getPreviousSibling() throws MbException

Returns the syntax element representing the previous sibling (left sibling) of this element.

getSpecificType

public int getSpecificType() throws MbException

Returns the full type information of this element including the parser specific type.

getType

public int getType() throws MbException

Gets the generic type of the element. Values are:

getValue

public Object getValue() throws MbException

Gets the value of the element as a java Object. This can be one of the types:

getValueState

public int getValueState() throws MbException

Gets the state of the value of the element. Return values are:

is

public boolean is(MbElement comparisonElement) 

is: Returns true if the MbElement actually refers to the same element in the logical message tree.

setName

public void setName(String name) throws MbException

Sets the name of the element, any previous name is overwritten.

setNamespace

public void setNamespace(String namespace) throws MbException

Sets the namespace URI of the element, any previous namespace is overwritten.

setSpecificType

public void setSpecificType(int type) throws MbException

Sets the full type information for this element including the parser specific type. Knowledge of type values for the parser is required to use this method. Type values for the generic XML parsers are given in the MbXML, MbXMLNS and MbXMLNSC classes.

setValue

public void setValue(Object value) throws MbException

Sets the value of the element as a java Object. This can be one of the types:

An exception is thrown if the Object is not one of these types. An exception is also thrown if a BigDecimal value with more than 31 significant figures is passed into this method. The user should use one of the BigDecimal's rounding modes if necessary to avoid this.

toBitstream

public byte[] toBitstream(String messageType,
                          String messageSet,
                          String messageFormat,
                          int encoding,
                          int ccsid,
                          int options) throws MbException

Returns the bit stream representation of the element. This method causes the parser associated with the element to serialize the element and all its children. This method can only be called on the message body, i.e. the last child of the message root.

toString

public String toString() 

Returns a String representation of the MbElement. This string is for debug use only; its format is not guaranteed to stay the same between releases.

Class Hierarchy All Classes All Fields and Methods