com.tibco.ftl

## Interface TibBrowser

-     public interface TibBrowser

  Programs can use browsers to inspect and delete existing messages in shared durables.

  To create a browser object, see `Realm.createBrowser`. This file defines browser calls.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION` Retry duration for browser operations; double.
    `static java.lang.String` | `PROPERTY_STRING_LABEL` Property name for a browser label; string.
    `static java.lang.String` | `PROPERTY_STRING_MATCHER` Property name for a browser matcher; string.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close a browser.
    `void` | `deleteMessage(Message message)` Delete a browsed message from the durable.
    `Message` | `next()` Retrieve the next message in the durable.
    `void` | `reset()` Return the browser to the first message in the durable.

- - ### Field Detail

    - #### PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

          static final java.lang.String PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

      Retry duration for browser operations; double.

      When `Realm.createBrowser(java.lang.String, java.lang.String, com.tibco.ftl.TibProperties)` or `deleteMessage(com.tibco.ftl.Message)` cannot access the persistence server (usually because of network failure or quorum unavailability), they can automatically retry the interaction. The value of this property overrides the retry behavior of the server. Supply it to the browser create call.

      Values:

      - 0 No retry. The call raises an exception.
      - -1 Synchronously retry the interaction until it succeeds. The call returns only upon success.
      - n (Any positive double value) Retry the interaction for n seconds. Return upon success or raise an exception after timeout.

      Closing the realm or destroying the browser supersedes and cancels retry behavior. This property does not apply to `next()`.

      See Also:
        Constant Field Values

    - #### PROPERTY_STRING_LABEL

          static final java.lang.String PROPERTY_STRING_LABEL

      Property name for a browser label; string.

      It is good practice to include this property in every browser create call. Monitoring data incorporates these labels so administrators can identify and distinguish among internal subscribers created on behalf of browsers. Use labels that reveal the unique role and identity of each durable within the application program. When the browser label is present in the browser create call, the new browser assigns it as the label of its internal subscribers. See `Realm.createBrowser(java.lang.String, java.lang.String, com.tibco.ftl.TibProperties)`.

      See Also:
        Constant Field Values

    - #### PROPERTY_STRING_MATCHER

          static final java.lang.String PROPERTY_STRING_MATCHER

      Property name for a browser matcher; string.

      Limit the browser to messages that match this string. See `Realm.createBrowser(java.lang.String, java.lang.String, com.tibco.ftl.TibProperties)`.

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### next

          Message next()
                throws FTLException

      Retrieve the next message in the durable.

      A browser starts at the first available message in the durable. Each call to this function advances the browser to the next available message.

      The browser will not return messages that have been delivered to live subscribers. To browse every message it may be necessary to stop all subscribers on the durable.

      Messages returned by the browser may be delivered to, and acknowledged by, live subscribers at any time.

      If the connection to the persistence service is interrupted, or some other error occurs, the call will fail, regardless of any retry duration. When this happens, calls to this function will continue to fail until `reset()` is called, or a new browser is created.

      The library owns the message object, and may destroy it after the program calls `next()`, `reset()`, or `close()`. Application code may take a copy of the message via `Message.mutableCopy()`.

      Returns:
        return A message. `null` indicates no more data.
      Throws:
        `FTLException`

    - #### reset

          void reset()
              throws FTLException

      Return the browser to the first message in the durable.

      Applications may call this function to return to the beginning of the durable. The next call to `next()` will return the first available message.

      If `next()` fails, it is necessary to call this function to continue using the browser.

      Throws:
        `FTLException`

    - #### deleteMessage

          void deleteMessage(Message message)
                      throws FTLException

      Delete a browsed message from the durable.

      This call deletes the specified message from the browser's durable. The message is deleted even if it has since been delivered to a live subscriber.

      This call only accepts messages returned from calls to `next()` or mutable copies of such messages. See `Message.mutableCopy()`.

      Parameters:
        `message` - The call removes this message.
      Throws:
        `FTLException`

    - #### close

          void close()
              throws FTLException

      Close a browser.

      Closing a browser frees all the resources associated with it. This call allows the server to clean up as well.

      Throws:
        `FTLException`