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 Detail

      • 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

      • subscribeTable

        void subscribeTable​(java.lang.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.

      • unsubscribeTable

        void unsubscribeTable​(java.lang.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

        java.util.Set<java.lang.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.