Open topic with navigation

TIBCO Rendezvous® 8.7.0

# 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

Did you find this helpful?

Yes No
Great!
Thanks for taking the time to give us some feedback.
Sorry about that

Why wasn't this helpful? (check all that apply)

Could not find what I was looking for
Instructions confusing or unclear
Instructions did not work

Want to tell us more?

Please select at least one option or provide details about the issue!!

Error occurred while submitting feedback.

Error2 occurred while submitting feedback.

TIBCO Rendezvous®

Copyright © 1997-2023. Cloud Software Group, Inc. All Rights Reserved.