TibrvMsg.add()
Method
Declaration
voidadd
(
java.lang.String fieldName,
java.lang.Object data)
throws TibrvException
voidadd
(
java.lang.String fieldName,
java.lang.Object data,
short type)
throws TibrvException
voidadd
(
java.lang.String fieldName,
java.lang.Object data,
short type,
int fieldId)
throws TibrvException
Purpose
Remarks
This method copies the information into the new message field. All related convenience methods behave similarly.
Parameter |
Description |
|
Add a field with this name.
|
Add a field with this data value.
|
|
|
Add a field with this explicit type. For a list of types, see Datatype Constants. When absent or TibrvMsg.DEFAULT, determine the field’s type from the type of the data. In Java to Wire Format Datatype Conversion Matrix, filled dots indicate default encodings between homologous types. |
|
Add a field with this identifier. All field identifiers must be unique within each message. When absent, add a field without an identifier. Integers in the range [ Zero is a special value, indicating no identifier. It is illegal to add a field that has both a |
Encoding and Type Conversion
This method automatically tags Java data with a corresponding Rendezvous wire format type; sending the message actually triggers the encoding into wire format. Java to Wire Format Datatype Conversion Matrix specifies default encodings with filled circles; for some types you can override the default decoding by using convenience calls that force specific types (see Add Scalar).
We recommend converting the XML document string to a byte sequence, using the encoding that corresponds to your locale (file encoding system property). Then create a TibrvXml object containing the bytes, and add that object to the message. This practice ensures that all receivers can easily parse the resulting XML document. For more information, see Decoding XML.
Nested Message
When the data
argument is a message object, this method adds only the data portion of the nested message; it does not include any address information or certified delivery information.
Empty Array
The behavior of TibrvMsg.add
differs among the various implementations when the data argument is an empty array. The reason for the discrepancy is that Java supports empty arrays, while C does not.
The native (JNI) preferred implementation uses underlying C calls to manipulate messages stored outside of the Java environment, so it cannot support empty arrays; consequently, this method throws an exception when it receives an empty array.
The native (JNI) backward compatibility implementation and the pure Java implementation both manipulate messages stored within the Java environment, so they do support empty arrays; consequently, this method correctly adds an empty array to a message field.
Figure 234: Java to Wire Format Datatype Conversion Matrix