public class MbElement extends Object
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:getParent()
^ | +-------------+ | |getPreviousSibling()
<--| MbElement |-->getNextSibling()
| | +-------------+ | | v vgetFirstChild()
getLastChild()
createElementAfter(parserName)
createElementBefore(parserName)
createElementAsLastChild(parserName)
createElementAsFirstChild(parserName)
createElementAsLastChildFromBitstream()
Warning: caching MbElement objects over multiple message flow invocations is unsupported because the internal state may be reset at the end of the current message invocation.
Modifier and Type | Field and Description |
---|---|
static int |
TYPE_NAME
A name element has associated with it a string, which is the name of
the element.
|
static 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.
|
static int |
TYPE_UNKNOWN
The element type is undefined.
|
static int |
TYPE_VALUE
A value element has a value associated with it.
|
static int |
VALUE_STATE_INVALID
Returned by
getValueState() . |
static int |
VALUE_STATE_UNDEFINED
Returned by
getValueState() . |
static int |
VALUE_STATE_VALID
Returned by
getValueState() . |
Modifier and Type | Method and Description |
---|---|
void |
addAfter(MbElement element)
Adds an unattached syntax element after this element.
|
void |
addAsFirstChild(MbElement element)
Adds an unattached syntax element as the first of this element.
|
void |
addAsLastChild(MbElement element)
Adds an unattached syntax element as the last of this element.
|
void |
addBefore(MbElement element)
Adds an unattached syntax element before this element.
|
MbElement |
copy() |
void |
copyElementTree(MbElement element)
Copies the element tree from the element passed as an argument to the
current element.
|
MbElement |
createElementAfter(int type)
Creates a new syntax element and inserts it after this element.
|
MbElement |
createElementAfter(int type,
String name,
Object value)
Creates a new syntax element and inserts it after this element.
|
MbElement |
createElementAfter(String parserName)
Creates a new syntax element, inserts it after this element,
and associates it with the specified parser class name.
|
MbElement |
createElementAsFirstChild(int type)
Creates a new syntax element as the first child of this element.
|
MbElement |
createElementAsFirstChild(int type,
String name,
Object value)
Creates a new syntax element as the first child of this element.
|
MbElement |
createElementAsFirstChild(String parserName)
Creates a new syntax element as the first child of this element,
and associates it with the specified parser class name.
|
MbElement |
createElementAsLastChild(int type)
Creates a new syntax element as the last child of this element.
|
MbElement |
createElementAsLastChild(int type,
String name,
Object value)
Creates a new syntax element as the last child of this element.
|
MbElement |
createElementAsLastChild(String parserName)
Creates a new syntax element as the last child of this element,
and associates it with the specified parser class name.
|
MbElement |
createElementAsLastChildFromBitstream(byte[] bitstream,
String parserName,
String messageType,
String messageSet,
String messageFormat,
int encoding,
int ccsid,
int options)
Creates a new syntax element tree as the last child of this element,
and associates it with the specified parser.
|
MbElement |
createElementBefore(int type)
Creates a new syntax element and inserts it before this element.
|
MbElement |
createElementBefore(int type,
String name,
Object value)
Creates a new syntax element and inserts it before this element.
|
MbElement |
createElementBefore(String parserName)
Creates a new syntax element, inserts it before this element,
and associates it with the specified parser class name.
|
void |
delete()
Detaches and destroys a portion of a message tree, allowing
its memory to be reused.
|
void |
detach()
Detaches this element from the syntax element tree.
|
Object |
evaluateXPath(MbXPath xpath)
Evaluates the XPath 1.0 expression with the current element as the context node.
|
Object |
evaluateXPath(String expression)
Evaluates the XPath 1.0 expression with the current element as the context node.
|
MbElement[] |
getAllElementsByPath(String path)
Deprecated.
Path selection should be done using the XPath 1.0 methods.
|
org.w3c.dom.Node |
getDOMNode()
Returns this MbElement as an instance of the org.w3c.dom.Node interface
|
MbElement |
getFirstChild()
Returns the syntax element representing the first child of this element.
|
MbElement |
getFirstElementByPath(String path)
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.
|
String |
getValueAsString()
Gets the value of the element as a java String.
|
int |
getValueState()
Gets the state of the value of the element.
|
boolean |
is(MbElement comparisonElement)
is:
Returns true if the MbElement actually refers to the same element in the logical
message tree.
|
boolean |
isReadOnly()
Returns true if this element is part of the message that is read only.
|
void |
setName(String name)
Sets the name of the element, any previous name is overwritten.
|
void |
setNamespace(String namespace)
Sets the namespace URI of the element, any previous namespace is overwritten.
|
void |
setSpecificType(int type)
Sets the full type information for this element including the
parser specific type.
|
void |
setValue(Object value)
Sets the value of the element as a java Object.
|
byte[] |
toBitstream(String messageType,
String messageSet,
String messageFormat,
int encoding,
int ccsid,
int options)
Returns the bit stream representation of the element.
|
String |
toString()
Returns a String representation of the MbElement.
|
public static final int VALUE_STATE_UNDEFINED
getValueState()
. Indicates the
value is undefined.public static final int VALUE_STATE_VALID
getValueState()
. Indicates the
value is valid.public static final int VALUE_STATE_INVALID
getValueState()
. Indicates the
value is invalid.public static final int TYPE_UNKNOWN
public static final int TYPE_NAME
public static final int TYPE_VALUE
public static final int TYPE_NAME_VALUE
public boolean isReadOnly()
public MbElement createElementAfter(int type) throws MbException
createElementAfter(parserName)
type
- The type of syntax element to be created. This must be either a
valid specific type value for the associated parser or one of the following
generic types:
TYPE_NAME
TYPE_VALUE
TYPE_NAME_VALUE
MbException
public MbElement createElementAfter(String parserName) throws MbException
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.
parserName
- The name of the parser class.
The supplied parser constants give values for some of the IBM supplied parsers.
For example, MbBLOB.PARSER_NAME
.MbException
public MbElement createElementAfter(int type, String name, Object value) throws MbException
createElementAfter(parserName)
type
- The type of syntax element to be created.
This must be either a
valid specific type value for the associated parser or one of the following
generic types:
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
BitSet
MbException
public MbElement createElementBefore(int type) throws MbException
createElementBefore(parserName)
type
- The type of syntax element to be created. This must be either a
valid specific type value for the associated parser or one of the following
generic types:
TYPE_NAME
TYPE_VALUE
TYPE_NAME_VALUE
MbException
public MbElement createElementBefore(String parserName) throws MbException
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.
parserName
- The name of the parser class.
The supplied parser constants give values for some of the IBM supplied parsers.
For example, MbBLOB.PARSER_NAME
.MbException
public MbElement createElementBefore(int type, String name, Object value) throws MbException
createElementBefore(parserName)
type
- The type of syntax element to be created.
This must be either a
valid specific type value for the associated parser or one of the following
generic types:
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
BitSet
MbException
public MbElement createElementAsFirstChild(int type) throws MbException
createElementAsFirstChild(parserName)
type
- The type of syntax element to be created. This must be either a
valid specific type value for the associated parser or one of the following
generic types:
TYPE_NAME
TYPE_VALUE
TYPE_NAME_VALUE
MbException
public MbElement createElementAsFirstChild(String parserName) throws MbException
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.
parserName
- The name of the parser class.
The supplied parser constants give values for some of the IBM supplied parsers.
For example, MbBLOB.PARSER_NAME
.MbException
public MbElement createElementAsFirstChild(int type, String name, Object value) throws MbException
createElementAsFirstChild(parserName)
type
- The type of syntax element to be created. This must be either a
valid specific type value for the associated parser or one of the following
generic types:
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
BitSet
MbException
public MbElement createElementAsLastChild(int type) throws MbException
createElementAsLastChild(parserName)
type
- The type of syntax element to be created. This must be either a
valid specific type value for the associated parser or one of the following
generic types:
TYPE_NAME
TYPE_VALUE
TYPE_NAME_VALUE
MbException
public MbElement createElementAsLastChild(String parserName) throws MbException
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.
parserName
- The name of the parser class.
The supplied parser constants give values for some of the IBM supplied parsers.
For example, MbBLOB.PARSER_NAME
.MbException
public MbElement createElementAsLastChild(int type, String name, Object value) throws MbException
createElementAsLastChild(parserName)
type
- The type of syntax element to be created. This must be either a
valid specific type value for the associated parser or one of the following
generic types:
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
BitSet
MbException
public String getName() throws MbException
MbException
public void setName(String name) throws MbException
name
- The new name of the element.MbException
public String getNamespace() throws MbException
MbException
public void setNamespace(String namespace) throws MbException
namespace
- The new namespace URI of the element.MbException
public int getType() throws MbException
TYPE_NAME
TYPE_VALUE
TYPE_NAME_VALUE
TYPE_UNKNOWN
MbException
public int getParserContext() throws MbException
getSpecificType()
should be used instead.MbException
public int getSpecificType() throws MbException
MbException
public void setSpecificType(int type) throws MbException
MbXML
, MbXMLNS
and MbXMLNSC
classes.type
- The full parser specific type for this elementMbException
public Object getValue() throws MbException
MbDate
MbTime
MbTimestamp
Boolean
byte[]
String
Integer
32-bit values.
Long
64-bit values.
Double
BigDecimal
BitSet
MbException
public String getValueAsString() throws MbException
MbException
public void setValue(Object value) throws MbException
MbDate
MbTime
MbTimestamp
Boolean
byte[]
String
Integer
32-bit values.
Long
64-bit values.
Double
BigDecimal
BitSet
value
- The java Object representing the value of the element.MbException
public int getValueState() throws MbException
VALUE_STATE_UNDEFINED
VALUE_STATE_VALID
VALUE_STATE_INVALID
MbException
public String getParserClassName() throws MbException
MbException
public MbElement getParent() throws MbException
MbElement
MbException.
MbException
public MbElement getNextSibling() throws MbException
MbException
public MbElement getPreviousSibling() throws MbException
MbException
public MbElement getFirstChild() throws MbException
MbException
public MbElement getLastChild() throws MbException
MbException
public Object evaluateXPath(String expression) throws MbException
Boolean
Double
String
java.util.List
of MbElement objects representing an XPath 1.0 nodeset
expression
- The XPath 1.0 expression.MbException
- - An exception was thrown during the compilation of
the expression.public Object evaluateXPath(MbXPath xpath) throws MbException
Boolean
Double
String
java.util.List
of MbElement objects representing an XPath 1.0 nodeset
xpath
- The MbXPath object representing the XPath 1.0 expression.MbException
- - An exception was thrown during the compilation of
the expression.public MbElement getFirstElementByPath(String path) throws MbException
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. |
MbException
public MbElement[] getAllElementsByPath(String path) throws MbException
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. |
MbException
public void addAfter(MbElement element) throws MbException
element
- The currently unattached element to be added.MbException
public void addBefore(MbElement element) throws MbException
element
- The currently unattached element to be added.MbException
public void addAsFirstChild(MbElement element) throws MbException
element
- The currently unattached element to be added.MbException
public void addAsLastChild(MbElement element) throws MbException
element
- The currently unattached element to be added.MbException
public MbElement copy() throws MbException
MbException
public void copyElementTree(MbElement element) throws MbException
element
- Source element for copy.MbException
public void detach() throws MbException
MbException
public void delete() throws MbException
MbException
public boolean is(MbElement comparisonElement)
comparisonElement
- The element being compared.public byte[] toBitstream(String messageType, String messageSet, String messageFormat, int encoding, int ccsid, int options) throws MbException
messageType
- The message type definition used to create the
bit stream from the element tree. A value of null will cause this
parameter to be ignored.messageSet
- The message set definition used to create the
bit stream from the element tree. A value of null will cause this
parameter to be ignored.messageFormat
- The message format definition used to create the
bit stream from the element tree. A value of null will cause this
parameter to be ignored.encoding
- The encoding to use when writing the bit stream.
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 bit stream. 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 bit stream 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.MbException
public MbElement createElementAsLastChildFromBitstream(byte[] bitstream, String parserName, String messageType, String messageSet, String messageFormat, int encoding, int ccsid, int options) throws MbException
bitstream
- The bit stream to be parsed and added to the element
tree.parserName
- The name of the parser class to use to parse the
bit stream. The same parser must be used to parse the whole bit stream.messageType
- The message type definition used to create the
element tree from the bit stream. A value of null will cause this
parameter to be ignored.messageSet
- The message set definition used to create the
element tree from the bit stream. A value of null will cause this
parameter to be ignored.messageFormat
- The message format definition used to create the
element tree from the bit stream. A value of null will cause this
parameter to be ignored.encoding
- The encoding to use when parsing the bit stream.
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 parsing
the bit stream. 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.MbException
public org.w3c.dom.Node getDOMNode() throws MbException
MbException