Package oracle.kv.pubsub

# Interface NoSQLSubscription

All Superinterfaces:
  `Subscription`

public interface NoSQLSubscription extends Subscription
A NoSQL subscription to the source kvstore. It is created by an instance of NoSQLPublisher with given subscription configuration.

A NoSQL subscription has real resources (threads, network connections, iterator state etc.) associated with it. These resources are released when the subscription is canceled via `cancel()`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `cancel()`
  Clean up and free resources; terminates shard streams in particular.
  `void`
  `doCheckpoint(StreamPosition streamPosition)`
  Do subscription checkpoint.
  `void`
  `doCheckpoint(StreamPosition streamPosition, boolean exact)`
  Do subscription checkpoint at the given stream position or a stream position later than the given position selected by the Streams API.
  `StreamPosition`
  `getCurrentPosition()`
  Returns a current position in the stream.
  `StreamPosition`
  `getLastCheckpoint()`
  Gets the last checkpoint stored in kv store for the given subscription.
  `StreamPosition`
  `getOptimizedPosition(StreamPosition streamPosition)`
  Returns a stream position that represents the same operations supplied to `NoSQLSubscriber.onNext(oracle.kv.pubsub.StreamOperation)`, but one that is optimized for checkpoints.
  `Set<String>`
  `getSubscribedTables()`
  Returns the set of currently subscribed tables.
  `NoSQLSubscriberId`
  `getSubscriberId()`
  Returns ID of the subscriber that created the subscription.
  `SubscriptionMetrics`
  `getSubscriptionMetrics()`
  Returns the subscription metrics `SubscriptionMetrics`
  `boolean`
  `isCanceled()`
  Returns true if the subscription has been canceled.
  `void`
  `request(long n)`
  Streams a fixed number operations from source kvstore interested to the subscribed tables.
  `void`
  `subscribeTable(String tableName)`
  Adds a table to the set of subscribed tables for a running subscription.
  `void`
  `subscribeTable(String tableName, boolean streamTxn)`
  Adds a subscribed table to the running subscription, and specify if to stream transaction.
  `void`
  `unsubscribeTable(String tableName)`
  Removes a table from the set of subscribed tables for a running subscription.

- ## Method Details

  - ### request

    void request(long n)
    Streams a fixed number operations from source kvstore interested to the subscribed tables.
    Specified by:
      `request` in interface `Subscription`

  - ### cancel

    void cancel()
    Clean up and free resources; terminates shard streams in particular.
    Specified by:
      `cancel` in interface `Subscription`

  - ### getSubscriberId

    NoSQLSubscriberId getSubscriberId()
    Returns ID of the subscriber that created the subscription.
    Returns:
      ID of the subscriber that created the subscription

  - ### getCurrentPosition

    StreamPosition getCurrentPosition()
    Returns a current position in the stream. All elements before this position have been delivered to the Subscriber via `NoSQLSubscriber.onNext(oracle.kv.pubsub.StreamOperation)`, and delivering the element for the current position to `onNext` is either about to begin, underway, or also complete.

    Although this position can be used by a subsequent subscriber to resume the stream from this point forwards, effectively resuming an earlier subscription, it is preferable either to use the stream position returned by `getOptimizedPosition(StreamPosition)`, or to call `doCheckpoint(StreamPosition, boolean)` and specify false for `exact`. Both of those approaches use a later position if possible, and therefore should increase the odds that the checkpoint will be available to resume. When the position returned by this method or `getOptimizedPosition(StreamPosition)` is used to do checkpoint, the caller needs to ensure all earlier operations before the position have been processed, and it is safe to resume the stream from the position.

    Returns:
      current stream position

  - ### getLastCheckpoint

    StreamPosition getLastCheckpoint()
    Gets the last checkpoint stored in kv store for the given subscription.

    If `doCheckpoint(StreamPosition)` or, `doCheckpoint(StreamPosition, boolean)` is called with `exact` is set to true is called to checkpoint, it returns the supplied stream position if the checkpoint is successful.

    If `doCheckpoint(StreamPosition, boolean)` is called with `exact` is set to false, a higher stream position can be used to checkpoint and therefore it may return a higher stream position than the supplied one.

    Returns:
      the last checkpoint associated with that subscription, or null if this subscription does not have any persisted checkpoint in kvstore.

  - ### isCanceled

    boolean isCanceled()
    Returns true if the subscription has been canceled.
    Returns:
      true if the subscription has been canceled, false otherwise.

  - ### doCheckpoint

    void doCheckpoint(StreamPosition streamPosition)
    Do subscription checkpoint. This is equivalent to calling `doCheckpoint(StreamPosition, boolean)` with `exact` is set to true. The checkpoint will be made to the source kvstore. The checkpoint from a subscription is stored in a table dedicated to this particular subscription. Each row in the table represents a checkpoint for a shard. Each row is inserted when the checkpoint is made for the first time, and updated when subsequent checkpoint is made.

    Note the checkpoint is an asynchronous call. When called, it creates a separate thread to do the check to kvstore, and it itself instantly returns to caller. The result of checkpoint will be signaled to subscriber via `NoSQLSubscriber.onCheckpointComplete(oracle.kv.pubsub.StreamPosition, java.lang.Throwable)`.

    The caller needs to ensure all operations up to the given stream position have been processed and it is safe to resume stream from the given stream position and no operation will be missing after resumption.

    Unless the application has its own need to store an exact checkpoint position, in most cases it is preferable to call `doCheckpoint(StreamPosition, boolean)` and specify false for `exact`, or store the value returned by `getOptimizedPosition(oracle.kv.pubsub.StreamPosition)`, both of which may be able to checkpoint a higher position.

    It is illegal to call this method concurrently for a subscription. The method should be called only after `NoSQLSubscriber.onCheckpointComplete(oracle.kv.pubsub.StreamPosition, java.lang.Throwable)` is called in the previous call of this method, which indicates the previous checkpoint is done. Otherwise `SubscriptionFailureException` will be raised.

    Parameters:
      `streamPosition` - the stream position to checkpoint

  - ### doCheckpoint

    void doCheckpoint(StreamPosition streamPosition, boolean exact)
    Do subscription checkpoint at the given stream position or a stream position later than the given position selected by the Streams API. The checkpoint will be made to the source kvstore like `doCheckpoint(StreamPosition)`. If `exact` is true, the checkpoint will be made at exact `streamPosition`. Otherwise, Streams API will use a stream position returned by `getOptimizedPosition(StreamPosition)` to checkpoint.
    Parameters:
      `streamPosition` - the stream position to checkpoint
      `exact` - true if checkpoint at exact given position, false if use an optimized stream position to checkpoint.

  - ### getOptimizedPosition

    StreamPosition getOptimizedPosition(StreamPosition streamPosition)
    Returns a stream position that represents the same operations supplied to `NoSQLSubscriber.onNext(oracle.kv.pubsub.StreamOperation)`, but one that is optimized for checkpoints. The returned position is equal or later than the given position for all replication groups. Applications should use the results of calling this method when saving a stream position as a checkpoint. The benefit of later position is that a later position is more likely to be available when the stream resumes.
    Parameters:
      `streamPosition` - the stream position to checkpoint
    Returns:
      an optimized stream position

  - ### getSubscriptionMetrics

    SubscriptionMetrics getSubscriptionMetrics()
    Returns the subscription metrics `SubscriptionMetrics`
    Returns:
      the subscription metrics

  - ### subscribeTable

    void subscribeTable(String tableName)
    Adds a table to the set of subscribed tables for a running subscription. The subscription will apply the change to every shard in kvstore. This method is asynchronous and will return immediately. The `NoSQLSubscriber.onChangeResult(StreamPosition, Throwable)` method will be called when the change is complete. If it fails, `NoSQLSubscriber.onChangeResult(StreamPosition, Throwable)` will be called when the subscription does not need terminate, and `NoSQLSubscriber.onError(Throwable)` will be called when the subscription need terminate. Calling this method does not block the running subscription.
    Parameters:
      `tableName` - the name of the table to subscribe, which is either an non-prefixed name that specifies a table in the default namespace, or a name with the namespace prefix and a colon followed by the table name.

  - ### subscribeTable

    void subscribeTable(String tableName, boolean streamTxn)
    Adds a subscribed table to the running subscription, and specify if to stream transaction. This method is identical to `subscribeTable(String)`, except that user can specify if the writes to the subscribed table should be streamed as transactions or not.
    Parameters:
      `tableName` - the name of the table to subscribe, which is either an non-prefixed name that specifies a table in the default namespace, or a name with the namespace prefix and a colon followed by the table name.
      `streamTxn` - true if to stream transactions, false to stream write operations in `StreamOperation`.

  - ### unsubscribeTable

    void unsubscribeTable(String tableName)
    Removes a table from the set of subscribed tables for a running subscription. The subscription will apply the change to every shard in kvstore. This method is asynchronous and will return immediately.The `NoSQLSubscriber.onChangeResult(StreamPosition, Throwable)` method will be called when the change is complete. If it fails, `NoSQLSubscriber.onChangeResult(StreamPosition, Throwable)` will be called when the subscription does not need terminate, and `NoSQLSubscriber.onError(Throwable)` will be called when the subscription need terminate. Calling this method does not block the running subscription.
    Parameters:
      `tableName` - the name of the table to subscribe, which is either an non-prefixed name that specifies a table in the default namespace, or a name with the namespace prefix and a colon followed by the table name.

  - ### getSubscribedTables

    Set<String> getSubscribedTables() throws SubscriptionFailureException
    Returns the set of currently subscribed tables. If the subscription is configured to stream all user tables, returns null.
    Returns:
      the set of currently subscribed tables, or null.
    Throws:
      `SubscriptionFailureException` - if the subscription is canceled.