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 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:

    • 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:

      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: