TibrvMsg.add()

Method

Declaration

void add(
    java.lang.String fieldName,
    java.lang.Object data)
   throws TibrvException
void add(
    java.lang.String fieldName,
    java.lang.Object data,
    short type)
  throws TibrvException
void add(
    java.lang.String fieldName,
    java.lang.Object data,
    short type,
    int fieldId)
  throws TibrvException

Purpose

Add a field to a message.

Remarks

This method copies the information into the new message field. All related convenience methods behave similarly.

Parameter

Description

fieldName

Add a field with this name.

null is a legal name. However, if fieldId is non-zero, then fieldName must be non-null.

data

Add a field with this data value.

null is illegal.

type

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.

fieldId

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 [0, 65535] are valid identifiers.

Zero is a special value, indicating no identifier. It is illegal to add a field that has both a null field name and a non-zero field identifier.

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).

Encoding XML

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

See Also

TibrvMsg.addField()

Add Scalar