com.tibco.ftl

## Interface Publisher

-     public interface Publisher

  Publisher objects send messages.

  A publisher object realizes the message-sending functionality of an endpoint within a program.

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

  Programs can use a publisher to send messages one-to-many, or one-to-one.

  To create a publisher object, call `Realm.createPublisher`.

  Customers do not implement this interface.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `PROPERTY_BOOL_RELEASE_MSGS_TO_SEND` Ownership of outbound messages; boolean.
    `static java.lang.String` | `PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER` Linger duration for persistent publisher close operation; double.
    `static java.lang.String` | `PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION` Retry duration for persistent publisher operations; double.
    `static java.lang.String` | `PROPERTY_INT_MAX_BATCH_COUNT` Maximum batch count for non-inline publishers; integer.
    `static java.lang.String` | `PROPERTY_INT_SEND_POLICY` Publisher send policy; string.
    `static java.lang.String` | `PROPERTY_STRING_LABEL` Property name for a publisher label; string.
    `static java.lang.String` | `PROPERTY_STRING_REPLY_ENDPOINT` Property name for a publisher reply endpoint; string.
    `static int` | `SEND_INLINE` Publish with low latency; integer.
    `static int` | `SEND_NON_INLINE` Publish with high throughput; integer.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close a publisher.
    `void` | `flush()` When the publisher's send policy is non-inline, flush all outsanding messages.
    `int` | `getMaxBatchCount()` Returns the maximum batch count of a non-inline publisher.
    `int` | `getSendPolicy()` Returns the send policy of a publisher.
    `void` | `send(Message msg)` Send a message, one-to-many.
    `void` | `send(Message[] messages)` Send an array of messages, one-to-many.
    `void` | `send(Message[] messages, int messageCount)` Send a subset of messages from an array of messages.
    `void` | `sendReply(Message reply, Message request)` Send a reply message to a requester.
    `Message` | `sendRequest(Message request, double timeout)` Send a request and wait for reply.
    `void` | `sendToInbox(Inbox inbox, Message msg)` Send an inbox message to an inbox.

- - ### Field Detail

    - #### PROPERTY_STRING_REPLY_ENDPOINT

          static final java.lang.String PROPERTY_STRING_REPLY_ENDPOINT

      Property name for a publisher reply endpoint; string.

      For `Publisher.sendRequest` this specifies the endpoint on which the reply is received.

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

    - #### PROPERTY_STRING_LABEL

          static final java.lang.String PROPERTY_STRING_LABEL

      Property name for a publisher label; string.

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

      If a non-inline persistence publisher fails to persist a message, the resulting advisory will include the publisher label. See `Advisory.NAME_NONINLINE_SEND_LOSS`.

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

    - #### SEND_INLINE

          static final int SEND_INLINE

      Publish with low latency; integer.

      If this value is set for property `PROPERTY_INT_SEND_POLICY`, then publish calls `send(Message msg)` and `send(Message messages [])` send messages immediately to reduce latency.

      See Also:
        Constant Field Values

    - #### SEND_NON_INLINE

          static final int SEND_NON_INLINE

      Publish with high throughput; integer.

      If this value is set for property `PROPERTY_INT_SEND_POLICY`, then the publish call `send(Message msg)` may batch messages in the background for improved throughput.

      See Also:
        Constant Field Values

    - #### PROPERTY_INT_SEND_POLICY

          static final java.lang.String PROPERTY_INT_SEND_POLICY

      Publisher send policy; string.

      Optimize the publisher for lower latency or greater throughput.

      Values:

      - `SEND_INLINE` Send the message immediately, to reduce latency.
      - `SEND_NON_INLINE` Buffer and batch messages before sending to help improve throughput.

      When publishing to a store, and the administrator has configured publisher mode store_confirm_send for the store, the inline send policy causes `send(Message msg)` and `send(Message messages [])` to block until the message(s) have been successfully persisted, or until a failure occurs.

      When publishing to a store, and the administrator has configured publisher mode store_confirm_send for the store, the non-inline send policy changes the behavior of `send(Message msg)`.

      - Calls to `send(Message msg)` return immediately, unless the maximum batch count has been reached. The message will be persisted in the background. See `PROPERTY_INT_MAX_BATCH_COUNT`.
      - If a failure occurs in the background, the next call to `send(Message msg)` or `flush()` will raise an exception. When this happens the application must assume that the most recent messages, up to the maximum batch count and including the message passed to `send(Message msg)`, have been lost. See `PROPERTY_INT_MAX_BATCH_COUNT`.
      - When the application calls `close()`, some messages may not have been persisted. In this case the close call may linger for some time before discarding the messages. See `PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER`.
      - Applications may call `flush()` to wait for all outstanding messages to be persisted.
      - If a failure occurs in the background, an advisory will be generated. This is a hint to the application that an error has occurred, and that a call to `flush()` will raise an exception. See `Advisory.NAME_NONINLINE_SEND_LOSS`.

      The `getSendPolicy()` call returns the value currently in effect.

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

    - #### PROPERTY_BOOL_RELEASE_MSGS_TO_SEND

          static final java.lang.String PROPERTY_BOOL_RELEASE_MSGS_TO_SEND

      Ownership of outbound messages; boolean.

      When `false` or absent, client program code retains ownership of outbound messages that it sends through this publisher.

      When `true`, the FTL library accepts ownership of outbound messages that the client sends through this publisher. Client code releases the message object when it invokes the send call; from that moment onward, client code must not reference the message object, because the FTL library can destroy the message object at any time.

      Client code can release a message only if client owns the message. In particular, if a subscriber does not release its messages to the callback, then the callback must not send it through a publisher that releases messages. (See `Subscriber.PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK` .)

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

    - #### PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

          static final java.lang.String PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

      Retry duration for persistent publisher operations; double.

      When `Realm.createPublisher(java.lang.String)` or `send(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 publisher 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 publisher or the realm supersedes and cancels retry behavior.

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

    - #### PROPERTY_INT_MAX_BATCH_COUNT

          static final java.lang.String PROPERTY_INT_MAX_BATCH_COUNT

      Maximum batch count for non-inline publishers; integer.

      When a persistence publisher is configured for non-inline send, this is the maximum number of messages that may be in flight to the persistence service at any given time. When this limit is reached, `send(Message msg)` blocks until some messages can be persisted, or a failure occurs. The default value is 100.

      The `getMaxBatchCount()` call returns the value currently in effect.

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

    - #### PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER

          static final java.lang.String PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER

      Linger duration for persistent publisher close operation; double.

      When a persistence publisher is configured for non-inline send, and a call to `close()` is made while there are still messages waiting to be persisted, the call can be configured to wait for some time before closing the publisher. If the linger period elapses, and the messages have not been successfully persisted, the messages will be discarded. Set this property to control the linger behavior of `close()`. The default value is 30 seconds.

      Values:

      - 0 Close the publisher immediately.
      - -1 Close the publisher only after it successfully persisted all outstanding messages
      - n (Any positive double value) Wait for the publisher to persist outstanding messages for at most n seconds. Proceed with closing the publisher upon success or timeout, whichever comes first.

      Closing the realm supersedes and cancels linger behavior.

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

  - ### Method Detail

    - #### send

          void send(Message msg)
             throws FTLException

      Send a message, one-to-many.

      If the administrator has configured publisher mode store_confirm_send for the store, a persistence publisher may block in this call until the message has been persisted. Otherwise the call returns immediately, and the message may or may not be stored.

      For persistence publishers, the exact semantics depend on the send policy. See `PROPERTY_INT_SEND_POLICY`.

      Parameters:
        `msg` - The method sends this message.
      Throws:
        `FTLException`

    - #### send

          void send(Message[] messages)
             throws FTLException

      Send an array of messages, one-to-many.

      The application sends each message in the array, in order.

      Sending an array of messages eliminates the overhead cost of a separate call for each message.

      If the administrator has configured publisher mode store_confirm_send for the store, a persistence publisher will block in this call until all messages have been persisted. Otherwise the call returns immediately, and the messages may or may not be stored.

      Parameters:
        `messages` - The method sends all the messages from this array.
      Throws:
        `FTLException`

    - #### send

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

      Send a subset of messages from an array of messages.

      The application sends `messageCount` messages from the array, in order.

      Sending an array of messages eliminates the overhead cost of a separate call for each message.

      If the administrator has configured publisher mode store_confirm_send for the store, a persistence publisher will block in this call until all messages have been persisted. Otherwise the call returns immediately, and the messages may or may not be stored.

      Parameters:
        `messages` - The method sends messages from this array.
        `messageCount` - Supply the number of messages to send.
      Throws:
        `FTLException`

    - #### sendToInbox

          void sendToInbox(Inbox inbox,
                           Message msg)
                    throws FTLException

      Send an inbox message to an inbox.

      Because inbox messages do not trigger the content matchers of other subscribers on the endpoint, they are an efficient way to target a message to a specific destination. For example, you might use an inbox message to query a specific data source, or to reply to a query.

      For details about getting an inbox, see `Realm.createInboxSubscriber`, `Message.getInbox` and `Inbox`.

      Parameters:
        `inbox` - The method sends the message to this inbox.
        `msg` - The method sends this message.
      Throws:
        `FTLException`

    - #### sendRequest

          Message sendRequest(Message request,
                              double timeout)
                       throws FTLException

      Send a request and wait for reply.

      Send a request and wait for a reply within a specified timeout.

      Parameters:
        `request` - The request message.
        `timeout` - The maximum time (in seconds) to wait for a reply.
      Throws:
        `FTLException`

    - #### sendReply

          void sendReply(Message reply,
                         Message request)
                  throws FTLException

      Send a reply message to a requester.

      Upon receiving a request message, send a reply message to the requester.

      Parameters:
        `reply` - The reply message.
        `request` - The original request message.
      Throws:
        `FTLException`

    - #### close

          void close()
              throws FTLException

      Close a publisher.

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

      Throws:
        `FTLException`

    - #### flush

          void flush()
              throws FTLException

      When the publisher's send policy is non-inline, flush all outsanding messages.

      When a persistence publisher is configured for non-inline send, calls to `send(Message msg)` may return before the message is persisted. Applications may call this function to ensure that all outstanding messages have been persisted (for example, if the application intends to close the publisher). This function blocks until all messages have been persisted, or until a failure occurs. If a failure occurs, this call will raise an exception.

      Throws:
        `FTLException`

    - #### getSendPolicy

          int getSendPolicy()
                     throws FTLException

      Returns the send policy of a publisher.

      Returns the send policy that is in effect for this publisher. Applications may use this call to determine appropriate behavior if a persistence publisher fails to persist a message.

      See `PROPERTY_INT_SEND_POLICY`.

      Returns:
        the send policy
      Throws:
        `FTLException`

    - #### getMaxBatchCount

          int getMaxBatchCount()
                        throws FTLException

      Returns the maximum batch count of a non-inline publisher.

      Returns the maximum batch count that is in effect for this publisher. Applications may use this call to determine appropriate behavior if a non-inline persistence publisher fails to persist a message.

      See `PROPERTY_INT_MAX_BATCH_COUNT`.

      Returns:
        the maximum batch count
      Throws:
        `FTLException`