com.tibco.ftl

## Interface Message

-     public interface Message

  Message objects contain fields with values.

  This interface defines message objects, field types, built-in formats, and the methods that manipulate them.

  Methods that set field values behave like `clearField(java.lang.String)` when the field value is null.

  To create a message object, call `Realm.createMessage`.

  If a subscriber has set the release to callback property, then the program must explicitly destroy all messages it receives through dispatch from that subscriber. Otherwise, the program must not destroy messages received through dispatch.

  Customers do not implement this interface.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `TIB_BUILTIN_MSG_FMT_KEY_FIELDNAME` Built-in field name of the key field in a keyed opaque message.
    `static long` | `TIB_BUILTIN_MSG_FMT_KEY_MAXLEN` Maximum length (in bytes) of the key field of a keyed opaque message.
    `static java.lang.String` | `TIB_BUILTIN_MSG_FMT_KEYED_OPAQUE` Built-in format name for keyed opaque messages.
    `static java.lang.String` | `TIB_BUILTIN_MSG_FMT_OPAQUE` Built-in format name for opaque messages.
    `static java.lang.String` | `TIB_BUILTIN_MSG_FMT_OPAQUE_FIELDNAME` Built-in field name of the data field in an opaque message or a keyed opaque message.
    `static long` | `TIB_BUILTIN_MSG_FMT_OPAQUE_MAXSIZE` Maximum efficient length (in bytes) of a built-in opaque message.
    `static int` | `TIB_FIELD_TYPE_DATETIME` DateTime.
    `static int` | `TIB_FIELD_TYPE_DATETIME_ARRAY` Array of DateTime.
    `static int` | `TIB_FIELD_TYPE_DOUBLE` Double floating-point number.
    `static int` | `TIB_FIELD_TYPE_DOUBLE_ARRAY` Array of double floating-point numbers.
    `static int` | `TIB_FIELD_TYPE_INBOX` Inbox.
    `static int` | `TIB_FIELD_TYPE_LONG` Long integer.
    `static int` | `TIB_FIELD_TYPE_LONG_ARRAY` Array of long integers.
    `static int` | `TIB_FIELD_TYPE_MAX` Deprecated. This constant will be removed.
    `static int` | `TIB_FIELD_TYPE_MESSAGE` Sub-message (that is, a nested message).
    `static int` | `TIB_FIELD_TYPE_MESSAGE_ARRAY` Array of sub-messages.
    `static int` | `TIB_FIELD_TYPE_OPAQUE` Opaque byte-string.
    `static int` | `TIB_FIELD_TYPE_STRING` Character string.
    `static int` | `TIB_FIELD_TYPE_STRING_ARRAY` Array of character strings.
    `static int` | `TIB_FIELD_TYPE_UNKNOWN` Unrecognized type.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `acknowledge()` Explicitly acknowledge a message.
    `void` | `clearAllFields()` Clear all fields in a mutable message.
    `void` | `clearField(MessageFieldRef ref)` Clear a field in a mutable message.
    `void` | `clearField(java.lang.String name)` Clear a field in a mutable message.
    `void` | `destroy()` Destroy a message object.
    `TibDateTime` | `getDateTime(MessageFieldRef ref)` Get the value of a TibDateTime field from a message.
    `void` | `getDateTime(MessageFieldRef ref, TibDateTime in)` Get the value of a TibDateTime field from a message, and store it in an existing TibDateTime object (the method's second argument).
    `TibDateTime` | `getDateTime(java.lang.String name)` Get the value of a TibDateTime field from a message.
    `void` | `getDateTime(java.lang.String name, TibDateTime in)` Get the value of a TibDateTime field from a message, and store it in an existing TibDateTime object (the method's second argument).
    `TibDateTime[]` | `getDateTimeArray(MessageFieldRef ref)` Get the value of a TibDateTime array field from a message.
    `TibDateTime[]` | `getDateTimeArray(java.lang.String name)` Get the value of a TibDateTime array field from a message.
    `int` | `getDeliveryCount()` Get the delivery count of a message.
    `double` | `getDouble(MessageFieldRef ref)` Get the value of a double floating-point field from a message.
    `double` | `getDouble(java.lang.String name)` Get the value of a double floating-point field from a message.
    `double[]` | `getDoubleArray(MessageFieldRef ref)` Get the value of a double array field from a message.
    `double[]` | `getDoubleArray(java.lang.String name)` Get the value of a double array field from a message.
    `long` | `getFieldCount()` Get the number of fields from the message's format.
    `java.nio.ByteBuffer` | `getFieldsFingerprint()` Return a fingerprint representing a message's set fields.
    `int` | `getFieldType(MessageFieldRef ref)` Get the type of a field within the message.
    `int` | `getFieldType(java.lang.String name)` Get the type of a field within the message.
    `java.lang.String` | `getFieldTypeString(int type)` Return a string that represents a field type.
    `Inbox` | `getInbox(MessageFieldRef ref)` Get the value of an inbox field from a message.
    `Inbox` | `getInbox(java.lang.String name)` Get the value of an inbox field from a message.
    `long` | `getLong(MessageFieldRef ref)` Get the value of a long integer field from a message.
    `long` | `getLong(java.lang.String name)` Get the value of a long integer field from a message.
    `long[]` | `getLongArray(MessageFieldRef ref)` Get the value of a long array field from a message.
    `long[]` | `getLongArray(java.lang.String name)` Get the value of a long array field from a message.
    `Message` | `getMessage(MessageFieldRef ref)` Get the value of a message field from a message.
    `Message` | `getMessage(java.lang.String name)` Get the value of a message field from a message.
    `Message[]` | `getMessageArray(MessageFieldRef ref)` Get the value of a message array field from a message.
    `Message[]` | `getMessageArray(java.lang.String name)` Get the value of a message array field from a message.
    `byte[]` | `getOpaque(MessageFieldRef ref)` Get the value of an opaque field from a message.
    `int` | `getOpaque(MessageFieldRef ref, byte[] data)` Get the value of an opaque field from a message.
    `byte[]` | `getOpaque(java.lang.String name)` Get the value of an opaque field from a message.
    `int` | `getOpaque(java.lang.String name, byte[] data)` Get the value of an opaque field from a message.
    `long` | `getStoreLocalMessageId()` Get the store local message id as assigned by the persistence service.
    `java.lang.String` | `getString(MessageFieldRef ref)` Get the value of a string field from a message.
    `java.lang.String` | `getString(java.lang.String name)` Get the value of a string field from a message.
    `java.lang.String[]` | `getStringArray(MessageFieldRef ref)` Get the value of a string array field from a message.
    `java.lang.String[]` | `getStringArray(java.lang.String name)` Get the value of a string array field from a message.
    `boolean` | `isFieldSet(MessageFieldRef ref)` Determine whether a field is set in a message.
    `boolean` | `isFieldSet(java.lang.String name)` Determine whether a field is set in a message.
    `MessageIterator` | `iterator()` Initialize an iterator for the fields of the message.
    `Message` | `mutableCopy()` Create a mutable copy of a message.
    `void` | `setArray(MessageFieldRef ref, double[] value)` Set a double array field in a mutable message.
    `void` | `setArray(MessageFieldRef ref, double[] value, int index, int count)` Set a double array field in a mutable message.
    `void` | `setArray(MessageFieldRef ref, long[] value)` Set a long array field in a mutable message.
    `void` | `setArray(MessageFieldRef ref, long[] value, int index, int count)` Set a long array field in a mutable message.
    `void` | `setArray(MessageFieldRef ref, Message[] messages)` Set a sub-message array field in a mutable message.
    `void` | `setArray(MessageFieldRef ref, Message[] messages, int index, int count)` Set a sub-message array field in a mutable message.
    `void` | `setArray(MessageFieldRef ref, java.lang.String[] value)` Set a string array field in a mutable message.
    `void` | `setArray(MessageFieldRef ref, java.lang.String[] value, int index, int count)` Set a string array field in a mutable message.
    `void` | `setArray(MessageFieldRef ref, TibDateTime[] value)` Set a TibDateTime array field in a mutable message.
    `void` | `setArray(MessageFieldRef ref, TibDateTime[] value, int index, int count)` Set a TibDateTime array field in a mutable message.
    `void` | `setArray(java.lang.String name, double[] value)` Set a double array field in a mutable message.
    `void` | `setArray(java.lang.String name, double[] value, int index, int count)` Set a double array field in a mutable message.
    `void` | `setArray(java.lang.String name, long[] value)` Set a long array field in a mutable message.
    `void` | `setArray(java.lang.String name, long[] value, int index, int count)` Set a long array field in a mutable message.
    `void` | `setArray(java.lang.String name, Message[] messages)` Set a sub-message array field in a mutable message.
    `void` | `setArray(java.lang.String name, Message[] messages, int index, int count)` Set a sub-message array field in a mutable message.
    `void` | `setArray(java.lang.String name, java.lang.String[] value)` Set a string array field in a mutable message.
    `void` | `setArray(java.lang.String name, java.lang.String[] value, int index, int count)` Set a string array field in a mutable message.
    `void` | `setArray(java.lang.String name, TibDateTime[] value)` Set a TibDateTime array field in a mutable message.
    `void` | `setArray(java.lang.String name, TibDateTime[] value, int index, int count)` Set a TibDateTime array field in a mutable message.
    `void` | `setDateTime(MessageFieldRef ref, TibDateTime value)` Set a TibDateTime field in a mutable message.
    `void` | `setDateTime(java.lang.String name, TibDateTime value)` Set a TibDateTime field in a mutable message.
    `void` | `setDouble(MessageFieldRef ref, double value)` Set a double floating-point field in a mutable message.
    `void` | `setDouble(java.lang.String name, double value)` Set a double floating-point field in a mutable message.
    `void` | `setInbox(MessageFieldRef ref, Inbox inbox)` Set an inbox field in a mutable message.
    `void` | `setInbox(java.lang.String name, Inbox inbox)` Set an inbox field in a mutable message.
    `void` | `setLong(MessageFieldRef ref, long value)` Set a long integer field in a mutable message.
    `void` | `setLong(java.lang.String name, long value)` Set a long integer field in a mutable message.
    `void` | `setMessage(MessageFieldRef ref, Message msg)` Set a sub-message field in a mutable message.
    `void` | `setMessage(java.lang.String name, Message msg)` Set a sub-message field in a mutable message.
    `void` | `setOpaque(MessageFieldRef ref, byte[] value)` Set an opaque (byte-array) field in a mutable message.
    `void` | `setOpaque(MessageFieldRef ref, byte[] value, int length)` Set an opaque (byte-array) field in a mutable message.
    `void` | `setOpaque(java.lang.String name, byte[] value)` Set an opaque (byte-array) field in a mutable message.
    `void` | `setOpaque(java.lang.String name, byte[] value, int length)` Set an opaque (byte-array) field in a mutable message.
    `void` | `setString(MessageFieldRef ref, java.lang.String value)` Set a string field in a mutable message.
    `void` | `setString(java.lang.String name, java.lang.String value)` Set a string field in a mutable message.
    `int` | `writeToByteArray(byte[] bytes)` Write a serialized representation of a message to a byte-array.
    `int` | `writeToPortableByteArray(byte[] bytes)` Write a self-describing serialized representation of a message to a byte-array.

- - ### Field Detail

    - #### TIB_BUILTIN_MSG_FMT_OPAQUE

          static final java.lang.String TIB_BUILTIN_MSG_FMT_OPAQUE

      Built-in format name for opaque messages.

      Opaque messages contain only a byte-string.

      This format name is valid as an argument to `Realm.createMessage`.

      See Also:
        Constant Field Values

    - #### TIB_BUILTIN_MSG_FMT_KEYED_OPAQUE

          static final java.lang.String TIB_BUILTIN_MSG_FMT_KEYED_OPAQUE

      Built-in format name for keyed opaque messages. Keyed opaque messages contain only a character string and a byte-string. Content matchers can match against the key field (character string). This format name is valid as an argument to `Realm.createMessage`.
      See Also:
        Constant Field Values

    - #### TIB_BUILTIN_MSG_FMT_OPAQUE_MAXSIZE

          static final long TIB_BUILTIN_MSG_FMT_OPAQUE_MAXSIZE

      Maximum efficient length (in bytes) of a built-in opaque message.

      Larger payloads are less efficient.

      This threshold also limits the total payload of a keyed opaque message (including the key string, its null terminator, and the opaque data).

      See Also:
        Constant Field Values

    - #### TIB_BUILTIN_MSG_FMT_KEY_MAXLEN

          static final long TIB_BUILTIN_MSG_FMT_KEY_MAXLEN

      Maximum length (in bytes) of the key field of a keyed opaque message.
      See Also:
        Constant Field Values

    - #### TIB_BUILTIN_MSG_FMT_OPAQUE_FIELDNAME

          static final java.lang.String TIB_BUILTIN_MSG_FMT_OPAQUE_FIELDNAME

      Built-in field name of the data field in an opaque message or a keyed opaque message.
      See Also:
        Constant Field Values

    - #### TIB_BUILTIN_MSG_FMT_KEY_FIELDNAME

          static final java.lang.String TIB_BUILTIN_MSG_FMT_KEY_FIELDNAME

      Built-in field name of the key field in a keyed opaque message.
      See Also:
        Constant Field Values

    - #### TIB_FIELD_TYPE_OPAQUE

          static final int TIB_FIELD_TYPE_OPAQUE

      Opaque byte-string.
      See Also:
        Constant Field Values

    - #### TIB_FIELD_TYPE_LONG

          static final int TIB_FIELD_TYPE_LONG

      Long integer.
      See Also:
        Constant Field Values

    - #### TIB_FIELD_TYPE_LONG_ARRAY

          static final int TIB_FIELD_TYPE_LONG_ARRAY

      Array of long integers.
      See Also:
        Constant Field Values

    - #### TIB_FIELD_TYPE_DOUBLE

          static final int TIB_FIELD_TYPE_DOUBLE

      Double floating-point number.
      See Also:
        Constant Field Values

    - #### TIB_FIELD_TYPE_DOUBLE_ARRAY

          static final int TIB_FIELD_TYPE_DOUBLE_ARRAY

      Array of double floating-point numbers.
      See Also:
        Constant Field Values

    - #### TIB_FIELD_TYPE_STRING

          static final int TIB_FIELD_TYPE_STRING

      Character string.
      See Also:
        Constant Field Values

    - #### TIB_FIELD_TYPE_STRING_ARRAY

          static final int TIB_FIELD_TYPE_STRING_ARRAY

      Array of character strings.
      See Also:
        Constant Field Values

    - #### TIB_FIELD_TYPE_MESSAGE

          static final int TIB_FIELD_TYPE_MESSAGE

      Sub-message (that is, a nested message).
      See Also:
        Constant Field Values

    - #### TIB_FIELD_TYPE_MESSAGE_ARRAY

          static final int TIB_FIELD_TYPE_MESSAGE_ARRAY

      Array of sub-messages.
      See Also:
        Constant Field Values

    - #### TIB_FIELD_TYPE_INBOX

          static final int TIB_FIELD_TYPE_INBOX

      Inbox.
      See Also:
        Constant Field Values

    - #### TIB_FIELD_TYPE_DATETIME

          static final int TIB_FIELD_TYPE_DATETIME

      DateTime.
      See Also:
        Constant Field Values

    - #### TIB_FIELD_TYPE_DATETIME_ARRAY

          static final int TIB_FIELD_TYPE_DATETIME_ARRAY

      Array of DateTime.
      See Also:
        Constant Field Values

    - #### TIB_FIELD_TYPE_MAX

          @Deprecated
          static final int TIB_FIELD_TYPE_MAX

      Deprecated. This constant will be removed.
      See Also:
        Constant Field Values

    - #### TIB_FIELD_TYPE_UNKNOWN

          static final int TIB_FIELD_TYPE_UNKNOWN

      Unrecognized type.

      `getFieldType` returns `TIB_FIELD_TYPE_UNKNOWN` to indicate that the field's type is not defined.

      It is not legal for programs to supply `TIB_FIELD_TYPE_UNKNOWN` to any API call except `getFieldTypeString`.

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### mutableCopy

          Message mutableCopy()

      Create a mutable copy of a message.

      Programs cannot modify inbound messages that subscribers receive. However, programs can use this method to create mutable copies (which they may modify).

      Programs must destroy mutable copies to reclaim resources.

      Returns:
        a mutable message object

    - #### getString

          java.lang.String getString(java.lang.String name)
                              throws FTLException

      Get the value of a string field from a message.

      This method copies the string from the message.

      Parameters:
        `name` - The method gets the value of the field with this name.
      Returns:
        the string value of a field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getString

          java.lang.String getString(MessageFieldRef ref)
                              throws FTLException

      Get the value of a string field from a message.

      This method copies the string from the message.

      Parameters:
        `ref` - The call gets the value of this field.
      Returns:
        the string value of a field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getLong

          long getLong(java.lang.String name)
                throws FTLException

      Get the value of a long integer field from a message.
      Parameters:
        `name` - The method gets the value of the field with this name.
      Returns:
        the long value of a field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getLong

          long getLong(MessageFieldRef ref)
                throws FTLException

      Get the value of a long integer field from a message.
      Parameters:
        `ref` - The method gets the value of this field.
      Returns:
        the long value of a field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getDouble

          double getDouble(java.lang.String name)
                    throws FTLException

      Get the value of a double floating-point field from a message.
      Parameters:
        `name` - The method gets the value of the field with this name.
      Returns:
        the double value of a field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getDouble

          double getDouble(MessageFieldRef ref)
                    throws FTLException

      Get the value of a double floating-point field from a message.
      Parameters:
        `ref` - The method gets the value of this field.
      Returns:
        the double value of a field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getOpaque

          byte[] getOpaque(java.lang.String name)
                    throws FTLException

      Get the value of an opaque field from a message.

      This method copies the bytes from the message.

      Parameters:
        `name` - The method gets the value of the field with this name.
      Returns:
        the bytes value of a opaque field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getOpaque

          byte[] getOpaque(MessageFieldRef ref)
                    throws FTLException

      Get the value of an opaque field from a message.

      This method copies the bytes from the message.

      Parameters:
        `ref` - The method gets the value of this field.
      Returns:
        the bytes value of a opaque field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getOpaque

          int getOpaque(java.lang.String name,
                        byte[] data)
                 throws FTLException

      Get the value of an opaque field from a message.

      For efficiency, this method does not allocate a new byte-array object; instead it copies the bytes into the byte-array you supply.

      Programmers estimate the required size of the byte-array buffer. If the buffer is too small, the method does not copy any bytes, but returns the actual required size. The program can use this information to supply a buffer of the required size in the second call.

      Programming Strategy:

      1. Create an array you think is big enough.
      2. Call getOpaque.
      3. If the returned size is bigger than your array, then call getOpaque again with a larger array (at least the returned size).

      For example:

                  int length = 2048;
                  byte[] bytes = new byte[length];

                  length = msg.getOpaque(field, bytes);

                  if(length > bytes.length)
                  {
                      bytes = new byte[length];
                      length = msg.getOpaque(field, bytes);
                  }

      Parameters:
        `name` - The method gets the value of the field with this name.
        `data` - The method stores the value in this byte-array.
      Returns:
        the number of bytes in the opaque value
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getOpaque

          int getOpaque(MessageFieldRef ref,
                        byte[] data)
                 throws FTLException

      Get the value of an opaque field from a message.

      For efficiency, this method does not allocate a new byte-array object; instead it copies the bytes into the byte-array you supply.

      Programmers estimate the required size of the byte-array buffer. If the buffer is too small, the method does not copy any bytes, but returns the actual required size. The program can use this information to supply a buffer of the required size in the second call.

      Programming Strategy:

      1. Create an array you think is big enough.
      2. Call getOpaque.
      3. If the returned size is bigger than your array, then call getOpaque again with a larger array (at least the returned size).

      For example:

                  int length = 2048;
                  byte[] bytes = new byte[length];

                  length = msg.getOpaque(field, bytes);

                  if(length > bytes.length)
                  {
                      bytes = new byte[length];
                      length = msg.getOpaque(field, bytes);
                  }

      Parameters:
        `ref` - The method gets the value of this field.
        `data` - The method stores the value in this byte-array.
      Returns:
        the number of bytes in the opaque value
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getMessage

          Message getMessage(java.lang.String name)
                      throws FTLException

      Get the value of a message field from a message.

      This call deserializes the sub-message value, caches the result with the message object, and returns that cached sub-message. The sub-message is valid only for the lifetime of the parent message. Your program must not modify nor destroy the sub-message.

      Calling this method repeatedly returns the same cached sub-message; it does not repeat the deserialization.

      Parameters:
        `name` - The method gets the value of the field with this name.
      Returns:
        the sub-message
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getMessage

          Message getMessage(MessageFieldRef ref)
                      throws FTLException

      Get the value of a message field from a message.

      This call deserializes the sub-message value, caches the result with the message object, and returns that cached sub-message. The sub-message is valid only for the lifetime of the parent message. Your program must not modify nor destroy the sub-message.

      Calling this method repeatedly returns the same cached sub-message; it does not repeat the deserialization.

      Parameters:
        `ref` - The method gets the value of this field.
      Returns:
        the sub-message
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getInbox

          Inbox getInbox(java.lang.String name)
                  throws FTLException

      Get the value of an inbox field from a message.

      This call deserializes the inbox value, caches the result with the message object, and returns that cached inbox object. The inbox object is valid only for the lifetime of the message (though programs may copy it). Your program must not modify nor destroy the inbox object.

      Calling this method repeatedly returns the same cached inbox; it does not repeat the deserialization.

      Programs can send messages to the inbox using `Publisher.sendToInbox`.

      Parameters:
        `name` - The method gets the value of the field with this name.
      Returns:
        an inbox
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getInbox

          Inbox getInbox(MessageFieldRef ref)
                  throws FTLException

      Get the value of an inbox field from a message.

      This call deserializes the inbox value, caches the result with the message object, and returns that cached inbox object. The inbox object is valid only for the lifetime of the message (though programs may copy it). Your program must not modify nor destroy the inbox object.

      Calling this method repeatedly returns the same cached inbox; it does not repeat the deserialization.

      Programs can send messages to the inbox using `Publisher.sendToInbox`.

      Parameters:
        `ref` - The method gets the value of this field.
      Returns:
        an inbox
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getDateTime

          TibDateTime getDateTime(java.lang.String name)
                           throws FTLException

      Get the value of a TibDateTime field from a message.
      Parameters:
        `name` - The method gets the value of the field with this name.
      Returns:
        the TibDateTime value of a field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getDateTime

          TibDateTime getDateTime(MessageFieldRef ref)
                           throws FTLException

      Get the value of a TibDateTime field from a message.
      Parameters:
        `ref` - The method gets the value of this field.
      Returns:
        the TibDateTime value of a field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getDateTime

          void getDateTime(java.lang.String name,
                           TibDateTime in)
                    throws FTLException

      Get the value of a TibDateTime field from a message, and store it in an existing TibDateTime object (the method's second argument).
      Parameters:
        `name` - The method gets the value of the field with this name.
        `in` - The method stores the value into this TibDateTime object.
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getDateTime

          void getDateTime(MessageFieldRef ref,
                           TibDateTime in)
                    throws FTLException

      Get the value of a TibDateTime field from a message, and store it in an existing TibDateTime object (the method's second argument).
      Parameters:
        `ref` - The method gets the value of this field.
        `in` - The method stores the value into this TibDateTime object.
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### setDateTime

          void setDateTime(java.lang.String name,
                           TibDateTime value)
                    throws FTLException

      Set a TibDateTime field in a mutable message.

      The method copies the value into the message.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `value` - The method sets this TibDateTime as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setDateTime

          void setDateTime(MessageFieldRef ref,
                           TibDateTime value)
                    throws FTLException

      Set a TibDateTime field in a mutable message.

      The method copies the value into the message.

      Parameters:
        `ref` - The method sets the value of this field.
        `value` - The method sets this TibDateTime as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setString

          void setString(java.lang.String name,
                         java.lang.String value)
                  throws FTLException

      Set a string field in a mutable message.

      This method copies the string value into the message.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `value` - The method sets this string as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setString

          void setString(MessageFieldRef ref,
                         java.lang.String value)
                  throws FTLException

      Set a string field in a mutable message.

      This method copies the string value into the message.

      Parameters:
        `ref` - The method sets the value of this field.
        `value` - The method sets this string as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setLong

          void setLong(java.lang.String name,
                       long value)
                throws FTLException

      Set a long integer field in a mutable message.
      Parameters:
        `name` - The method sets the value of the field with this name.
        `value` - The method sets this long as the field value.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setLong

          void setLong(MessageFieldRef ref,
                       long value)
                throws FTLException

      Set a long integer field in a mutable message.
      Parameters:
        `ref` - The method sets the value of this field.
        `value` - The method sets this long as the field value.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setDouble

          void setDouble(java.lang.String name,
                         double value)
                  throws FTLException

      Set a double floating-point field in a mutable message.
      Parameters:
        `name` - The method sets the value of the field with this name.
        `value` - The method sets this double as the field value.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setDouble

          void setDouble(MessageFieldRef ref,
                         double value)
                  throws FTLException

      Set a double floating-point field in a mutable message.
      Parameters:
        `ref` - The method sets the value of this field.
        `value` - The method sets this double as the field value.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setOpaque

          void setOpaque(java.lang.String name,
                         byte[] value)
                  throws FTLException

      Set an opaque (byte-array) field in a mutable message.

      This method copies the entire byte-array into the field.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `value` - The method sets this byte-array as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setOpaque

          void setOpaque(MessageFieldRef ref,
                         byte[] value)
                  throws FTLException

      Set an opaque (byte-array) field in a mutable message.

      This method copies the entire byte-array into the field.

      Parameters:
        `ref` - The method sets the value of this field.
        `value` - The method sets this byte-array as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setOpaque

          void setOpaque(java.lang.String name,
                         byte[] value,
                         int length)
                  throws FTLException

      Set an opaque (byte-array) field in a mutable message.

      This method copies only a portion of the byte-array value into the field.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `value` - The method sets this byte-array as the field value. If null, this method clears the field.
        `length` - The method copies this many bytes into the message.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setOpaque

          void setOpaque(MessageFieldRef ref,
                         byte[] value,
                         int length)
                  throws FTLException

      Set an opaque (byte-array) field in a mutable message.

      This method copies only a portion of the byte-array value into the field.

      Parameters:
        `ref` - The method sets the value of this field.
        `value` - The method sets this byte-array as the field value. If null, this method clears the field.
        `length` - The method copies this many bytes into the message.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setMessage

          void setMessage(java.lang.String name,
                          Message msg)
                   throws FTLException

      Set a sub-message field in a mutable message.

      This call copies the sub-message data into the enclosing message field, but does not create a new Java message object.

      Programs may safely destroy the `msg` argument after this call returns.

      Do not set a message as a sub-message of itself (at any level of nesting).

      Parameters:
        `name` - The method sets the value of the field with this name.
        `msg` - The method sets this sub-message as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setMessage

          void setMessage(MessageFieldRef ref,
                          Message msg)
                   throws FTLException

      Set a sub-message field in a mutable message.

      This call copies the sub-message data into the enclosing message field, but does not create a new Java message object.

      Programs may safely destroy the `msg` argument after this call returns.

      Do not set a message as a sub-message of itself (at any level of nesting).

      Parameters:
        `ref` - The method sets the value of this field.
        `msg` - The method sets this sub-message as the field value.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setInbox

          void setInbox(java.lang.String name,
                        Inbox inbox)
                 throws FTLException

      Set an inbox field in a mutable message.

      This call copies the inbox into a message field.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `inbox` - The method sets this inbox as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setInbox

          void setInbox(MessageFieldRef ref,
                        Inbox inbox)
                 throws FTLException

      Set an inbox field in a mutable message.

      This call copies the inbox into a message field.

      Parameters:
        `ref` - The method sets the value of this field.
        `inbox` - The method sets this inbox as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setArray

          void setArray(java.lang.String name,
                        long[] value)
                 throws FTLException

      Set a long array field in a mutable message.

      This method copies the array.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `value` - The method sets this array as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setArray

          void setArray(MessageFieldRef ref,
                        long[] value)
                 throws FTLException

      Set a long array field in a mutable message.

      This method copies the array.

      Parameters:
        `ref` - The method sets the value of this field.
        `value` - The method sets this array as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setArray

          void setArray(java.lang.String name,
                        long[] value,
                        int index,
                        int count)
                 throws FTLException

      Set a long array field in a mutable message.

      This method copies `count` elements from the array, starting at `index`.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `value` - The method sets the field value from this array. If null, this method clears the field.
        `index` - The method copies value elements starting at this index.
        `count` - The method copies `count` elements.
      Throws:
        `FTLException` -
        - The message uses a managed format that does not define the field.
        - The `index` and `count` arguments specify a location beyond the end of the `value` array.

    - #### setArray

          void setArray(MessageFieldRef ref,
                        long[] value,
                        int index,
                        int count)
                 throws FTLException

      Set a long array field in a mutable message.

      This method copies `count` elements from the array, starting at `index`.

      Parameters:
        `ref` - The method sets the value of this field.
        `value` - The method sets the field value from this array. If null, this method clears the field.
        `index` - The method copies value elements starting at this index.
        `count` - The method copies `count` elements.
      Throws:
        `FTLException` -
        - The message uses a managed format that does not define the field.
        - The `index` and `count` arguments specify a location beyond the end of the `value` array.

    - #### setArray

          void setArray(java.lang.String name,
                        double[] value)
                 throws FTLException

      Set a double array field in a mutable message.

      This method copies the array.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `value` - The method sets this array as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setArray

          void setArray(MessageFieldRef ref,
                        double[] value)
                 throws FTLException

      Set a double array field in a mutable message.

      This method copies the array.

      Parameters:
        `ref` - The method sets the value of this field.
        `value` - The method sets this array as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setArray

          void setArray(java.lang.String name,
                        double[] value,
                        int index,
                        int count)
                 throws FTLException

      Set a double array field in a mutable message.

      This method copies `count` elements from the array, starting at `index`.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `value` - The method sets the field value from this array. If null, this method clears the field.
        `index` - The method copies value elements starting at this index.
        `count` - The method copies `count` elements.
      Throws:
        `FTLException` -
        - The message uses a managed format that does not define the field.
        - The `index` and `count` arguments specify a location beyond the end of the `value` array.

    - #### setArray

          void setArray(MessageFieldRef ref,
                        double[] value,
                        int index,
                        int count)
                 throws FTLException

      Set a double array field in a mutable message.

      This method copies `count` elements from the array, starting at `index`.

      Parameters:
        `ref` - The method sets the value of this field.
        `value` - The method sets the field value from this array. If null, this method clears the field.
        `index` - The method copies value elements starting at this index.
        `count` - The method copies `count` elements.
      Throws:
        `FTLException` -
        - The message uses a managed format that does not define the field.
        - The `index` and `count` arguments specify a location beyond the end of the `value` array.

    - #### setArray

          void setArray(java.lang.String name,
                        java.lang.String[] value)
                 throws FTLException

      Set a string array field in a mutable message.

      This method copies the array.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `value` - The method sets this array as the field value. (Null is not a legal value within this array.) If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setArray

          void setArray(MessageFieldRef ref,
                        java.lang.String[] value)
                 throws FTLException

      Set a string array field in a mutable message.

      This method copies the array.

      Parameters:
        `ref` - The method sets the value of this field.
        `value` - The method sets this array as the field value. (Null is not a legal value within this array.) If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setArray

          void setArray(java.lang.String name,
                        java.lang.String[] value,
                        int index,
                        int count)
                 throws FTLException

      Set a string array field in a mutable message.

      This method copies `count` elements from the array, starting at `index`.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `value` - The method sets the field value from this array. If null, this method clears the field.
        `index` - The method copies value elements starting at this index.
        `count` - The method copies `count` elements.
      Throws:
        `FTLException` -
        - The message uses a managed format that does not define the field.
        - The `index` and `count` arguments specify a location beyond the end of the `value` array.

    - #### setArray

          void setArray(MessageFieldRef ref,
                        java.lang.String[] value,
                        int index,
                        int count)
                 throws FTLException

      Set a string array field in a mutable message.

      This method copies `count` elements from the array, starting at `index`.

      Parameters:
        `ref` - The method sets the value of this field.
        `value` - The method sets the field value from this array. If null, this method clears the field.
        `index` - The method copies value elements starting at this index.
        `count` - The method copies `count` elements.
      Throws:
        `FTLException` -
        - The message uses a managed format that does not define the field.
        - The `index` and `count` arguments specify a location beyond the end of the `value` array.

    - #### setArray

          void setArray(java.lang.String name,
                        Message[] messages)
                 throws FTLException

      Set a sub-message array field in a mutable message.

      This call copies the sub-message data into the enclosing message field, but does not create new Java message objects.

      Programs may safely destroy the `messages` argument after this call returns.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `messages` - The method sets this array as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setArray

          void setArray(MessageFieldRef ref,
                        Message[] messages)
                 throws FTLException

      Set a sub-message array field in a mutable message.

      This call copies the sub-message data into the enclosing message field, but does not create new Java message objects.

      Programs may safely destroy the `messages` argument after this call returns.

      Parameters:
        `ref` - The method sets the value of this field.
        `messages` - The method sets this array as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setArray

          void setArray(java.lang.String name,
                        Message[] messages,
                        int index,
                        int count)
                 throws FTLException

      Set a sub-message array field in a mutable message.

      This method copies `count` elements from the array, starting at `index`.

      This call copies the sub-message data into the enclosing message field, but does not create new Java message objects.

      Programs may safely destroy the `messages` argument after this call returns.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `messages` - The method sets the field value from this array. If null, this method clears the field.
        `index` - The method copies value elements starting at this index.
        `count` - The method copies `count` elements.
      Throws:
        `FTLException` -
        - The message uses a managed format that does not define the field.
        - The `index` and `count` arguments specify a location beyond the end of the `value` array.

    - #### setArray

          void setArray(MessageFieldRef ref,
                        Message[] messages,
                        int index,
                        int count)
                 throws FTLException

      Set a sub-message array field in a mutable message.

      This method copies `count` elements from the array, starting at `index`.

      This call copies the sub-message data into the enclosing message field, but does not create new Java message objects.

      Programs may safely destroy the `messages` argument after this call returns.

      Parameters:
        `ref` - The method sets the value of this field.
        `messages` - The method sets the field value from this array. If null, this method clears the field.
        `index` - The method copies value elements starting at this index.
        `count` - The method copies `count` elements.
      Throws:
        `FTLException` -
        - The message uses a managed format that does not define the field.
        - The `index` and `count` arguments specify a location beyond the end of the `value` array.

    - #### setArray

          void setArray(java.lang.String name,
                        TibDateTime[] value)
                 throws FTLException

      Set a TibDateTime array field in a mutable message.

      This method copies the array.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `value` - The method sets this array as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setArray

          void setArray(MessageFieldRef ref,
                        TibDateTime[] value)
                 throws FTLException

      Set a TibDateTime array field in a mutable message.

      This method copies the array.

      Parameters:
        `ref` - The method sets the value of this field.
        `value` - The method sets this array as the field value. If null, this method clears the field.
      Throws:
        `FTLException` - The message uses a managed format that doesn't define the field.

    - #### setArray

          void setArray(java.lang.String name,
                        TibDateTime[] value,
                        int index,
                        int count)
                 throws FTLException

      Set a TibDateTime array field in a mutable message.

      This method copies `count` elements from the array, starting at `index`.

      Parameters:
        `name` - The method sets the value of the field with this name.
        `value` - The method sets the field value from this array. If null, this method clears the field.
        `index` - The method copies value elements starting at this index.
        `count` - The method copies `count` elements.
      Throws:
        `FTLException` -
        - The message uses a managed format that does not define the field.
        - The `index` and `count` arguments specify a location beyond the end of the `value` array.

    - #### setArray

          void setArray(MessageFieldRef ref,
                        TibDateTime[] value,
                        int index,
                        int count)
                 throws FTLException

      Set a TibDateTime array field in a mutable message.

      This method copies `count` elements from the array, starting at `index`.

      Parameters:
        `ref` - The method sets the value of this field.
        `value` - The method sets the field value from this array. If null, this method clears the field.
        `index` - The method copies value elements starting at this index.
        `count` - The method copies `count` elements.
      Throws:
        `FTLException` -
        - The message uses a managed format that does not define the field.
        - The `index` and `count` arguments specify a location beyond the end of the `value` array.

    - #### getLongArray

          long[] getLongArray(java.lang.String name)
                       throws FTLException

      Get the value of a long array field from a message.
      Parameters:
        `name` - The method gets the value of the field with this name.
      Returns:
        the array value of the field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getLongArray

          long[] getLongArray(MessageFieldRef ref)
                       throws FTLException

      Get the value of a long array field from a message.
      Parameters:
        `ref` - The method gets the value of this field.
      Returns:
        the array value of the field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getDoubleArray

          double[] getDoubleArray(java.lang.String name)
                           throws FTLException

      Get the value of a double array field from a message.
      Parameters:
        `name` - The method gets the value of the field with this name.
      Returns:
        the array value of the field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getDoubleArray

          double[] getDoubleArray(MessageFieldRef ref)
                           throws FTLException

      Get the value of a double array field from a message.
      Parameters:
        `ref` - The method gets the value of this field.
      Returns:
        the array value of the field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getStringArray

          java.lang.String[] getStringArray(java.lang.String name)
                                     throws FTLException

      Get the value of a string array field from a message.
      Parameters:
        `name` - The method gets the value of the field with this name.
      Returns:
        the array value of the field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getStringArray

          java.lang.String[] getStringArray(MessageFieldRef ref)
                                     throws FTLException

      Get the value of a string array field from a message.
      Parameters:
        `ref` - The method gets the value of this field.
      Returns:
        the array value of the field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getMessageArray

          Message[] getMessageArray(java.lang.String name)
                             throws FTLException

      Get the value of a message array field from a message.

      This call deserializes the sub-message array value, caches the result with the message object, and returns that cached array object. The array is valid only for the lifetime of the message. Your program must not modify nor destroy the sub-messages, nor modify the array.

      Calling this method repeatedly returns the same cached array of cached messages; it does not repeat the deserialization.

      Parameters:
        `name` - The method gets the value of the field with this name.
      Returns:
        the array value of the field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getMessageArray

          Message[] getMessageArray(MessageFieldRef ref)
                             throws FTLException

      Get the value of a message array field from a message.

      This call deserializes the sub-message array value, caches the result with the message object, and returns that cached array object. The array is valid only for the lifetime of the message. Your program must not modify nor destroy the sub-messages, nor modify the array.

      Calling this method repeatedly returns the same cached array of cached messages; it does not repeat the deserialization.

      Parameters:
        `ref` - The method gets the value of this field.
      Returns:
        the array value of the field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getDateTimeArray

          TibDateTime[] getDateTimeArray(java.lang.String name)
                                  throws FTLException

      Get the value of a TibDateTime array field from a message.
      Parameters:
        `name` - The method gets the value of the field with this name.
      Returns:
        the array value of the field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getDateTimeArray

          TibDateTime[] getDateTimeArray(MessageFieldRef ref)
                                  throws FTLException

      Get the value of a TibDateTime array field from a message.
      Parameters:
        `ref` - The method gets the value of this field.
      Returns:
        the array value of the field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### isFieldSet

          boolean isFieldSet(java.lang.String name)

      Determine whether a field is set in a message.

      If it is not set, then getting the field value throws an exception.

      Parameters:
        `name` - The method checks for a field with this name.
      Returns:
        `true` if the field is set; `false` otherwise

    - #### isFieldSet

          boolean isFieldSet(MessageFieldRef ref)

      Determine whether a field is set in a message.

      If it is not set, then getting the field value throws an exception.

      Parameters:
        `ref` - The method checks for this field.
      Returns:
        `true` if the field is set; `false` otherwise

    - #### clearField

          void clearField(java.lang.String name)

      Clear a field in a mutable message.

      Clearing a field clears the data from a field in the message object, and flags the field so a subsequent send call does not transmit it.

      Parameters:
        `name` - The method clears the field with this name.

    - #### clearField

          void clearField(MessageFieldRef ref)

      Clear a field in a mutable message.

      Clearing a field clears the data from a field in the message object, and flags the field so a subsequent send call does not transmit it.

      Parameters:
        `ref` - The method clears this field.

    - #### clearAllFields

          void clearAllFields()

      Clear all fields in a mutable message.

      After clearing all fields, you can re-use the message. The message format does not change.

      This call is more efficient than creating a new empty message of the same format.

    - #### writeToByteArray

          int writeToByteArray(byte[] bytes)

      Write a serialized representation of a message to a byte-array.

      Programmers estimate the required size of the byte-array buffer. If the buffer is too small, the method fails, but returns the actual required size. The program can use this information to supply a buffer of the required size in the second call.

      Programming Strategy:

      1. Create an array you think is big enough.
      2. Call writeToByteArray.
      3. If the returned size is bigger than your array, then call writeToByteArray again with a larger array (at least the returned size).

      For example:

                  int length = 2048;
                  byte[] bytes = new byte[length];

                  length = msg.writeToByteArray(bytes);

                  if(length > bytes.length)
                  {
                      bytes = new byte[length];
                      length = msg.writeToByteArray(bytes);
                  }

      Parameters:
        `bytes` - The method writes the serialized representation into this byte-array.
      Returns:
        the actual size of the serialized representation (in bytes)

    - #### writeToPortableByteArray

          int writeToPortableByteArray(byte[] bytes)

      Write a self-describing serialized representation of a message to a byte-array.

      This method writes a portable form of the message, which you can use outside the originating realm. The portable form is larger than optimized forms, because it includes all format metadata (as with a dynamic format).

      Programmers estimate the required size of the byte-array buffer. If the buffer is too small, the method fails, but returns the actual required size. The program can use this information to supply a buffer of the required size in the second call.

      Programming Strategy:

      1. Create an array you think is big enough.
      2. Call writeToPortableByteArray.
      3. If the returned size is bigger than your array, then call writeToPortableByteArray again with a larger array (at least the returned size).

      For example:

                  int length = 2048;
                  byte[] bytes = new byte[length];

                  length = msg.writeToPortableByteArray(bytes);

                  if(length > bytes.length)
                  {
                      bytes = new byte[length];
                      length = msg.writeToPortableByteArray(bytes);
                  }

      Parameters:
        `bytes` - The method writes the serialized representation into this byte-array.
      Returns:
        the actual size of the serialized representation (in bytes)

    - #### destroy

          void destroy()
                throws FTLException

      Destroy a message object.

      A program may destroy only mutable messages -- that is, those messages that the program creates -- for example, using `Realm.createMessage` or `mutableCopy()`.

      Inbound messages in listener callback methods belong to the FTL library; programs must not destroy them.

      Do not destroy a message if the program needs data that the message owns -- for example, a string (from `getString`), an opaque pointer (from `getOpaque`), a sub-message (from `getMessage`), or an inbox (from `getInbox`).

      Destroying a message frees all resources associated with it.

      Throws:
        `FTLException`

    - #### getFieldType

          int getFieldType(MessageFieldRef ref)
                    throws FTLException

      Get the type of a field within the message.
      Parameters:
        `ref` - The method gets the type of this field.
      Returns:
        the type of the field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getFieldType

          int getFieldType(java.lang.String name)
                    throws FTLException

      Get the type of a field within the message.
      Parameters:
        `name` - The method gets the type of the field with this name.
      Returns:
        the type of the field
      Throws:
        `FTLException` - The field is not defined in the format, or is not set in the message.

    - #### getFieldTypeString

          java.lang.String getFieldTypeString(int type)

      Return a string that represents a field type.
      Parameters:
        `type` - The method converts this type to a string.
      Returns:
        a string corresponding to the `type` argument

    - #### iterator

          MessageIterator iterator()

      Initialize an iterator for the fields of the message.
      Returns:
        a `MessageIterator` over the fields of the message

    - #### acknowledge

          void acknowledge()
                    throws FTLException

      Explicitly acknowledge a message.

      When a durable subscriber object specifies explicit acknowledgement, the application program must acknowledge each message to the durable by calling this method.

      When a durable subscriber object does not specify explicit acknowledgement, the FTL library automatically acknowledges the message when the application callback method returns.

      For any message that arrives through a non-durable subscriber, this call returns without error (and without action).

      Throws:
        `FTLException`
      See Also:
        `Subscriber.PROPERTY_BOOL_EXPLICIT_ACK`

    - #### getDeliveryCount

          int getDeliveryCount()
                        throws FTLException

      Get the delivery count of a message. This value represents the number of times that a persistence service has delivered the message from a standard or shared durable to any subscriber. The value 1 indicates the application is the first to receive the message. The special value -1 indicates that delivery count does not apply. For example, the message is not in a shared durable, or did not arrive from a persistence server that tracks delivery count.
      Returns:
        the delivery count
      Throws:
        `FTLException` - if the message is null

    - #### getFieldsFingerprint

          java.nio.ByteBuffer getFieldsFingerprint()
                                            throws FTLException

      Return a fingerprint representing a message's set fields. A message's fields fingerprint is calculated based on the message's set fields, taking into account each field's position, type, and name, but not value.
      Returns:
        the message's fields fingerprint
      Throws:
        `FTLException` - if the message is null

    - #### getStoreLocalMessageId

          long getStoreLocalMessageId()
                               throws FTLException

      Get the store local message id as assigned by the persistence service. This message id is local to a persistence service cluster and also different depending on the store being replicated or non replicated.
      Returns:
        the store local message id.
      Throws:
        `FTLException`

    - #### getFieldCount

          long getFieldCount()
                      throws FTLException

      Get the number of fields from the message's format. This call returns the number of field from the message's format.
      Returns:
        The number of fields from the message's format.
      Throws:
        `FTLException`