AutoBalancer (Apache Geode 1.8.0)
Date: 2018-11-29

org.apache.geode.cache.util

## Class AutoBalancer

- java.lang.Object
- - org.apache.geode.cache.util.AutoBalancer

- All Implemented Interfaces:
    Declarable

      @Experimental(value="The autobalancer may be removed or the API may change in future releases")
      public class AutoBalancer
      extends java.lang.Object
      implements Declarable

  Re-balancing operation relocates data from heavily loaded members to lightly loaded members. In most cases, the decision to re-balance is based on the size of the member and a few other statistics. `AutoBalancer` monitors these statistics and if necessary, triggers a re-balancing request. Auto-Balancing is expected to prevent failures and data loss.

  This implementation is based on `ConfigInitialization` implementation. By default auto-balancing is disabled. A user needs to configure `AutoBalancer` during cache initialization `GemFireCache.getInitializer()`

  In a cluster only one member owns auto-balancing responsibility. This is achieved by grabbing a distributed lock. In case of a failure a new member will grab the lock and manage auto balancing.

  `AutoBalancer` can be controlled using the following configurations

  1. `SCHEDULE`
  2. TBD THRESHOLDS

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.Object` | `AUTO_BALANCER_LOCK`
    `static java.lang.String` | `AUTO_BALANCER_LOCK_SERVICE_NAME` Name of the DistributedLockService that `AutoBalancer` will use to guard against concurrent maintenance activity
    `static int` | `DEFAULT_MINIMUM_SIZE` Default value of `MINIMUM_SIZE`.
    `static int` | `DEFAULT_SIZE_THRESHOLD_PERCENT` Default value of `SIZE_THRESHOLD_PERCENT`.
    `static java.lang.String` | `MINIMUM_SIZE` In the initial data load phases, `SIZE_THRESHOLD_PERCENT` based rebalance invocation may be unnecessary.
    `static java.lang.String` | `SCHEDULE` Use this configuration to manage out-of-balance audit frequency.
    `static java.lang.String` | `SIZE_THRESHOLD_PERCENT` Use this configuration to manage re-balance invocation.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AutoBalancer()`
    `AutoBalancer(org.apache.geode.cache.util.AutoBalancer.AuditScheduler scheduler, org.apache.geode.cache.util.AutoBalancer.OOBAuditor auditor, org.apache.geode.cache.util.AutoBalancer.TimeProvider clock, org.apache.geode.cache.util.AutoBalancer.CacheOperationFacade cacheFacade)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()`
    `org.apache.geode.cache.util.AutoBalancer.CacheOperationFacade` | `getCacheOperationFacade()`
    `void` | `init(java.util.Properties props)` Deprecated. as of Geode 1.5 use initialize instead.
    `void` | `initialize(Cache cache, java.util.Properties props)` Initializes a user-defined object, owned by the given cache, using the given properties.

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

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

- - ### Field Detail

    - #### SCHEDULE

          public static final java.lang.String SCHEDULE

      Use this configuration to manage out-of-balance audit frequency. If the auditor finds the system to be out-of-balance, it will trigger re-balancing. Any valid cron string is accepted. The sub-expressions represent the following:
      1. Seconds
      2. Minutes
      3. Hours
      4. Day-of-Month
      5. Month
      6. Day-of-Week
      7. Year (optional field)

         For. e.g. `0 0 * * * ?` for auditing the system every hour

      See Also:
        Constant Field Values

    - #### SIZE_THRESHOLD_PERCENT

          public static final java.lang.String SIZE_THRESHOLD_PERCENT

      Use this configuration to manage re-balance invocation. Rebalance operation will be triggered if the total number of bytes rebalance operation may move is more than this threshold, in percentage of the total data size.

      Default value `DEFAULT_SIZE_THRESHOLD_PERCENT`

      See Also:
        Constant Field Values

    - #### DEFAULT_SIZE_THRESHOLD_PERCENT

          public static final int DEFAULT_SIZE_THRESHOLD_PERCENT

      Default value of `SIZE_THRESHOLD_PERCENT`. If 10% of data is misplaced, its a good time to redistribute buckets
      See Also:
        Constant Field Values

    - #### MINIMUM_SIZE

          public static final java.lang.String MINIMUM_SIZE

      In the initial data load phases, `SIZE_THRESHOLD_PERCENT` based rebalance invocation may be unnecessary. Rebalance should not be triggered if the total data size managed by cluster is too small. Rebalance operation will be triggered if the total number of bytes rebalance operation may move is more than this number of bytes.

      Default value `DEFAULT_MINIMUM_SIZE`

      See Also:
        Constant Field Values

    - #### DEFAULT_MINIMUM_SIZE

          public static final int DEFAULT_MINIMUM_SIZE

      Default value of `MINIMUM_SIZE`. In the initial data load phases, `SIZE_THRESHOLD_PERCENT` based rebalance invocation may be unnecessary. Do not rebalance if the data to be moved is less than 100MB
      See Also:
        Constant Field Values

    - #### AUTO_BALANCER_LOCK_SERVICE_NAME

          public static final java.lang.String AUTO_BALANCER_LOCK_SERVICE_NAME

      Name of the DistributedLockService that `AutoBalancer` will use to guard against concurrent maintenance activity
      See Also:
        Constant Field Values

    - #### AUTO_BALANCER_LOCK

          public static final java.lang.Object AUTO_BALANCER_LOCK

  - ### Constructor Detail

    - #### AutoBalancer

          public AutoBalancer()

    - #### AutoBalancer

          public AutoBalancer(org.apache.geode.cache.util.AutoBalancer.AuditScheduler scheduler,
                              org.apache.geode.cache.util.AutoBalancer.OOBAuditor auditor,
                              org.apache.geode.cache.util.AutoBalancer.TimeProvider clock,
                              org.apache.geode.cache.util.AutoBalancer.CacheOperationFacade cacheFacade)

  - ### Method Detail

    - #### initialize

          public void initialize(Cache cache,
                                 java.util.Properties props)

      Description copied from interface: `Declarable`
      Initializes a user-defined object, owned by the given cache, using the given properties. Note that any uncaught exception thrown by this method will cause the `Cache` initialization to fail. Note that if this method is implemented then the deprecated init method should not be implemented. The product will call both methods assuming that only one will have a non-default implementation.
      Specified by:
        `initialize` in interface `Declarable`
      Parameters:
        `cache` - the cache that owns this declarable
        `props` - Contains the parameters declared in the declarative xml file.

    - #### init

          public void init(java.util.Properties props)

      Deprecated. as of Geode 1.5 use initialize instead.
      Description copied from interface: `Declarable`
      Initializes a user-defined object using the given properties. Note that any uncaught exception thrown by this method will cause the `Cache` initialization to fail.
      Specified by:
        `init` in interface `Declarable`
      Parameters:
        `props` - Contains the parameters declared in the declarative xml file.

    - #### getCacheOperationFacade

          public org.apache.geode.cache.util.AutoBalancer.CacheOperationFacade getCacheOperationFacade()

    - #### destroy

          public void destroy()