Package oracle.kv.pubsub

Interface NoSQLSubscription

  • All Superinterfaces:
    org.reactivestreams.Subscription
    public interface NoSQLSubscription
extends org.reactivestreams.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 org.reactivestreams.Subscription

      • cancel

        void cancel()
        Clean up and free resources; terminates shard streams in particular.
        Specified by:
        cancel in interface org.reactivestreams.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 up to and including this position have been delivered to the Subscriber via NoSQLSubscriber.onNext(oracle.kv.pubsub.StreamOperation).

        This position can be used by a subsequent subscriber to resume the stream from this point forwards, effectively resuming an earlier subscription.

        Returns:
        current stream position

      • getLastCheckpoint

        StreamPosition getLastCheckpoint()
        Gets the last checkpoint stored in kv store for the given subscription
        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. 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).

        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

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

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