com.tibco.ftl

## Interface Subscriber

- All Known Subinterfaces:
    InboxSubscriber

      public interface Subscriber

  Subscribers express interest to receive inbound messages.

  A subscriber object realizes the message-receiving functionality of an endpoint within a program.

  A subscriber object encapsulates all the information that a program needs to subscribe to a stream of messages. Subscriber objects use the transport and format resources associated with an endpoint (as defined in the realm).

  A subscriber can also use an optional content matcher to filter the message stream.

  A subscriber does not receive messages until you add it to an event queue.

  Use subscriber objects to receive one-to-many messages. Use `InboxSubscriber` objects to receive one-to-one messages.

  To create a subscriber object, call `Realm.createSubscriber`. Programs must define a callback method in a class that implements the `SubscriberListener` interface.

  Customers do not implement this interface.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `PROPERTY_BOOL_EXPLICIT_ACK` Explicit acknowledgement property; boolean.
    `static java.lang.String` | `PROPERTY_BOOL_NOLOCAL_MESSAGE_DELIVERY` No Local property that inhibits delivery of messages published by publishers on the same connection as the subscriber; boolean.
    `static java.lang.String` | `PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK` Ownership of inbound messages; boolean.
    `static java.lang.String` | `PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION` Retry duration for persistent subscriber operations; double.
    `static java.lang.String` | `PROPERTY_LONG_PREFETCH_SIZE` Allows a subscriber to override the prefetch set by the administrator for a static durable or dynamic durable template.
    `static java.lang.String` | `PROPERTY_STRING_DURABLE_NAME` Durable name property; string.
    `static java.lang.String` | `PROPERTY_STRING_KEY_FIELD_NAME` Key field name for a dynamic last-value durable; string.
    `static java.lang.String` | `PROPERTY_STRING_LABEL` Property name for a subscriber label; string.
    `static java.lang.String` | `PROPERTY_STRING_NAME` Durable subscriber name property; string.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `acknowledge(Message[] messages, int messageCount)` Explicitly acknowledge a batch of messages.
    `void` | `close()` Close a subscriber.
    `Inbox` | `getInbox()` Deprecated. This method has been replaced by `InboxSubscriber.getInbox`.

- - ### Field Detail

    - #### PROPERTY_STRING_LABEL

          static final java.lang.String PROPERTY_STRING_LABEL

      Property name for a subscriber label; string.

      It is good practice to include this property in every subscriber create call. Monitoring data incorporates these labels so administrators can identify and distinguish among subscribers. Use labels that reveal the unique role and identity of each subscriber within the application program.

      The library does not use labels internally.

      See Also:
        `Realm.createSubscriber`, Constant Field Values

    - #### PROPERTY_STRING_NAME

          static final java.lang.String PROPERTY_STRING_NAME

      Durable subscriber name property; string.

      To request messages from static durable in a persistence store, programs may supply a subscriber name as the value of this property in a `Realm.createSubscriber` call.

      If `PROPERTY_STRING_DURABLE_NAME` is present, it overrides this property.

      If neither this property nor `PROPERTY_STRING_DURABLE_NAME` is present, then the create call uses the default durable subscriber name (`_default`).

      Setting this value is required for only static durables where administrative configuration maps the subscriber name to a durable name.

      See Also:
        Constant Field Values

    - #### PROPERTY_STRING_DURABLE_NAME

          static final java.lang.String PROPERTY_STRING_DURABLE_NAME

      Durable name property; string.

      To request messages from a persistence store, supply a durable name as the value of this property in a `Realm.createSubscriber` call.

      If a static or dynamic durable with this name already exists, the new subscriber draws messages from that durable.

      Otherwise, the store creates a new dynamic durable with this name.

      If this property is present, it overrides the `PROPERTY_STRING_NAME` property.

      See Also:
        Constant Field Values

    - #### PROPERTY_BOOL_EXPLICIT_ACK

          static final java.lang.String PROPERTY_BOOL_EXPLICIT_ACK

      Explicit acknowledgement property; boolean.

      A durable subscriber can acknowledge message receipt to its durable (in the persistence store) in either of two ways:

      - With automatic acknowledgement, the FTL library automatically acknowledges the message when the application callback returns.
      - With explicit acknowledgement, the application program must call `Message.acknowledge` to explicitly acknowledge each message.

      To enable explicit acknowledgement mode, pass this property to `Realm.createSubscriber` with value `true`. Otherwise, the default behavior is automatic acknowledgement.

      See Also:
        Constant Field Values

    - #### PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK

          static final java.lang.String PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK

      Ownership of inbound messages; boolean.

      When `false` or absent, the FTL library retains ownership of inbound messages that arrive through this subscriber. The library automatically destroys each message after the callback returns.

      When `true`, client program code accepts ownership of inbound messages that arrive through this subscriber. The FTL library releases the message object when it dispatches the message to the client's callback. The callback can pass this message to another program thread. Client program code must explicitly destroy the message object.

      See Also:
        Constant Field Values

    - #### PROPERTY_STRING_KEY_FIELD_NAME

          static final java.lang.String PROPERTY_STRING_KEY_FIELD_NAME

      Key field name for a dynamic last-value durable; string.

      When creating or subscribing to a dynamic last-value durable, this property is required. Supply the name of the last-value durable's key field as the value of this property.

      The subscriber's content matcher must match the key field against a specific value.

      See Also:
        Constant Field Values

    - #### PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

          static final java.lang.String PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

      Retry duration for persistent subscriber operations; double.

      When `Realm.createSubscriber(java.lang.String, com.tibco.ftl.ContentMatcher)` or `Message.acknowledge()` 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 subscriber 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 subscriber or the realm supersedes and cancels retry behavior.

      See Also:
        Constant Field Values

    - #### PROPERTY_LONG_PREFETCH_SIZE

          static final java.lang.String PROPERTY_LONG_PREFETCH_SIZE

      Allows a subscriber to override the prefetch set by the administrator for a static durable or dynamic durable template. When absent,the FTL library will default the prefetch value set by the administrator for a static durable or dynamic durable template. When present and and set to a value greater than zero, a subscriber receives prefetch number of messages in a batch as set by the subscriber. NOTE: This value should be lower than the administrator configured value.
      See Also:
        Constant Field Values

    - #### PROPERTY_BOOL_NOLOCAL_MESSAGE_DELIVERY

          static final java.lang.String PROPERTY_BOOL_NOLOCAL_MESSAGE_DELIVERY

      No Local property that inhibits delivery of messages published by publishers on the same connection as the subscriber; boolean. This mainly applies only to subscribers on an endpoint that have a 'store' associated. When \c tibfalse or absent, FTL delivers messages to the subscriber that are published by a publisher on the same connection This is the default behavior. When \c tibtrue, FTL does not deliver messages that are published by publishers on the same connection as the subscriber.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getInbox

          @Deprecated
          Inbox getInbox()

      Deprecated. This method has been replaced by `InboxSubscriber.getInbox`.

    - #### close

          void close()
              throws FTLException

      Close a subscriber.

      Closing a subscriber frees all the resources associated with it (for example, transport resources that are not used in other endpoints).

      Throws:
        `FTLException`

    - #### acknowledge

          void acknowledge(Message[] messages,
                           int messageCount)
                    throws FTLException

      Explicitly acknowledge a batch of messages.

      When a durable subscriber object specifies explicit acknowledgement, the application program must acknowledge each message to the durable, the application can acknowledge each message individually by calling msg.acknowledge() or by calling this method with a batch of messages.

      When a durable subscriber object does \e 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).

      Parameters:
        `messages` - The array of messages to acknowledge
        `messageCount` - The number of messages to acknowledge
      Throws:
        `FTLException`