Interface NoSQLSubscription
- All Superinterfaces:
org.reactivestreams.Subscription
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 TypeMethodDescriptionvoid
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.Returns a current position in the stream.Gets the last checkpoint stored in kv store for the given subscription.getOptimizedPosition
(StreamPosition streamPosition) Returns a stream position that represents the same operations supplied toNoSQLSubscriber.onNext(oracle.kv.pubsub.StreamOperation)
, but one that is optimized for checkpoints.Returns the set of currently subscribed tables.Returns ID of the subscriber that created the subscription.Returns the subscription metricsSubscriptionMetrics
boolean
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
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 interfaceorg.reactivestreams.Subscription
-
cancel
void cancel()Clean up and free resources; terminates shard streams in particular.- Specified by:
cancel
in interfaceorg.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 viaNoSQLSubscriber.onNext(oracle.kv.pubsub.StreamOperation)
.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 calldoCheckpoint(StreamPosition, boolean)
and specify false forexact
. Both of those approaches use a later position if possible, and therefore should increase the odds that the checkpoint will be available to resume.- 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 withexact
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 withexact
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
Do subscription checkpoint. This is equivalent to callingdoCheckpoint(StreamPosition, boolean)
withexact
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 forexact
, or store the value returned bygetOptimizedPosition(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. OtherwiseSubscriptionFailureException
will be raised.- Parameters:
streamPosition
- the stream position to checkpoint
-
doCheckpoint
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 likedoCheckpoint(StreamPosition)
. Ifexact
is true, the checkpoint will be made at exactstreamPosition
. Otherwise, Streams API will use a stream position returned bygetOptimizedPosition(StreamPosition)
to checkpoint.- Parameters:
streamPosition
- the stream position to checkpointexact
- true if checkpoint at exact given position, false if use an optimized stream position to checkpoint.
-
getOptimizedPosition
Returns a stream position that represents the same operations supplied toNoSQLSubscriber.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 metricsSubscriptionMetrics
- Returns:
- the subscription metrics
-
subscribeTable
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. TheNoSQLSubscriber.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, andNoSQLSubscriber.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
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.TheNoSQLSubscriber.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, andNoSQLSubscriber.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
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.
-