Package oracle.kv.pubsub

# Interface NoSQLSubscriber

All Superinterfaces:
  `Subscriber<StreamOperation>`

public interface NoSQLSubscriber extends Subscriber<StreamOperation>
The subscriber interface is to be implemented by the application. The NoSQLSubscriber interface defines additional methods that are described below along with details of NoSQL-specific considerations for the existing methods.

Implementation of NOSQLSubscriber should follow the Subscriber rules in the Reactive Streams Specification.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `NoSQLSubscriptionConfig`
  `getSubscriptionConfig()`
  Invoked by the NoSQL publisher when creating a Subscription.
  `default void`
  `onChangeResult(StreamPosition streamPosition, Throwable failureCause)`
  Signals when a request to add or remove a table from the set of subscribed tables is completed.
  `void`
  `onCheckpointComplete(StreamPosition streamPosition, Throwable failureCause)`
  Signals when a previously requested checkpoint is completed.
  `void`
  `onComplete()`
  Signals the completion of a subscription
  `void`
  `onError(Throwable t)`
  Signals an unrecoverable error in subscription.
  `void`
  `onNext(StreamOperation t)`
  Signals the next NoSQL Operation.
  `void`
  `onSubscribe(Subscription s)`
  Invoked after the `NoSQLPublisher` has successfully established contact with the store using helper hosts.
  `void`
  `onWarn(Throwable t)`
  Signals a warning during subscription.

- ## Method Details

  - ### onSubscribe

    void onSubscribe(Subscription s)
    Invoked after the `NoSQLPublisher` has successfully established contact with the store using helper hosts. When this method is called by NoSQLPublisher, the argument is an implementation of `NoSQLSubscription`.
    Specified by:
      `onSubscribe` in interface `Subscriber<StreamOperation>`
    See Also:
      - `NoSQLSubscription.request(long)`

  - ### onNext

    void onNext(StreamOperation t)
    Signals the next NoSQL Operation.

    The sequence of onNext calls represents the stream of changes, both updates and deletions, made to the store. The order of calls to onNext for a given key represents the exact order of the operations on that key performed on the store. There are no guarantees about the order of operations across different keys in the stream.

    If a shard is down, events associated with rows stored on that shard could be arbitrarily delayed until the shard comes back up again and the NoSQL Publisher can establish a shard stream to it.

    Specified by:
      `onNext` in interface `Subscriber<StreamOperation>`

  - ### onError

    void onError(Throwable t)
    Signals an unrecoverable error in subscription.

    There are many potential sources of error that the publisher may signal via this method. One of them is worth special mention: the publisher may invoke this method if it finds that it cannot resume the stream from `NoSQLSubscriptionConfig.getInitialPosition()` because the relevant logs are no longer available at one of the shards.

    Specified by:
      `onError` in interface `Subscriber<StreamOperation>`

  - ### onComplete

    void onComplete()
    Signals the completion of a subscription

    Note streaming from kvstore table is unbounded by nature since unbounded updates can be applied to a table. Thus onComplete() will never be called in Stream API. User of Stream API shall implement this method as no-op and any no-op implementation will be ignored.

    Specified by:
      `onComplete` in interface `Subscriber<StreamOperation>`

  - ### getSubscriptionConfig

    NoSQLSubscriptionConfig getSubscriptionConfig()
    Invoked by the NoSQL publisher when creating a Subscription. The implementation of this method should return a configuration that identifies the desired position for starting streaming, the tables whose data should be streamed, and other configuration information.

    An ill configuration or null return will cancel the subscription and the publisher will release all resources allocated for that subscription.

    Returns:
      the configuration for creating the subscription

  - ### onWarn

    void onWarn(Throwable t)
    Signals a warning during subscription.

    A call to this method warns the user of a potential issue that does not yet represent a disruption in service, for example, a warning that a shard was not available for an extended period of time. Note that onWarn, unlike onError, does not terminate the flow of signals. It's used to warn the subscriber that the publisher's functioning is impaired, but not as yet fatally and some exception-specific action could be taken to restore the health of the Publisher.

  - ### onCheckpointComplete

    void onCheckpointComplete(StreamPosition streamPosition, Throwable failureCause)
    Signals when a previously requested checkpoint is completed. If checkpoint fails for any reason, the subscription will skip this checkpoint for certain shards and continue streaming. The subscription will try the next checkpoint when it comes.

    Note that the stream position checkpoint may not be the one originally supplied if `NoSQLSubscription.doCheckpoint(StreamPosition, boolean)` is called to do checkpoint with `exact` is set to false.

    Parameters:
      `streamPosition` - the stream position in checkpoint
      `failureCause` - null if checkpoint succeeds, otherwise the cause of checkpoint failure.

  - ### onChangeResult

    default void onChangeResult(StreamPosition streamPosition, Throwable failureCause)
    Signals when a request to add or remove a table from the set of subscribed tables is completed. If the change was successful, this method will be called with a non-null stream position that represents the first stream position for which the change has taken effect. This method will be called before any entries for that stream position are provided to a call to `onNext(oracle.kv.pubsub.StreamOperation)`. If the change was unsuccessful but the subscription is still active, this method will be called with a non-null exception that describes the cause of the failure. If the change caused the subscription to be canceled, this method will not be called, and the `onError(java.lang.Throwable)` method will be called instead.

    In particular, this method will be called with a `SubscriptionChangeNotAppliedException` whose `reason` is one of:

    - `TOO_MANY_PENDING_CHANGES`
    - `SUBSCRIPTION_CANCELED`
    - `SUBSCRIPTION_ALL_TABLES`
    - `TABLE_ALREADY_SUBSCRIBED`
    - `TABLE_NOT_SUBSCRIBED`
    - `SubscriptionChangeNotAppliedException.Reason.CHANGE_TIMEOUT`

    This method will be called with `SubscriptionTableNotFoundException` if the table does not exist.

    If the subscription is unable to apply a requested change to all shards, the subscription will be canceled and the `onError` method will be called with a `SubscriptionFailureException`.

    The default implementation does nothing.

    Parameters:
      `streamPosition` - the effective stream position of the change, or null if the change failed
      `failureCause` - null if the change was applied successfully, otherwise cause of the failure
    See Also:
      - `NoSQLSubscription.subscribeTable(java.lang.String)`
      - `NoSQLSubscription.unsubscribeTable(java.lang.String)`