com.tibco.ftl

## Interface MessageIterator

- All Superinterfaces:
    java.util.Iterator<MessageFieldRef>

      public interface MessageIterator
      extends java.util.Iterator<MessageFieldRef>

  A message iterator object traverses the fields of a message.

  When you do not know the format of a message at the time you design a program, your program can use an iterator to traverse the fields of a message. For example, you can use this technique to output the complete content of an erroneous or unexpected message to a log file. (However, when you do know the format of an inbound message, then you can code the program to get each field in the most efficient manner.)

  A message iterator presents all the fields that are actually set in a message object. The message format determines the order in which an iterator presents the fields of a message.

  Message iterator objects are not thread-safe. Programs must not access a message iterator from several threads simultaneously.

  An iterator becomes invalid when its message becomes invalid.

  To create a message iterator object, call `Message.iterator`.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()` Explicitly destroy the MessageIterator object.
    `boolean` | `hasNext()` Determine whether a message iterator object can present another field.
    `MessageFieldRef` | `next()` Get the next field of a message iterator object.
    `void` | `remove()` Unsupported method; do not use.

    - ### Methods inherited from interface java.util.Iterator

      `forEachRemaining`

- - ### Method Detail

    - #### hasNext

          boolean hasNext()

      Determine whether a message iterator object can present another field.
      - This call returns `true` if a message iterator is ready to present another field.
      - This call returns `false` if the iterator has presented the last field.
      Specified by:
        `hasNext` in interface `java.util.Iterator<MessageFieldRef>`
      Returns:
        boolean

    - #### next

          MessageFieldRef next()

      Get the next field of a message iterator object.

      This method advances the iterator to the next field of its message, and returns a field reference object, which refers to that next field. Programs can use that field reference object to get the field's name, type and value.

      Warning: For efficiency, an iterator object reuses a single field reference object. Iterator methods overwrite that field reference object. Programs can use the field reference object with correct results only until the next call that changes the state of the iterator. That is, when you get the next field or destroy the iterator, then the field reference object changes too. Although field reference objects are usually thread-safe, this one is not thread-safe.

      Specified by:
        `next` in interface `java.util.Iterator<MessageFieldRef>`
      Returns:
        a `MessageFieldRef` to the next field
      Throws:
        `NoSuchElementException` - The iterator has already presented the last field of the message.

    - #### remove

          void remove()

      Unsupported method; do not use.
      Specified by:
        `remove` in interface `java.util.Iterator<MessageFieldRef>`

    - #### destroy

          void destroy()

      Explicitly destroy the MessageIterator object.

      This explicit destroy method immediately triggers Java garbage collection. Programs can use it to manage garbage collection delays (to achieve more consistent latency).

      Nonetheless, programs need not call this optional method. When a message object is destroyed, all message iterator objects that refer to that message are automatically destroyed as well.