ConsistentRegionConfig (Java Application API for IBM Streams)
Date: 2020-08-07

com.ibm.streamsx.topology.consistent

## Class ConsistentRegionConfig

- java.lang.Object
- - com.ibm.streamsx.topology.consistent.ConsistentRegionConfig

-     public final class ConsistentRegionConfig
      extends java.lang.Object

  Immutable consistent region configuration. The default values for a `ConsistentRegionConfig` are:
  - `drainTimeout` - 180 seconds - Indicates the maximum time in seconds that the drain and checkpoint of the region is allotted to finish processing. If the process takes longer than the specified time, a failure is reported and the region is reset to the point of the previously successfully established consistent state.
  - `resetTimeout` - 180 seconds - Indicates the maximum time in seconds that the reset of the region is allotted to finish processing. If the process takes longer than the specified time, a failure is reported and another reset of the region is attempted
  - `maxConsecutiveResetAttempts` - 5 - Indicates the maximum number of consecutive attempts to reset a consistent region. After a failure, if the maximum number of attempts is reached, the region stops processing new tuples. After the maximum number of consecutive attempts is reached, a region can be reset only with manual intervention or with a program with a call to a method in the consistent region controller.

  A configuration has `time unit` that applies to `getPeriod()`, `getDrainTimeout()` and `getResetTimeout()`. The time unit is hard-coded to `TimeUnit.SECONDS`, future versions may allow creating configurations with a different time unit.

  Example Use:

       // set source to be a the start of an operator driven consistent region
       // with a drain timeout of five seconds and a reset timeout of twenty seconds.
       source.setConsistent(operatorDriven().drainTimeout(5).resetTimeout(20));

  See Also:
    `TStream.setConsistent(ConsistentRegionConfig)`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ConsistentRegionConfig.Trigger` Defines how the drain-checkpoint cycle of a consistent region is triggered.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ConsistentRegionConfig()` Create a `ConsistentRegionConfig.Trigger.OPERATOR_DRIVEN` consistent region configuration.
    `ConsistentRegionConfig(int period)` Create a `ConsistentRegionConfig.Trigger.PERIODIC` consistent region configuration.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `ConsistentRegionConfig` | `drainTimeout(long drainTimeout)` Return a new configuration changing `drainTimeout`.
    `boolean` | `equals(java.lang.Object obj)`
    `long` | `getDrainTimeout()` Get the drain timeout for this configuration.
    `int` | `getMaxConsecutiveResetAttempts()` Get the maximum number of consecutive reset attempts.
    `long` | `getPeriod()` Get the trigger period.
    `long` | `getResetTimeout()` Get the reset timeout for this configuration.
    `java.util.concurrent.TimeUnit` | `getTimeUnit()` Get the time unit for `getPeriod()`, `getDrainTimeout()` and `getResetTimeout()()`.
    `ConsistentRegionConfig.Trigger` | `getTrigger()` Get the trigger type.
    `int` | `hashCode()`
    `ConsistentRegionConfig` | `maxConsecutiveResetAttempts(int attempts)` Return a new configuration changing `maxConsecutiveResetAttempts`.
    `static ConsistentRegionConfig` | `operatorDriven()` Create a `ConsistentRegionConfig.Trigger.OPERATOR_DRIVEN` consistent region configuration.
    `static ConsistentRegionConfig` | `periodic(int period)` Create a `ConsistentRegionConfig.Trigger.PERIODIC` consistent region configuration.
    `ConsistentRegionConfig` | `resetTimeout(long resetTimeout)` Return a new configuration changing `resetTimeout`.

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

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

- - ### Constructor Detail

    - #### ConsistentRegionConfig

          public ConsistentRegionConfig()

      Create a `ConsistentRegionConfig.Trigger.OPERATOR_DRIVEN` consistent region configuration. The source operator drives when a region is drained and checkpointed, for example a messaging source might drain and checkpoint every ten thousand messages.
      Configuration values are set to the default values.

    - #### ConsistentRegionConfig

          public ConsistentRegionConfig(int period)

      Create a `ConsistentRegionConfig.Trigger.PERIODIC` consistent region configuration. The IBM Streams runtime will trigger a drain and checkpoint the region periodically approximately every `period` seconds.
      Configuration values are set to the default values.
      Parameters:
        `period` - Trigger period in seconds.

  - ### Method Detail

    - #### operatorDriven

          public static ConsistentRegionConfig operatorDriven()

      Create a `ConsistentRegionConfig.Trigger.OPERATOR_DRIVEN` consistent region configuration. The source operator triggers drain and checkpoint cycles for the region.
      Configuration values are set to the default values.

      This is equivalent to `ConsistentRegionConfig()` but when used as an imported static method can produce clearer code:

           import static com.ibm.streamsx.topology.consistent.ConsistentRegionConfig.operatorDriven;
           ...
               stream.setConsistent(operatorDriven());

    - #### periodic

          public static ConsistentRegionConfig periodic(int period)

      Create a `ConsistentRegionConfig.Trigger.PERIODIC` consistent region configuration. The IBM Streams runtime will trigger a drain and checkpoint the region periodically approximately every `period` seconds.
      Configuration values are set to the default values.

      This is equivalent to `ConsistentRegionConfig(int)` but when used as an imported static method can produce clearer code:

           import static com.ibm.streamsx.topology.consistent.ConsistentRegionConfig.periodic;
           ...
               stream.setConsistent(periodic(30));

      Parameters:
        `period` - Trigger period in seconds.

    - #### getTrigger

          public ConsistentRegionConfig.Trigger getTrigger()

      Get the trigger type.
      Returns:
        trigger type.

    - #### getPeriod

          public long getPeriod()

      Get the trigger period.
      Returns:
        period if `getTrigger()` is `ConsistentRegionConfig.Trigger.PERIODIC` otherwise -1.

    - #### getTimeUnit

          public java.util.concurrent.TimeUnit getTimeUnit()

      Get the time unit for `getPeriod()`, `getDrainTimeout()` and `getResetTimeout()()`.
      Returns:
        Time unit for this configuration.

    - #### getDrainTimeout

          public long getDrainTimeout()

      Get the drain timeout for this configuration.
      Returns:
        Drain timeout in units of `getTimeUnit()`.

    - #### drainTimeout

          public ConsistentRegionConfig drainTimeout(long drainTimeout)

      Return a new configuration changing `drainTimeout`. A new configuration instance is returned that is a copy of this configuration with only `drainTimeout` changed.

      `stream.setConsistent(periodic(30).drainTimeout(5))`

      Parameters:
        `drainTimeout` - Drain timeout to use in seconds, must be greater than 0.
      Returns:
        New configuration with drain timeout set to `drainTimeout` and the remaining values copied from this configuration.

    - #### getResetTimeout

          public long getResetTimeout()

      Get the reset timeout for this configuration.
      Returns:
        Reset timeout in units of `getTimeUnit()`.

    - #### resetTimeout

          public ConsistentRegionConfig resetTimeout(long resetTimeout)

      Return a new configuration changing `resetTimeout`. A new configuration instance is returned that is a copy of this configuration with only `resetTimeout` changed.

      `stream.setConsistent(periodic(30).resetTimeout(15))`

      Parameters:
        `resetTimeout` - Reset timeout to use in seconds, must be greater than 0.
      Returns:
        New configuration with reset timeout set to `resetTimeout` and the remaining values copied from this configuration.

    - #### getMaxConsecutiveResetAttempts

          public int getMaxConsecutiveResetAttempts()

      Get the maximum number of consecutive reset attempts.
      Returns:
        Maximum number of consecutive reset attempts.

    - #### maxConsecutiveResetAttempts

          public ConsistentRegionConfig maxConsecutiveResetAttempts(int attempts)

      Return a new configuration changing `maxConsecutiveResetAttempts`. A new configuration instance is returned that is a copy of this configuration with only `maxConsecutiveResetAttempts` changed.

      `stream.setConsistent(periodic(30).maxConsecutiveResetAttempts(7))`

      Parameters:
        `attempts` - Maximum number of consecutive reset attempts, must be greater than 0.
      Returns:
        New configuration with maxConsecutiveResetAttempts set to `attempts` and the remaining values copied from this configuration.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals(java.lang.Object obj)

      Overrides:
        `equals` in class `java.lang.Object`