Package oracle.kv.pubsub

# Class NoSQLSubscriptionConfig.Builder

java.lang.Object
oracle.kv.pubsub.NoSQLSubscriptionConfig.Builder

Enclosing class:
  NoSQLSubscriptionConfig

public static class NoSQLSubscriptionConfig.Builder extends Object
Builder to construct a NoSQLSubscriptionConfig instance

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Builder(String ckptTableName)`
  Makes a builder for NoSQLSubscriptionConfig with required parameter for single subscriber, that is, the `NoSQLSubscriberId.getTotal()` is 1.
  `Builder(Function<NoSQLSubscriberId,String> ckptTableMapper)`
  Makes a builder for NoSQLSubscriptionConfig with required parameter for multiple sharded subscribers, that is, the `NoSQLSubscriberId.getTotal()` is greater than 1.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `NoSQLSubscriptionConfig`
  `build()`
  Builds a NoSQLSubscriptionConfig instance from builder
  `NoSQLSubscriptionConfig.Builder`
  `setChangeTimeoutMs(long changeTimeoutMs)`
  Sets the subscription change timeout in milliseconds.
  `NoSQLSubscriptionConfig.Builder`
  `setCreateNewCheckpointTable(boolean allow)`
  Sets if publisher is allowed to create a new checkpoint table if it does not exist.
  `NoSQLSubscriptionConfig.Builder`
  `setEmptyStreamDuration(int emptyStreamSecs)`
  Sets the empty stream duration.
  `NoSQLSubscriptionConfig.Builder`
  `setIncludeBeforeImage(boolean includeBeforeImage)`
  Sets if the subscription should include before image of subscribed tables in stream events represented by `StreamOperation`.
  `NoSQLSubscriptionConfig.Builder`
  `setLocalWritesOnly(boolean localWritesOnly)`
  Sets that when subscribing multi-region tables, whether only local writes are streamed.
  `NoSQLSubscriptionConfig.Builder`
  `setMaxReconnect(long maxReconnect)`
  Sets the max number of reconnect if stream is down
  `NoSQLSubscriptionConfig.Builder`
  `setOutputQueueSizeMB(int sz)`
  Sets the output queue size in megabytes.
  `NoSQLSubscriptionConfig.Builder`
  `setStartStreamPosition(StreamPosition position)`
  Sets the start stream position.
  `NoSQLSubscriptionConfig.Builder`
  `setStreamDeliveryMode(NoSQLSubscriptionConfig.StreamDeliveryMode mode, String... tables)`
  Sets stream delivery mode `NoSQLSubscriptionConfig.StreamDeliveryMode` for given tables.
  `NoSQLSubscriptionConfig.Builder`
  `setStreamMode(NoSQLStreamMode mode)`
  Sets the stream mode.
  `NoSQLSubscriptionConfig.Builder`
  `setSubscribedTables(String... tables)`
  Sets the subscribed tables under given namespace.
  `NoSQLSubscriptionConfig.Builder`
  `setSubscribedTables(Set<String> tables)`
  Sets the subscribed tables under given namespace.
  `NoSQLSubscriptionConfig.Builder`
  `setSubscriberId(NoSQLSubscriberId id)`
  Sets the subscriber id which owns the subscription.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### Builder

    public Builder(String ckptTableName)
    Makes a builder for NoSQLSubscriptionConfig with required parameter for single subscriber, that is, the `NoSQLSubscriberId.getTotal()` is 1.

    The checkpoint table can be specified in one of following formats:

    1. tablename, e.g., "MyCkptTable". The given table should be existent or will be created in system default table space.
    2. namespace:tablename, e.g., "MyNameSpace:MyTable". The given table should be existent or will be created in in the given name space.
    Parameters:
      `ckptTableName` - the full namespace name of checkpoint table. The checkpoint table cannot be a child table.
    Throws:
      `IllegalArgumentException` - if the checkpoint table name is null or empty

  - ### Builder

    public Builder(Function<NoSQLSubscriberId,String> ckptTableMapper)
    Makes a builder for NoSQLSubscriptionConfig with required parameter for multiple sharded subscribers, that is, the `NoSQLSubscriberId.getTotal()` is greater than 1.

    Sets a function that maps a subscriber ID to the name of the associated checkpoint table. The checkpoint table name format should be consistent with that in `Builder(String)`.

    Parameters:
      `ckptTableMapper` - a mapper function to build the checkpoint table name from subscriber id
    Throws:
      `IllegalArgumentException` - if the checkpoint table name mapper function is null

- ## Method Details

  - ### build

    public NoSQLSubscriptionConfig build()
    Builds a NoSQLSubscriptionConfig instance from builder
    Returns:
      a NoSQLSubscriptionConfig instance

  - ### setSubscribedTables

    public NoSQLSubscriptionConfig.Builder setSubscribedTables(Set<String> tables)
    Sets the subscribed tables under given namespace. Each table should be specified in one of following formats:
    1. tablename, e.g., "MyTable". The given table should be existent in system default table space. See `TableAPI.SYSDEFAULT_NAMESPACE_NAME`.
    2. namespace:tablename, e.g., "MyNameSpace:MyTable". The given table should be existent in the given table space.
    If not set or set to null or empty set, the stream will subscribe all user tables from all name spaces.
    Parameters:
      `tables` - set of table names to subscribe
    Returns:
      this instance

  - ### setSubscribedTables

    public NoSQLSubscriptionConfig.Builder setSubscribedTables(String... tables)
    Sets the subscribed tables under given namespace. Each table should be specified in one of following formats:
    1. tablename, e.g., "MyTable". The given table should be existent in initial table space.
    2. namespace:tablename, e.g., "MyNameSpace:MyTable". The given table should be existent in given table space.
    If not set or set to null or empty set, the stream will subscribe all user tables.
    Parameters:
      `tables` - set of table names to subscribe
    Returns:
      this instance

  - ### setSubscriberId

    public NoSQLSubscriptionConfig.Builder setSubscriberId(NoSQLSubscriberId id)
    Sets the subscriber id which owns the subscription. If it is not set, the subscription is considered a singleton subscription with single subscriber streaming from all shards.
    Parameters:
      `id` - subscriber id
    Returns:
      this instance

  - ### setStartStreamPosition

    public NoSQLSubscriptionConfig.Builder setStartStreamPosition(StreamPosition position)
    Sets the start stream position. Depending on stream mode, the start stream position has different semantics as follows.

    If stream mode is set to `NoSQLStreamMode.FROM_CHECKPOINT`, which is the default if stream mode is not set, the stream will start from the checkpoint persisted in the specified checkpoint table, and any specified stream position will be ignored. If the checkpoint table does not exist, the stream will create a new checkpoint table for user if allowed. If the checkpoint table is empty, or if the position specified by the checkpoint table is not available, subscription will stream from the next available position.

    If stream mode is set to `NoSQLStreamMode.FROM_EXACT_CHECKPOINT`, the stream will start from the checkpoint persisted in the specified checkpoint table, and any specified stream position will be ignored. If the table does not exist, the stream will create a new checkpoint table for user if allowed. If the checkpoint table is empty, subscription will to stream from the first available entry. If a checkpoint has been saved but that stream position is not available, the subscription will fail and the publisher will signal `SubscriptionInsufficientLogException` to the subscriber via `NoSQLSubscriber.onError(java.lang.Throwable)`.

    If stream mode is set to `NoSQLStreamMode.FROM_STREAM_POSITION` the stream will start from specified stream position if set. If the start stream position is not available, the subscription will stream from the next available position. If the start stream position is not set or is set to null, `IllegalArgumentException` will be raised when the configuration is created.

    If stream mode is set to `NoSQLStreamMode.FROM_EXACT_STREAM_POSITION`, the stream will start from specified stream position if set. If the specified position is not available, the subscription will fail and the publisher will signal `SubscriptionInsufficientLogException` to the subscriber via `NoSQLSubscriber.onError(java.lang.Throwable)`. If the start stream position is not set or set to null, `IllegalArgumentException` will be raised when the configuration is created.

    If stream mode is set to `NoSQLStreamMode.FROM_NOW`, the stream will start from the latest available stream position and any specified start stream position will be ignored.

    Parameters:
      `position` - stream position to start stream
    Returns:
      this instance

  - ### setCreateNewCheckpointTable

    public NoSQLSubscriptionConfig.Builder setCreateNewCheckpointTable(boolean allow)
    Sets if publisher is allowed to create a new checkpoint table if it does not exist. If not set, the default is that publisher would create a new checkpoint table if it does not exist.
    Parameters:
      `allow` - true if publisher is allowed to create a new checkpoint table for user if it does not exist; false otherwise, and subscription will fail if checkpoint table does not exist.
    Returns:
      this instance

  - ### setStreamMode

    public NoSQLSubscriptionConfig.Builder setStreamMode(NoSQLStreamMode mode) throws IllegalArgumentException
    Sets the stream mode. If not set, the stream mode defaults to `NoSQLStreamMode.FROM_CHECKPOINT`.
    Parameters:
      `mode` - the stream mode
    Returns:
      this instance
    Throws:
      `IllegalArgumentException` - if specified stream mode is null.

  - ### setEmptyStreamDuration

    public NoSQLSubscriptionConfig.Builder setEmptyStreamDuration(int emptyStreamSecs) throws IllegalArgumentException
    Sets the empty stream duration. A stream is considered empty if all subscribed tables have been removed from the subscription. An empty stream is considered to be no longer empty when at least one subscribed table is added successfully to the empty stream. If a stream is empty, the publisher would keep the empty stream alive for a period of time specified, and the publisher would shut down the empty stream when it times out.

    If not set, the empty stream stream duration defaults to 60 seconds.

    Parameters:
      `emptyStreamSecs` - empty stream lifetime in seconds
    Returns:
      this instance
    Throws:
      `IllegalArgumentException` - if specified empty stream lifetime is non-positive.

  - ### setChangeTimeoutMs

    public NoSQLSubscriptionConfig.Builder setChangeTimeoutMs(long changeTimeoutMs) throws IllegalArgumentException
    Sets the subscription change timeout in milliseconds. When the user changes the subscription by adding or removing table, the request would be sent to kvstore and it would timeout if the kvstore does not respond the request within the time period.

    If not set, change timeout defaults to 30000 milliseconds.

    Parameters:
      `changeTimeoutMs` - change timeout in milliseconds
    Returns:
      this instance
    Throws:
      `IllegalArgumentException` - if specified change timeout is non-positive.

  - ### setLocalWritesOnly

    public NoSQLSubscriptionConfig.Builder setLocalWritesOnly(boolean localWritesOnly)
    Sets that when subscribing multi-region tables, whether only local writes are streamed.
    Returns:
      this instance

  - ### setMaxReconnect

    public NoSQLSubscriptionConfig.Builder setMaxReconnect(long maxReconnect)
    Sets the max number of reconnect if stream is down
    Returns:
      this instance

  - ### setOutputQueueSizeMB

    public NoSQLSubscriptionConfig.Builder setOutputQueueSizeMB(int sz)
    Sets the output queue size in megabytes.
    Parameters:
      `sz` - size of output queue in megabytes
    Throws:
      `IllegalArgumentException` - if size is smaller than the default queue size `NoSQLSubscriptionConfig.DEFAULT_OUTPUT_QUEUE_SIZE_MB`

  - ### setIncludeBeforeImage

    public NoSQLSubscriptionConfig.Builder setIncludeBeforeImage(boolean includeBeforeImage)
    Sets if the subscription should include before image of subscribed tables in stream events represented by `StreamOperation`. By default, subscription does not include before image of subscribed tables in `StreamOperation`. The before image will be included in subscription only if 1) it is enabled in the corresponding subscribed table, and 2) the subscription is configured to include it in stream events. For any stream event, users can check if the before image is enabled by `StreamOperation.isBeforeImageEnabled()`, and check if subscription is configured to include before image by `StreamOperation.includeBeforeImage()`.
    Parameters:
      `includeBeforeImage` - true to include before image in subscription, false otherwise.
    Returns:
      this instance

  - ### setStreamDeliveryMode

    public NoSQLSubscriptionConfig.Builder setStreamDeliveryMode(NoSQLSubscriptionConfig.StreamDeliveryMode mode, String... tables)
    Sets stream delivery mode `NoSQLSubscriptionConfig.StreamDeliveryMode` for given tables. The tables must be the subscribed tables by either `setSubscribedTables(String...)` or `setSubscribedTables(Set)`.
    Parameters:
      `mode` - stream delivery mode
      `tables` - name of tables