PartitionAttributesFactory (Apache Geode 1.13.2)
Date: 2021-03-08

org.apache.geode.cache

## Class PartitionAttributesFactory<K,V>

- java.lang.Object
- - org.apache.geode.cache.PartitionAttributesFactory<K,V>

-     public class PartitionAttributesFactory<K,V>
      extends Object

  A factory that creates instances of `PartitionAttributes` which are used to create a partitioned `Region`. The setter methods follow the self-return idiom so that they can be "chained" together with the `create()` method to create `PartitionAttributes`. For example:

       PartitionAttributes pa =
           new PartitionAttributesFactory().setRedundantCopies(1).setLocalMaxMemory(1240).create();

       final Region myRegion = new RegionFactory().setPartitionAttributes(pa)
           .setKeyConstraint(String.class).setValueConstraint(ArrayList.class).create("myRegion");

  `PartitionAttributes` can also be defined in a declarative fashion using a cache.xml file. Here is an example of how to configure a Partitioned Region named "pRoot" whose `Scope` is Distributed Ack, which maintains a `redundant copy` of any given `Region.Entry`, configures a `CacheLoader` implementation, and sets `global properties` as well as `local max memory to use`.

          <root-region name="pRoot">
            <region-attributes scope="distributed-ack" >
              <partition-attributes redundant-copies="1", local-max-memory="1240"/>
            </region-attributes>
          </root-region>

  Since:
    GemFire 5.0
  See Also:
    `PartitionAttributes`, `AttributesFactory.setPartitionAttributes(PartitionAttributes)`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `GLOBAL_MAX_BUCKETS_DEFAULT` The default total number of buckets (113).
    `static String` | `GLOBAL_MAX_BUCKETS_PROPERTY` Deprecated. - please use `setTotalNumBuckets(int)` instead. This setting must be the same in all processes using the Region.
    `static long` | `GLOBAL_MAX_MEMORY_DEFAULT` Default maximum total size of the region across all processes, in megabytes.
    `static String` | `GLOBAL_MAX_MEMORY_PROPERTY` Deprecated. - use `setTotalMaxMemory(long)` instead. The `global property` name that defines the total maximum size for the partitioned Region. This setting must be the same in all processes using the Region.
    `static int` | `LOCAL_MAX_MEMORY_DEFAULT` Deprecated. Use `PartitionAttributesImpl.getLocalMaxMemoryDefault()` instead.
    `static String` | `LOCAL_MAX_MEMORY_PROPERTY` Deprecated. - please use the `setLocalMaxMemory(int)` method instead. The `local property` name that sets the maximum heap storage a VM contributes to a partitioned Region. When set to zero, the resulting Region reference allows access to the partitioned Region without any consuming any heap storage.
    `static long` | `RECOVERY_DELAY_DEFAULT`
    `static long` | `STARTUP_RECOVERY_DELAY_DEFAULT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PartitionAttributesFactory()` Creates a new instance of PartitionAttributesFactory ready to create a `PartitionAttributes` with default settings.
    `PartitionAttributesFactory(PartitionAttributes pa)` Creates a new instance of PartitionAttributesFactory ready to create a `PartitionAttributes` with the same settings as those in the specified `PartitionAttributes`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `PartitionAttributesFactory<K,V>` | `addFixedPartitionAttributes(FixedPartitionAttributes fpa)` FixedPartitionAttributes defined for this partitioned region is added to PR attributes.
    `PartitionAttributesFactory<K,V>` | `addPartitionListener(PartitionListener listener)` adds a PartitionListener for the partitioned region.
    `PartitionAttributes<K,V>` | `create()` Creates a `PartitionAttributes` with the current settings.
    `PartitionAttributesFactory<K,V>` | `setColocatedWith(String colocatedRegionFullPath)` Sets the name of the PartitionRegion with which this newly created partitioned region is colocated
    `PartitionAttributesFactory<K,V>` | `setGlobalProperties(Properties globalProps)` Deprecated. use `setTotalMaxMemory(long)` and `setTotalNumBuckets(int)` in GemFire 5.1 and later releases
    `PartitionAttributesFactory<K,V>` | `setLocalMaxMemory(int mb)` Sets the maximum amount of memory, in megabytes, to be used by the region in this process.
    `PartitionAttributesFactory<K,V>` | `setLocalProperties(Properties localProps)` Deprecated. use `setLocalMaxMemory(int)` in GemFire 5.1 and later releases
    `PartitionAttributesFactory<K,V>` | `setPartitionResolver(PartitionResolver<K,V> resolver)` Sets the `PartitionResolver` for the PartitionRegion.
    `PartitionAttributesFactory<K,V>` | `setRecoveryDelay(long recoveryDelay)` Sets the delay in milliseconds that existing members will wait before satisfying redundancy after another member crashes.
    `PartitionAttributesFactory<K,V>` | `setRedundantCopies(int redundantCopies)` Sets the number of extra copies of buckets desired.
    `PartitionAttributesFactory<K,V>` | `setStartupRecoveryDelay(long startupRecoveryDelay)` Sets the delay in milliseconds that new members will wait before satisfying redundancy.
    `PartitionAttributesFactory<K,V>` | `setTotalMaxMemory(long mb)` Deprecated. since Geode 1.3.0
    `PartitionAttributesFactory<K,V>` | `setTotalNumBuckets(int numBuckets)` Sets the total number of hash buckets to be used by the region in all processes.

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

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

- - ### Field Detail

    - #### LOCAL_MAX_MEMORY_PROPERTY

          public static final String LOCAL_MAX_MEMORY_PROPERTY

      Deprecated. - please use the `setLocalMaxMemory(int)` method instead.

      The `local property` name that sets the maximum heap storage a VM contributes to a partitioned Region. When set to zero, the resulting Region reference allows access to the partitioned Region without any consuming any heap storage.

      See Also:
        Constant Field Values

    - #### LOCAL_MAX_MEMORY_DEFAULT

          @Deprecated
          public static final int LOCAL_MAX_MEMORY_DEFAULT

      Deprecated. Use `PartitionAttributesImpl.getLocalMaxMemoryDefault()` instead.
      The default maximum amount of memory to be used by this region in this process, in megabytes.

    - #### GLOBAL_MAX_MEMORY_PROPERTY

          public static final String GLOBAL_MAX_MEMORY_PROPERTY

      Deprecated. - use `setTotalMaxMemory(long)` instead.

      The `global property` name that defines the total maximum size for the partitioned Region.

      This setting must be the same in all processes using the Region.

      See Also:
        Constant Field Values

    - #### GLOBAL_MAX_MEMORY_DEFAULT

          public static final long GLOBAL_MAX_MEMORY_DEFAULT

      Default maximum total size of the region across all processes, in megabytes.
      See Also:
        Constant Field Values

    - #### GLOBAL_MAX_BUCKETS_PROPERTY

          public static final String GLOBAL_MAX_BUCKETS_PROPERTY

      Deprecated. - please use `setTotalNumBuckets(int)` instead.

      This setting must be the same in all processes using the Region.

      See Also:
        Constant Field Values

    - #### GLOBAL_MAX_BUCKETS_DEFAULT

          public static final int GLOBAL_MAX_BUCKETS_DEFAULT

      The default total number of buckets (113).
      See Also:
        Constant Field Values

    - #### RECOVERY_DELAY_DEFAULT

          public static final long RECOVERY_DELAY_DEFAULT

      See Also:
        Constant Field Values

    - #### STARTUP_RECOVERY_DELAY_DEFAULT

          public static final long STARTUP_RECOVERY_DELAY_DEFAULT

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### PartitionAttributesFactory

          public PartitionAttributesFactory()

      Creates a new instance of PartitionAttributesFactory ready to create a `PartitionAttributes` with default settings.

    - #### PartitionAttributesFactory

          public PartitionAttributesFactory(PartitionAttributes pa)

      Creates a new instance of PartitionAttributesFactory ready to create a `PartitionAttributes` with the same settings as those in the specified `PartitionAttributes`
      Parameters:
        `pa` - the `PartitionAttributes` used to initialize this PartitionAttributesFactory

  - ### Method Detail

    - #### setRedundantCopies

          public PartitionAttributesFactory<K,V> setRedundantCopies(int redundantCopies)

      Sets the number of extra copies of buckets desired. Extra copies allow for both high availability in the face of VM departure (intended or unintended) and and load balancing read operations.

      This setting must be the same in all processes using the Region. Default number of redundant copies is 0.

      Parameters:
        `redundantCopies` - the number of redundant bucket copies, limited to values 0, 1, 2 and 3.

    - #### setLocalMaxMemory

          public PartitionAttributesFactory<K,V> setLocalMaxMemory(int mb)

      Sets the maximum amount of memory, in megabytes, to be used by the region in this process. If not set, a default of 90% of available heap is used.

    - #### setTotalMaxMemory

          @Deprecated
          public PartitionAttributesFactory<K,V> setTotalMaxMemory(long mb)

      Deprecated. since Geode 1.3.0
      Sets the maximum amount of memory, in megabytes, to be used by the region in all processes.

      This setting must be the same in all processes using the Region. The default value is Integer.MAX_VALUE.

    - #### setTotalNumBuckets

          public PartitionAttributesFactory<K,V> setTotalNumBuckets(int numBuckets)

      Sets the total number of hash buckets to be used by the region in all processes.

      This setting must be the same in all processes using the Region.

      A bucket is the smallest unit of data management in a partitioned region. `Entries` are stored in buckets and buckets may move from one VM to another. Buckets may also have copies, depending on `redundancy` to provide high availability in the face of VM failure.

      The number of buckets should be prime and as a rough guide at the least four times the number of partition VMs. However, there is significant overhead to managing a bucket, particularly for higher values of `redundancy`.

      The default number of buckets for a PartitionedRegion is 113.

    - #### setPartitionResolver

          public PartitionAttributesFactory<K,V> setPartitionResolver(PartitionResolver<K,V> resolver)

      Sets the `PartitionResolver` for the PartitionRegion.

    - #### setColocatedWith

          public PartitionAttributesFactory<K,V> setColocatedWith(String colocatedRegionFullPath)

      Sets the name of the PartitionRegion with which this newly created partitioned region is colocated

    - #### setRecoveryDelay

          public PartitionAttributesFactory<K,V> setRecoveryDelay(long recoveryDelay)

      Sets the delay in milliseconds that existing members will wait before satisfying redundancy after another member crashes. Default value is set to -1 which indicates that redundancy will not be recovered after a failure.
      Since:
        GemFire 6.0

    - #### setStartupRecoveryDelay

          public PartitionAttributesFactory<K,V> setStartupRecoveryDelay(long startupRecoveryDelay)

      Sets the delay in milliseconds that new members will wait before satisfying redundancy. -1 indicates that adding new members will not trigger redundancy recovery. The default (set to 0) is to recover redundancy immediately when a new member is added.
      Since:
        GemFire 6.0

    - #### addPartitionListener

          public PartitionAttributesFactory<K,V> addPartitionListener(PartitionListener listener)

      adds a PartitionListener for the partitioned region.
      Since:
        GemFire 6.5

    - #### setLocalProperties

          @Deprecated
          public PartitionAttributesFactory<K,V> setLocalProperties(Properties localProps)

      Deprecated. use `setLocalMaxMemory(int)` in GemFire 5.1 and later releases
      Sets the `Properties` for the local instance the partitioned Region. Local properties define how the local instance of the partitioned region and any storage it may provide, behaves. There are currently no non-deprecated local properties.
      Returns:
        PartitionAttributeFactory.

    - #### setGlobalProperties

          @Deprecated
          public PartitionAttributesFactory<K,V> setGlobalProperties(Properties globalProps)

      Deprecated. use `setTotalMaxMemory(long)` and `setTotalNumBuckets(int)` in GemFire 5.1 and later releases
      Sets the global `Properties` for the next `PartitionAttributes` created. Global properties define how the entire partitioned Region behaves.

      Note that global settings must be the same in all processes using the Region.

      Returns:
        PartitionAttributeFactory.
      See Also:
        `GLOBAL_MAX_MEMORY_PROPERTY`

    - #### addFixedPartitionAttributes

          public PartitionAttributesFactory<K,V> addFixedPartitionAttributes(FixedPartitionAttributes fpa)

      FixedPartitionAttributes defined for this partitioned region is added to PR attributes.
      Since:
        GemFire 6.6

    - #### create

          public PartitionAttributes<K,V> create()

      Creates a `PartitionAttributes` with the current settings.
      Returns:
        the newly created `PartitionAttributes`
      Throws:
        `IllegalStateException` - if the current settings violate the compatibility rules