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 getLastChildFurther information on the syntax element structure can be found in the Programming Guide chapter 6 section 'The logical message model'.
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 | 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) | Deprecated. Path selection should be done using the XPath 1.0 methods. |
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 bitstream representation of the element. |
String toString() | Returns a String representation of the MbElement. |
public static final int TYPE_NAMEA name element has associated with it a string, which is the name of the element.
public static final int TYPE_NAME_VALUEA 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.
public static final int TYPE_UNKNOWNThe element type is undefined.
public static final int TYPE_VALUEA value element has a value associated with it.
public static final int VALUE_STATE_INVALIDReturned by getValueState. Indicates the value is invalid.
public static final int VALUE_STATE_UNDEFINEDReturned by getValueState. Indicates the value is undefined.
public static final int VALUE_STATE_VALIDReturned by getValueState. Indicates the value is valid.
public void addAfter(MbElement element) throws MbExceptionAdds 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).
- Parameters
- element - The currenly unattached element to be added.
- Throws
public void addAsFirstChild(MbElement element) throws MbExceptionAdds 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.
- Parameters
- element - The currenly unattached element to be added.
- Throws
public void addAsLastChild(MbElement element) throws MbExceptionAdds 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.
- Parameters
- element - The currenly unattached element to be added.
- Throws
public void addBefore(MbElement element) throws MbExceptionAdds 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).
- Parameters
- element - The currenly unattached element to be added.
- Throws
public MbElement copy() throws MbException
public void copyElementTree(MbElement element) throws MbExceptionCopies 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 tthe 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.
- Parameters
- element - Source element for copy.
- Throws
public MbElement createElementAfter(int type) throws MbExceptionCreates 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.
- Parameters
- type - The type of syntax element to be created. Must be one of:
TYPE_NAME
TYPE_VALUE
TYPE_NAME_VALUE
- Returns
- The new element.
- Throws
public MbElement createElementAfter(int type, String name, Object value) throws MbExceptionCreates 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.
- Parameters
- type - The type of syntax element to be created. This must be one of:
TYPE_NAME
TYPE_VALUE
TYPE_NAME_VALUE
- name - The name of the new element.
- value - The value of the new element as a Java Object. This must be one of the types:
MbDate
MbTime
MbTimestamp
Boolean
byte[]
String
Integer
Double
Float
BitSet
- Returns
- The new element.
- Throws
public MbElement createElementAfter(String parserName) throws MbExceptionCreates 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.
In WebSphere MQ Integrator Version 2, a 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 plug-in 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 bitstream when outputting a message.
- Parameters
- parserName - The name of the parser class.
- Returns
- The new element.
- Throws
public MbElement createElementAsFirstChild(int type) throws MbExceptionCreates a new syntax element as the first child of this element.
- Parameters
- type - The type of syntax element to be created. Must be one of:
TYPE_NAME
TYPE_VALUE
TYPE_NAME_VALUE
- Returns
- The new element.
- Throws
public MbElement createElementAsFirstChild(int type, String name, Object value) throws MbExceptionCreates a new syntax element as the first child of this element.
- Parameters
- type - The type of syntax element to be created. Must be one of:
TYPE_NAME
TYPE_VALUE
TYPE_NAME_VALUE
- name - The name of the new element.
- value - The value of the new element as a Java Object. This must be one of the types:
MbDate
MbTime
MbTimestamp
Boolean
byte[]
String
Integer
Double
Float
BitSet
- Returns
- The new element.
- Throws
public MbElement createElementAsFirstChild(String parserName) throws MbExceptionCreates a new syntax element as the first child of this element, and associates it with the specified parser class name.
In WebSphere MQ Integrator Version 2, a 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 plug-in 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 bitstream when outputting a message.
- Parameters
- parserName - The name of the parser class.
- Returns
- The new element.
- Throws
public MbElement createElementAsLastChild(int type) throws MbExceptionCreates a new syntax element as the last child of this element.
- Parameters
- type - The type of syntax element to be created. Must be one of:
TYPE_NAME
TYPE_VALUE
TYPE_NAME_VALUE
- Returns
- The new element.
- Throws
public MbElement createElementAsLastChild(int type, String name, Object value) throws MbExceptionCreates a new syntax element as the last child of this element.
- Parameters
- type - The type of syntax element to be created. Must be one of:
TYPE_NAME
TYPE_VALUE
TYPE_NAME_VALUE
- name - The name of the new element.
- value - The value of the new element as a Java Object. This must be one of the types:
MbDate
MbTime
MbTimestamp
Boolean
byte[]
String
Integer
Double
Float
BitSet
- Returns
- The new element.
- Throws
public MbElement createElementAsLastChild(String parserName) throws MbExceptionCreates a new syntax element as the last child of this element, and associates it with the specified parser class name.
In WebSphere MQ Integrator Version 2, a 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 plug-in 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 bitstream when outputting a message.
- Parameters
- parserName - The name of the parser class.
- Returns
- The new element.
- Throws
public MbElement createElementAsLastChildFromBitstream(byte[] bitstream, String parserName, String messageType, String messageSet, String messageFormat, int encoding, int ccsid, int options) throws MbExceptionCreates 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 bitstream. This method can only be used to create a message body i.e. last child of message root.
- Parameters
- bitstream - The bitstream to be parsed and added to the element tree.
- parserName - The name of the parser class to use to parse the bitstream. The same parser must be used to parse the whole bitstream.
- messageType - The message type definition used to create the element tree from the bitstream. A value of null will cause this parameter to be ignored.
- messageSet - The message set definition used to create the element tree from the bitstream. A value of null will cause this parameter to be ignored.
- messageFormat - The message format definition used to create the element tree from the bitstream. A value of null will cause this parameter to be ignored.
- encoding - The encoding to use when parsing the bitstream. A special value of 0 may be supplied to indicate that the queue manager's encoding should be used.
- ccsid - The coded character set identifier to use when parsin g the bitstream. This parameter is mandatory. A special value of 0 may be supplied to indicate that the queue manager's ccsid should be used.
- options - Ignored. This is a place holder for future enhancements.
public MbElement createElementBefore(int type) throws MbExceptionCreates 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.
- Parameters
- type - The type of syntax element to be created. Must be one of:
TYPE_NAME
TYPE_VALUE
TYPE_NAME_VALUE
- Returns
- The new element.
- Throws
public MbElement createElementBefore(int type, String name, Object value) throws MbExceptionCreates 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.
- Parameters
- type - The type of syntax element to be created. This must be one of:
TYPE_NAME
TYPE_VALUE
TYPE_NAME_VALUE
- name - The name of the new element.
- value - The value of the new element as a Java Object. This must be one of the types:
MbDate
MbTime
MbTimestamp
Boolean
byte[]
String
Integer
Double
Float
BitSet
- Returns
- The new element.
- Throws
public MbElement createElementBefore(String parserName) throws MbExceptionCreates 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.
In WebSphere MQ Integrator Version 2, a 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 plug-in 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 bitstream when outputting a message.
- Parameters
- parserName - The name of the parser class.
- Returns
- The new element.
- Throws
public void detach() throws MbExceptionDetaches this element from the syntax element tree. The element is detached from its parent ans 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.
- Throws
public Object evaluateXPath(MbXPath xpath) throws MbExceptionEvaluates 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:
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.
public Object evaluateXPath(String expression) throws MbExceptionEvaluates 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));
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.
Deprecated. Path selection should be done using the XPath 1.0 methods.
public MbElement[] getAllElementsByPath(String path) throws MbExceptionGet 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:
name selects 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/ReplyToQ
select the element representing the reply-to queue in the MQMD header.
- Returns
- An array of all elements matched by the path specification.
- Throws
public MbElement getFirstChild() throws MbExceptionReturns the syntax element representing the first child of this element.
- Returns
- The first child of the element.
- Throws
Deprecated. Path selection should be done using the XPath 1.0 methods.
public MbElement getFirstElementByPath(String path) throws MbExceptionGets 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/ReplyToQ
select the element representing the reply-to queue in the MQMD header.
- Returns
- The element specified by the path
- Throws
public MbElement getLastChild() throws MbExceptionReturns the syntax element representing the last child of this element.
- Returns
- The last child of the element.
- Throws
public String getName() throws MbExceptionReturns the name of the element.
- Returns
- The name of the element.
- Throws
public String getNamespace() throws MbExceptionReturns the namespace URI of the element.
- Returns
- The namespace URI of the element.
- Throws
public MbElement getNextSibling() throws MbExceptionReturns the syntax element representing the next sibling (right sibling) of this element.
- Returns
- The next sibling MbElement.
- Throws
public MbElement getParent() throws MbExceptionReturns the syntax element representing the parent of this element.
- Returns
- The parent
MbElement
- Throws
MbException.
public String getParserClassName() throws MbExceptionGets the name of the parser associated with the element.
- Returns
- The name of the parser, or null of there is no associated parser.
- Throws
Deprecated. getSpecificType should be used instead.
public int getParserContext() throws MbExceptionGets parser specific information for this element. In the 'C' interface this is refered to as the Specific Type.
- Returns
- Parser specific information for this element
- Throws
public MbElement getPreviousSibling() throws MbExceptionReturns the syntax element representing the previous sibling (left sibling) of this element.
- Returns
- The previous sibling MbElement.
- Throws
public int getSpecificType() throws MbExceptionReturns the full type information of this element including the parser specific type.
- Returns
- The full parser specific type of this element
- Throws
public int getType() throws MbExceptionGets the generic type of the element. Values are:
TYPE_NAME
TYPE_VALUE
TYPE_NAME_VALUE
TYPE_UNKNOWN
- Returns
- Element type.
- Throws
public Object getValue() throws MbExceptionGets the value of the element as a java Object. This can be one of the types:
MbDate
MbTime
MbTimestamp
Boolean
byte[]
String
Integer
32-bit values.Long
64-bit values.Double
BigDecimal
BitSet
- Returns
- Java object representing the value of the element.
- Throws
public int getValueState() throws MbExceptionGets the state of the value of the element. Return values are:
VALUE_STATE_UNDEFINED
VALUE_STATE_VALID
VALUE_STATE_INVALID
- Returns
- The state of the value.
- Throws
public boolean is(MbElement comparisonElement)is: Returns true if the MbElement actually refers to the same element in the logical message tree.
- Parameters
- comparisonElement - The element being compared.
- Returns
- The boolean indicating if they are the same.
public void setName(String name) throws MbExceptionSets the name of the element, any previous name is overwritten.
- Parameters
- name - The new name of the element.
- Throws
public void setNamespace(String namespace) throws MbExceptionSets the namespace URI of the element, any previous namespace is overwritten.
- Parameters
- name - The new namespace URI of the element.
- Throws
public void setSpecificType(int type) throws MbExceptionSets 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 and MRM parsers are listed in the Information Center under 'XML and MRM parser constants'.
- Parameters
- type - The full parser specific type for this element
- Throws
public void setValue(Object value) throws MbExceptionSets 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.
MbDate
MbTime
MbTimestamp
Boolean
byte[]
String
Integer
32-bit values.Long
64-bit values.Double
BigDecimal
BitSet
- Parameters
- value - The java Object representing the value of the element.
- Throws
public byte[] toBitstream(String messageType, String messageSet, String messageFormat, int encoding, int ccsid, int options) throws MbExceptionReturns the bitstream 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.
- Parameters
- messageType - The message type definition used to create the bitstream from the element tree. A value of null will cause this parameter to be ignored.
- messageSet - The message set definition used to create the bitstream from the element tree. A value of null will cause this parameter to be ignored.
- messageFormat - The message format definition used to create the bitstream from the element tree. A value of null will cause this parameter to be ignored.
- encoding - The encoding to use when writing the bitstream. A special value of 0 may be supplied to indicate that the queue manager's encoding should be used.
- ccsid - The coded character set identifier to use when writing the bitstream. A special value of 0 may be supplied to indicate that the queue manager's ccsid should be used. A ccsid of -1 indicates that the bitstream is to be generated using ccsid information contained in the subtree consisting of the field pointed to by the element and its children. Currently no parsers support this option.
- options - Ignored. This is a place holder for future enhancements.
- Returns
- The message bitstream.
public String toString()Returns a String representation of the MbElement.
- Returns
- String representing the element.
- Overrides
- toString in class Object