org.apache.ignite.configuration

## Class DataRegionConfiguration

- java.lang.Object
- - org.apache.ignite.configuration.DataRegionConfiguration

- All Implemented Interfaces:
    Serializable

      public final class DataRegionConfiguration
      extends Object
      implements Serializable

  This class allows defining custom data regions' configurations with various parameters for Apache Ignite page memory (see `DataStorageConfiguration`. For each configured data region Apache Ignite instantiates respective memory regions with different parameters like maximum size, eviction policy, swapping options, persistent mode flag, etc. An Apache Ignite cache can be mapped to a particular region using `CacheConfiguration.setDataRegionName(String)` method.

  Sample configuration below shows how to configure several data regions:

           <property name="memoryConfiguration">
               <bean class="org.apache.ignite.configuration.DataStorageConfiguration">
                   <property name="defaultRegionConfiguration">
                       <bean class="org.apache.ignite.configuration.DataRegionConfiguration">
                           <property name="name" value="Default_Region"/>
                           <property name="initialSize" value="#{100L * 1024 * 1024}"/>
                           <property name="maxSize" value="#{5L * 1024 * 1024 * 1024}"/>
                       </bean>
                   </property>

                   <property name="pageSize" value="4096"/>

                   <property name="dataRegions">
                       <list>
                            <bean class="org.apache.ignite.configuration.DataRegionConfiguration">
                                <property name="name" value="20MB_Region_Eviction"/>
                                <property name="initialSize" value="#{20L * 1024 * 1024}"/>
                                <property name="pageEvictionMode" value="RANDOM_2_LRU"/>
                            </bean>

                            <bean class="org.apache.ignite.configuration.DataRegionConfiguration">
                                <property name="name" value="25MB_Region_Swapping"/>
                                <property name="initialSize" value="#{25L * 1024 * 1024}"/>
                                <property name="maxSize" value="#{100L * 1024 * 1024}"/>
                                <property name="swapPath" value="db/swap"/>
                            </bean>
                        </list>
                    </property>

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `DFLT_METRICS_ENABLED` Default metrics enabled flag.
    `static PageReplacementMode` | `DFLT_PAGE_REPLACEMENT_MODE` Default page replacement mode.
    `static int` | `DFLT_RATE_TIME_INTERVAL_MILLIS` Default length of interval over which `DataRegionMetrics.getAllocationRate()` metric is calculated.
    `static int` | `DFLT_SUB_INTERVALS` Default amount of sub intervals to calculate `DataRegionMetrics.getAllocationRate()` metric.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DataRegionConfiguration()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `getCheckpointPageBufferSize()` Gets amount of memory allocated for a checkpoint temporary buffer.
    `int` | `getEmptyPagesPoolSize()` Specifies the minimal number of empty pages to be present in reuse lists for this data region.
    `double` | `getEvictionThreshold()` Gets a threshold for memory pages eviction initiation.
    `long` | `getInitialSize()` Gets initial memory region size defined by this data region.
    `long` | `getMaxSize()` Maximum memory region size defined by this data region.
    `@Nullable MemoryAllocator` | `getMemoryAllocator()`
    `long` | `getMetricsRateTimeInterval()` Deprecated. Use `MetricsMxBean.configureHitRateMetric(String, long)` instead.
    `int` | `getMetricsSubIntervalCount()` Deprecated. Use `MetricsMxBean.configureHitRateMetric(String, long)` instead.
    `String` | `getName()` Gets data region name.
    `DataPageEvictionMode` | `getPageEvictionMode()` Gets memory pages eviction mode.
    `PageReplacementMode` | `getPageReplacementMode()` Gets memory pages replacement mode.
    `String` | `getSwapPath()` A path to the memory-mapped files the memory region defined by this data region will be mapped to.
    `@Nullable WarmUpConfiguration` | `getWarmUpConfiguration()` Gets warm-up configuration.
    `boolean` | `isCdcEnabled()` Gets flag indicating whether CDC is enabled.
    `boolean` | `isLazyMemoryAllocation()`
    `boolean` | `isMetricsEnabled()` Gets whether memory metrics are enabled by default on node startup.
    `boolean` | `isPersistenceEnabled()` Gets whether persistence is enabled for this data region.
    `DataRegionConfiguration` | `setCdcEnabled(boolean cdcEnabled)` Sets flag indicating whether CDC enabled.
    `DataRegionConfiguration` | `setCheckpointPageBufferSize(long checkpointPageBufSize)` Sets amount of memory allocated for the checkpoint temporary buffer.
    `DataRegionConfiguration` | `setEmptyPagesPoolSize(int emptyPagesPoolSize)` Specifies the minimal number of empty pages to be present in reuse lists for this data region.
    `DataRegionConfiguration` | `setEvictionThreshold(double evictionThreshold)` Sets memory pages eviction threshold.
    `DataRegionConfiguration` | `setInitialSize(long initSize)` Sets initial memory region size defined by this data region.
    `DataRegionConfiguration` | `setLazyMemoryAllocation(boolean lazyMemoryAllocation)` Sets `lazyMemoryAllocation` flag value.
    `DataRegionConfiguration` | `setMaxSize(long maxSize)` Sets maximum memory region size defined by this data region.
    `DataRegionConfiguration` | `setMemoryAllocator(MemoryAllocator allocator)` Sets memory allocator.
    `DataRegionConfiguration` | `setMetricsEnabled(boolean metricsEnabled)` Sets memory metrics enabled flag.
    `DataRegionConfiguration` | `setMetricsRateTimeInterval(long metricsRateTimeInterval)` Deprecated. Use `MetricsMxBean.configureHitRateMetric(String, long)` instead.
    `DataRegionConfiguration` | `setMetricsSubIntervalCount(int metricsSubIntervalCnt)` Deprecated. Use `MetricsMxBean.configureHitRateMetric(String, long)` instead.
    `DataRegionConfiguration` | `setName(String name)` Sets data region name.
    `DataRegionConfiguration` | `setPageEvictionMode(DataPageEvictionMode evictionMode)` Sets memory pages eviction mode.
    `DataRegionConfiguration` | `setPageReplacementMode(PageReplacementMode replacementMode)` Sets memory pages replacement mode.
    `DataRegionConfiguration` | `setPersistenceEnabled(boolean persistenceEnabled)` Sets persistence enabled flag.
    `DataRegionConfiguration` | `setSwapPath(String swapPath)` Sets a path to the memory-mapped files.
    `DataRegionConfiguration` | `setWarmUpConfiguration(@Nullable WarmUpConfiguration warmUpCfg)` Sets warm-up configuration.
    `String` | `toString()`

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

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

- - ### Field Detail

    - #### DFLT_METRICS_ENABLED

          public static final boolean DFLT_METRICS_ENABLED

      Default metrics enabled flag.
      See Also:
        Constant Field Values

    - #### DFLT_SUB_INTERVALS

          public static final int DFLT_SUB_INTERVALS

      Default amount of sub intervals to calculate `DataRegionMetrics.getAllocationRate()` metric.
      See Also:
        Constant Field Values

    - #### DFLT_RATE_TIME_INTERVAL_MILLIS

          public static final int DFLT_RATE_TIME_INTERVAL_MILLIS

      Default length of interval over which `DataRegionMetrics.getAllocationRate()` metric is calculated.
      See Also:
        Constant Field Values

    - #### DFLT_PAGE_REPLACEMENT_MODE

          public static final PageReplacementMode DFLT_PAGE_REPLACEMENT_MODE

      Default page replacement mode.

  - ### Constructor Detail

    - #### DataRegionConfiguration

          public DataRegionConfiguration()

  - ### Method Detail

    - #### getName

          public String getName()

      Gets data region name.
      Returns:
        Data region name.

    - #### setName

          public DataRegionConfiguration setName(String name)

      Sets data region name. The name must be non empty and must not be equal to the reserved 'sysMemPlc' one. If not specified, `DataStorageConfiguration.DFLT_DATA_REG_DEFAULT_NAME` value is used.
      Parameters:
        `name` - Data region name.
      Returns:
        `this` for chaining.

    - #### getMaxSize

          public long getMaxSize()

      Maximum memory region size defined by this data region. If the whole data can not fit into the memory region an out of memory exception will be thrown.
      Returns:
        Size in bytes.

    - #### setMaxSize

          public DataRegionConfiguration setMaxSize(long maxSize)

      Sets maximum memory region size defined by this data region. The total size should not be less than 10 MB due to the internal data structures overhead.
      Parameters:
        `maxSize` - Maximum data region size in bytes.
      Returns:
        `this` for chaining.

    - #### getInitialSize

          public long getInitialSize()

      Gets initial memory region size defined by this data region. When the used memory size exceeds this value, new chunks of memory will be allocated.
      Returns:
        Data region start size.

    - #### setInitialSize

          public DataRegionConfiguration setInitialSize(long initSize)

      Sets initial memory region size defined by this data region. When the used memory size exceeds this value, new chunks of memory will be allocated.
      Parameters:
        `initSize` - Data region initial size.
      Returns:
        `this` for chaining.

    - #### getSwapPath

          public String getSwapPath()

      A path to the memory-mapped files the memory region defined by this data region will be mapped to. Having the path set, allows relying on swapping capabilities of an underlying operating system for the memory region.
      Returns:
        A path to the memory-mapped files or `null` if this feature is not used for the memory region defined by this data region.

    - #### setSwapPath

          public DataRegionConfiguration setSwapPath(String swapPath)

      Sets a path to the memory-mapped files.
      Parameters:
        `swapPath` - A Path to the memory mapped file.
      Returns:
        `this` for chaining.

    - #### getMemoryAllocator

          @Nullable
          public @Nullable MemoryAllocator getMemoryAllocator()

      Returns:
        Memory allocator instance.

    - #### setMemoryAllocator

          public DataRegionConfiguration setMemoryAllocator(MemoryAllocator allocator)

      Sets memory allocator. If not specified, default, based on `Unsafe` allocator will be used.
      Parameters:
        `allocator` - Memory allocator instance.
      Returns:
        `this` for chaining.

    - #### getPageEvictionMode

          public DataPageEvictionMode getPageEvictionMode()

      Gets memory pages eviction mode. If `DataPageEvictionMode.DISABLED` is used (default) then an out of memory exception will be thrown if the memory region usage, defined by this data region, goes beyond its capacity which is `getMaxSize()`. Note: Page eviction is used only when persistence is disabled for data region. For persistent data regions see page replacement mode (`getPageReplacementMode()`).
      Returns:
        Memory pages eviction algorithm. `DataPageEvictionMode.DISABLED` used by default.

    - #### setPageEvictionMode

          public DataRegionConfiguration setPageEvictionMode(DataPageEvictionMode evictionMode)

      Sets memory pages eviction mode.
      Parameters:
        `evictionMode` - Eviction mode.
      Returns:
        `this` for chaining.

    - #### getPageReplacementMode

          public PageReplacementMode getPageReplacementMode()

      Gets memory pages replacement mode. If persistence is enabled and Ignite store on disk more data then available data region memory (`getMaxSize()`) page replacement can be started to rotate memory pages with the disk. This parameter defines the algorithm to find pages to replace. Note: For not persistent data regions see page eviction mode (`getPageEvictionMode()`).
      Returns:
        Memory pages replacement algorithm. `PageReplacementMode.CLOCK` used by default.

    - #### setPageReplacementMode

          public DataRegionConfiguration setPageReplacementMode(PageReplacementMode replacementMode)

      Sets memory pages replacement mode.
      Parameters:
        `replacementMode` - Page replacement mode.
      Returns:
        `this` for chaining.

    - #### getEvictionThreshold

          public double getEvictionThreshold()

      Gets a threshold for memory pages eviction initiation. For instance, if the threshold is 0.9 it means that the page memory will start the eviction only after 90% of the data region is occupied.
      Returns:
        Memory pages eviction threshold.

    - #### setEvictionThreshold

          public DataRegionConfiguration setEvictionThreshold(double evictionThreshold)

      Sets memory pages eviction threshold.
      Parameters:
        `evictionThreshold` - Eviction threshold.
      Returns:
        `this` for chaining.

    - #### getEmptyPagesPoolSize

          public int getEmptyPagesPoolSize()

      Specifies the minimal number of empty pages to be present in reuse lists for this data region. This parameter ensures that Ignite will be able to successfully evict old data entries when the size of (key, value) pair is slightly larger than page size / 2. Increase this parameter if cache can contain very big entries (total size of pages in this pool should be enough to contain largest cache entry). Increase this parameter if `IgniteOutOfMemoryException` occurred with enabled page eviction.
      Returns:
        Minimum number of empty pages in reuse list.

    - #### setEmptyPagesPoolSize

          public DataRegionConfiguration setEmptyPagesPoolSize(int emptyPagesPoolSize)

      Specifies the minimal number of empty pages to be present in reuse lists for this data region. This parameter ensures that Ignite will be able to successfully evict old data entries when the size of (key, value) pair is slightly larger than page size / 2. Increase this parameter if cache can contain very big entries (total size of pages in this pool should be enough to contain largest cache entry). Increase this parameter if `IgniteOutOfMemoryException` occurred with enabled page eviction.
      Parameters:
        `emptyPagesPoolSize` - Empty pages pool size.
      Returns:
        `this` for chaining.

    - #### isMetricsEnabled

          public boolean isMetricsEnabled()

      Gets whether memory metrics are enabled by default on node startup. Memory metrics can be enabled and disabled at runtime via memory metrics "name=io.dataregion.{data_region_name}" mx bean.
      Returns:
        Metrics enabled flag.

    - #### setMetricsEnabled

          public DataRegionConfiguration setMetricsEnabled(boolean metricsEnabled)

      Sets memory metrics enabled flag. If this flag is `true`, metrics will be enabled on node startup. Memory metrics can be enabled and disabled at runtime via memory metrics "name=io.dataregion.{data_region_name}" mx bean.
      Parameters:
        `metricsEnabled` - Metrics enabled flag.
      Returns:
        `this` for chaining.

    - #### isPersistenceEnabled

          public boolean isPersistenceEnabled()

      Gets whether persistence is enabled for this data region. All caches residing in this region will be persistent.
      Returns:
        Persistence enabled flag.

    - #### setPersistenceEnabled

          public DataRegionConfiguration setPersistenceEnabled(boolean persistenceEnabled)

      Sets persistence enabled flag.
      Parameters:
        `persistenceEnabled` - Persistence enabled flag.
      Returns:
        `this` for chaining.

    - #### getMetricsRateTimeInterval

          @Deprecated
          public long getMetricsRateTimeInterval()

      Deprecated. Use `MetricsMxBean.configureHitRateMetric(String, long)` instead.
      Gets time interval for `DataRegionMetrics.getAllocationRate()` and `DataRegionMetrics.getEvictionRate()` monitoring purposes.

      For instance, after setting the interval to 60_000 milliseconds, subsequent calls to `DataRegionMetrics.getAllocationRate()` will return average allocation rate (pages per second) for the last minute.

      Returns:
        Time interval over which allocation rate is calculated.

    - #### setMetricsRateTimeInterval

          @Deprecated
          public DataRegionConfiguration setMetricsRateTimeInterval(long metricsRateTimeInterval)

      Deprecated. Use `MetricsMxBean.configureHitRateMetric(String, long)` instead.
      Sets time interval for `DataRegionMetrics.getAllocationRate()` and `DataRegionMetrics.getEvictionRate()` monitoring purposes.

      For instance, after setting the interval to 60 seconds, subsequent calls to `DataRegionMetrics.getAllocationRate()` will return average allocation rate (pages per second) for the last minute.

      Parameters:
        `metricsRateTimeInterval` - Time interval used for allocation and eviction rates calculations.
      Returns:
        `this` for chaining.

    - #### getMetricsSubIntervalCount

          @Deprecated
          public int getMetricsSubIntervalCount()

      Deprecated. Use `MetricsMxBean.configureHitRateMetric(String, long)` instead.
      Gets a number of sub-intervals the whole `setMetricsRateTimeInterval(long)` will be split into to calculate `DataRegionMetrics.getAllocationRate()` and `DataRegionMetrics.getEvictionRate()` rates (5 by default).

      Setting it to a bigger value will result in more precise calculation and smaller drops of `DataRegionMetrics.getAllocationRate()` metric when next sub-interval has to be recycled but introduces bigger calculation overhead.

      Returns:
        number of sub intervals.

    - #### setMetricsSubIntervalCount

          @Deprecated
          public DataRegionConfiguration setMetricsSubIntervalCount(int metricsSubIntervalCnt)

      Deprecated. Use `MetricsMxBean.configureHitRateMetric(String, long)` instead.
      Sets a number of sub-intervals the whole `setMetricsRateTimeInterval(long)` will be split into to calculate `DataRegionMetrics.getAllocationRate()` and `DataRegionMetrics.getEvictionRate()` rates (5 by default).

      Setting it to a bigger value will result in more precise calculation and smaller drops of `DataRegionMetrics.getAllocationRate()` metric when next sub-interval has to be recycled but introduces bigger calculation overhead.

      Parameters:
        `metricsSubIntervalCnt` - A number of sub-intervals.
      Returns:
        `this` for chaining.

    - #### getCheckpointPageBufferSize

          public long getCheckpointPageBufferSize()

      Gets amount of memory allocated for a checkpoint temporary buffer.
      Returns:
        Checkpoint page buffer size in bytes or `0` for Ignite to choose the buffer size automatically.

    - #### setCheckpointPageBufferSize

          public DataRegionConfiguration setCheckpointPageBufferSize(long checkpointPageBufSize)

      Sets amount of memory allocated for the checkpoint temporary buffer. The buffer is used to create temporary copies of pages that are being written to disk and being update in parallel while the checkpoint is in progress.
      Parameters:
        `checkpointPageBufSize` - Checkpoint page buffer size in bytes or `0` for Ignite to choose the buffer size automatically.
      Returns:
        `this` for chaining.

    - #### isLazyMemoryAllocation

          public boolean isLazyMemoryAllocation()

      Returns:
        `True` if memory for `DataRegion` will be allocated only on the creation of the first cache belonged to this `DataRegion`.

    - #### setLazyMemoryAllocation

          public DataRegionConfiguration setLazyMemoryAllocation(boolean lazyMemoryAllocation)

      Sets `lazyMemoryAllocation` flag value. If `true`, memory for `DataRegion` will be allocated only on the creation of the first cache belonged to this `DataRegion`.
      Parameters:
        `lazyMemoryAllocation` - Flag value.
      Returns:
        `this` for chaining.

    - #### setWarmUpConfiguration

          public DataRegionConfiguration setWarmUpConfiguration(@Nullable
                                                                @Nullable WarmUpConfiguration warmUpCfg)

      Sets warm-up configuration.
      Parameters:
        `warmUpCfg` - Warm-up configuration. Can be `null` (default `DataStorageConfiguration.getDefaultWarmUpConfiguration()` will be used).
      Returns:
        `this` for chaining.

    - #### getWarmUpConfiguration

          @Nullable
          public @Nullable WarmUpConfiguration getWarmUpConfiguration()

      Gets warm-up configuration.
      Returns:
        Warm-up configuration.

    - #### setCdcEnabled

          public DataRegionConfiguration setCdcEnabled(boolean cdcEnabled)

      Sets flag indicating whether CDC enabled.
      Parameters:
        `cdcEnabled` - CDC enabled flag.
      Returns:
        `this` for chaining.

    - #### isCdcEnabled

          public boolean isCdcEnabled()

      Gets flag indicating whether CDC is enabled. Default value is `false`.
      Returns:
        CDC enabled flag.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

${current.year} Copyright © Apache Software Foundation
| Follow @ApacheIgnite
Ignite Database and Caching Platform | : ver. 2.16.0
Release Date | : December 15 2023