EvictionAttributes (Apache Geode 1.15.4)

org.apache.geode.cache

## Class EvictionAttributes

- java.lang.Object
- - org.apache.geode.cache.EvictionAttributes

-     public abstract class EvictionAttributes
      extends Object

  Attributes that describe how a `Region`'s size is managed through an eviction controller. Eviction controllers are defined by an `EvictionAlgorithm` and a `EvictionAction`. Once a `Region` is created with an eviction controller, it can not be removed, however it can be changed through an `EvictionAttributesMutator`.

  Since:
    GemFire 5.0
  See Also:
    `AttributesFactory.setEvictionAttributes(EvictionAttributes)`, `AttributesMutator`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_ENTRIES_MAXIMUM` The default maximum for entry LRU.
    `static int` | `DEFAULT_MEMORY_MAXIMUM` The default maximum for memory LRU.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `EvictionAttributes()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `RegionAttributesType.EvictionAttributes` | `convertToConfigEvictionAttributes()`
    `static EvictionAttributes` | `createLIFOEntryAttributes(int maximumEntries, EvictionAction evictionAction)` Deprecated. For internal use only.
    `static EvictionAttributes` | `createLIFOMemoryAttributes(int maximumMegabytes, EvictionAction evictionAction)` Deprecated. For internal use only.
    `static EvictionAttributes` | `createLRUEntryAttributes()` Creates and returns entry LRU eviction attributes with default action and default maximum.
    `static EvictionAttributes` | `createLRUEntryAttributes(EvictionAction evictionAction)` Creates and returns entry LRU eviction attributes with default maximum and given `evictionAction`.
    `static EvictionAttributes` | `createLRUEntryAttributes(int maximumEntries)` Creates and returns entry LRU eviction attributes with default action and given `maximumEntries`.
    `static EvictionAttributes` | `createLRUEntryAttributes(int maximumEntries, EvictionAction evictionAction)` Creates and returns entry LRU eviction attributes with given `evictionAction` and given `maximumEntries`.
    `static EvictionAttributes` | `createLRUHeapAttributes()` Creates and returns heap LRU eviction attributes with default action and default sizer.
    `static EvictionAttributes` | `createLRUHeapAttributes(ObjectSizer sizer)` Creates and returns heap LRU eviction attributes with default action and the given `sizer`.
    `static EvictionAttributes` | `createLRUHeapAttributes(ObjectSizer sizer, EvictionAction evictionAction)` Creates and returns heap LRU eviction attributes with the given `evictionAction` and given `sizer`.
    `static EvictionAttributes` | `createLRUMemoryAttributes()` Creates and returns memory LRU eviction attributes with default action, default sizer, and default maximum.
    `static EvictionAttributes` | `createLRUMemoryAttributes(int maximumMegabytes)` Creates and returns memory LRU eviction attributes with default action, default sizer, and given `maximumMegabytes`.
    `static EvictionAttributes` | `createLRUMemoryAttributes(int maximumMegabytes, ObjectSizer sizer)` Creates and returns memory LRU eviction attributes with default action, given `sizer`, and given `maximumMegabytes`.
    `static EvictionAttributes` | `createLRUMemoryAttributes(int maximumMegabytes, ObjectSizer sizer, EvictionAction evictionAction)` Creates and returns memory LRU eviction attributes with the given `evictionAction`, given `sizer`, and given `maximumMegabytes`.
    `static EvictionAttributes` | `createLRUMemoryAttributes(ObjectSizer sizer)` Creates and returns memory LRU eviction attributes with default action, given `sizer`, and default maximum.
    `static EvictionAttributes` | `createLRUMemoryAttributes(ObjectSizer sizer, EvictionAction evictionAction)` Creates and returns memory LRU eviction attributes with given `evictionAction`, given `sizer`, and default maximum.
    `boolean` | `equals(Object obj)`
    `abstract EvictionAction` | `getAction()`
    `abstract EvictionAlgorithm` | `getAlgorithm()` The algorithm is used to identify entries that will be evicted.
    `abstract int` | `getMaximum()` The unit of this value is determined by the definition of the `EvictionAlgorithm` set by one of the creation methods e.g.
    `abstract ObjectSizer` | `getObjectSizer()` An `ObjectSizer` is used by the `EvictionAlgorithm.LRU_MEMORY` algorithm to measure the size of each Entry as it is entered into a Region.
    `int` | `hashCode()`
    `boolean` | `isNoEviction()`
    `String` | `toString()`

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

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

- - ### Field Detail

    - #### DEFAULT_ENTRIES_MAXIMUM

          public static final int DEFAULT_ENTRIES_MAXIMUM

      The default maximum for entry LRU. Currently `900` entries.
      See Also:
        Constant Field Values

    - #### DEFAULT_MEMORY_MAXIMUM

          public static final int DEFAULT_MEMORY_MAXIMUM

      The default maximum for memory LRU. Currently `10` megabytes.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### EvictionAttributes

          public EvictionAttributes()

  - ### Method Detail

    - #### createLRUEntryAttributes

          public static EvictionAttributes createLRUEntryAttributes()

      Creates and returns entry LRU eviction attributes with default action and default maximum.

      `EvictionAttributes` cause regions to evict the least recently used (LRU) entry once the region reaches a maximum capacity. The entry is either locally destroyed or its value overflows to disk when evicted.

      This is not supported when replication is enabled.

      For a region with `DataPolicy.PARTITION`, the EvictionAttribute `maximum`, indicates the number of entries allowed in the region, collectively for its primary buckets and redundant copies for this JVM. Once there are `maximum` entries in the region's primary buckets and redundant copies for this JVM, the least recently used entry will be evicted from the bucket in which the subsequent put takes place.

      If you are using a `cache.xml` file to create a Cache Region declaratively, you can include the following to configure a region for eviction

                   <region-attributes>
                      <eviction-attributes>
                         <lru-entry-count maximum="900" action="local-destroy"/>
                      </eviction-attributes>
                   </region-attributes>

      Returns:
        entry LRU eviction attributes with default action and default maximum

    - #### createLRUEntryAttributes

          public static EvictionAttributes createLRUEntryAttributes(int maximumEntries)

      Creates and returns entry LRU eviction attributes with default action and given `maximumEntries`.
      Parameters:
        `maximumEntries` - the number of entries to keep in the Region
      Returns:
        entry LRU eviction attributes with default action and `maximumEntries`
      See Also:
        `createLRUEntryAttributes()`

    - #### createLRUEntryAttributes

          public static EvictionAttributes createLRUEntryAttributes(EvictionAction evictionAction)

      Creates and returns entry LRU eviction attributes with default maximum and given `evictionAction`.
      Parameters:
        `evictionAction` - the action to perform when evicting an entry
      Returns:
        entry LRU eviction attributes with default maximum and given `evictionAction`
      Since:
        GemFire 8.1
      See Also:
        `createLRUEntryAttributes()`

    - #### createLRUEntryAttributes

          public static EvictionAttributes createLRUEntryAttributes(int maximumEntries,
                                                                    EvictionAction evictionAction)

      Creates and returns entry LRU eviction attributes with given `evictionAction` and given `maximumEntries`.
      Parameters:
        `maximumEntries` - the number of entries to keep in the Region
        `evictionAction` - the action to perform when evicting an entry
      Returns:
        entry LRU eviction attributes with given `evictionAction` and given `maximumEntries`
      See Also:
        `createLRUEntryAttributes()`

    - #### createLRUHeapAttributes

          public static EvictionAttributes createLRUHeapAttributes()

      Creates and returns heap LRU eviction attributes with default action and default sizer.

      Heap LRU EvictionAttributes evict the least recently used `Region.Entry` when heap usage exceeds the `ResourceManager` eviction heap threshold. If the eviction heap threshold is exceeded the least recently used `Region.Entry`s are evicted.

      With other LRU-based eviction controllers, only cache actions (such as `puts` and `gets`) cause the LRU entry to be evicted. However, with heap LRU, because the JVM's heap may be effected by more than just the GemFire cache operations, a daemon thread will perform the eviction if no operations are being done on the region.

      The eviction attribute's sizer is used to estimate how much the heap will be reduced by an eviction.

      When using Heap LRU, the JVM must be launched with the `-Xmx` and `-Xms` switches set to the same values. Many virtual machine implementations have additional JVM switches to control the behavior of the garbage collector. We suggest that you investigate tuning the garbage collector when using this type of eviction controller. A collector that frequently collects is needed to keep our heap usage up to date. In particular, on the Sun HotSpot JVM, before Java 14, the `-XX:+UseConcMarkSweepGC` flag needs to be set, and `-XX:CMSInitiatingOccupancyFraction=N` should be set with N being a percentage that is less than the `ResourceManager` eviction heap threshold.

      The JRockit JVM has similar flags, `-Xgc:gencon` and `-XXgcTrigger:N`, which are required if using this LRU algorithm. Please Note: the JRockit gcTrigger flag is based on heap free, not heap in use like the GemFire parameter. This means you need to set gcTrigger to 100-N. for example, if your eviction threshold is 30 percent, you will need to set gcTrigger to 70 percent.

      On the IBM JVM, the flag to get a similar collector is `-Xgcpolicy:gencon`, but there is no corollary to the gcTrigger/CMSInitiatingOccupancyFraction flags, so when using this feature with an IBM JVM, the heap usage statistics might lag the true memory usage of the JVM, and thresholds may need to be set sufficiently high that the JVM will initiate GC before the thresholds are crossed.

      If you are using a `cache.xml` file to create a Cache Region declaratively, you can include the following to create an LRU heap eviction controller:

                   <region-attributes>
                      <eviction-attributes>
                         <lru-heap-percentage action="local-destroy"
                      </eviction-attributes>
                   </region-attributes>

      Returns:
        heap LRU eviction attributes with default action and default sizer

    - #### createLRUHeapAttributes

          public static EvictionAttributes createLRUHeapAttributes(ObjectSizer sizer)

      Creates and returns heap LRU eviction attributes with default action and the given `sizer`.
      Parameters:
        `sizer` - the sizer implementation used to determine the size of each entry in this region
      Returns:
        heap LRU eviction attributes with default action and the given `sizer`
      See Also:
        `createLRUHeapAttributes()`

    - #### createLRUHeapAttributes

          public static EvictionAttributes createLRUHeapAttributes(ObjectSizer sizer,
                                                                   EvictionAction evictionAction)

      Creates and returns heap LRU eviction attributes with the given `evictionAction` and given `sizer`.
      Parameters:
        `sizer` - the sizer implementation used to determine the size of each entry in this region
        `evictionAction` - the way in which entries should be evicted
      Returns:
        heap LRU eviction attributes with the given `evictionAction` and given `sizer`
      See Also:
        `createLRUHeapAttributes()`

    - #### createLRUMemoryAttributes

          public static EvictionAttributes createLRUMemoryAttributes()

      Creates and returns memory LRU eviction attributes with default action, default sizer, and default maximum.

      Creates EvictionAttributes for an eviction controller that will remove the least recently used (LRU) entry from a region once the region reaches a certain byte capacity. Capacity is determined by monitoring the size of entries added and evicted. Capacity is specified in terms of megabytes. GemFire uses an efficient algorithm to determine the amount of space a region entry occupies in the JVM. However, this algorithm may not yield optimal results for all kinds of data. The user may provide their own algorithm for determining the size of objects by implementing an `ObjectSizer`.

      For a region with `DataPolicy.PARTITION`, the EvictionAttribute `maximum`, is always equal to `" local max memory "` specified for the `PartitionAttributes`. It signifies the amount of memory allowed in the region, collectively for its primary buckets and redundant copies for this JVM. It can be different for the same region in different JVMs.

      If you are using a `cache.xml` file to create a Cache Region declaratively, you can include the following to create an LRU memory eviction controller:

                    <region-attributes>
                      <eviction-attributes>
                         <lru-memory-size maximum="10" action="local-destroy">
                            <class-name>com.foo.MySizer</class-name>
                            <parameter name="name">
                               <string>Super Sizer</string>
                            </parameter>
                         </lru-memory-size>
                      </eviction-attributes>
                   </region-attributes>

      Returns:
        memory LRU eviction attributes with default action, default sizer, and default maximum

    - #### createLRUMemoryAttributes

          public static EvictionAttributes createLRUMemoryAttributes(int maximumMegabytes)

      Creates and returns memory LRU eviction attributes with default action, default sizer, and given `maximumMegabytes`.

      For a region with `DataPolicy.PARTITION`, even if maximumMegabytes are supplied, the EvictionAttribute `maximum`, is always set to `" local max memory "` specified for the `PartitionAttributes`.

      Parameters:
        `maximumMegabytes` - the maximum allowed bytes in the Region
      Returns:
        memory LRU eviction attributes with default action, default sizer, and given `maximumMegabytes`
      See Also:
        `createLRUMemoryAttributes()`

    - #### createLRUMemoryAttributes

          public static EvictionAttributes createLRUMemoryAttributes(int maximumMegabytes,
                                                                     ObjectSizer sizer)

      Creates and returns memory LRU eviction attributes with default action, given `sizer`, and given `maximumMegabytes`.

      For a region with `DataPolicy.PARTITION`, even if maximumMegabytes are supplied, the EvictionAttribute `maximum`, is always set to `" local max memory "` specified for the `PartitionAttributes`.

      Parameters:
        `maximumMegabytes` - the maximum allowed bytes in the Region
        `sizer` - calculates the size in bytes of the key and value for an entry.
      Returns:
        memory LRU eviction attributes with default action, given `sizer`, and given `maximumMegabytes`
      See Also:
        `createLRUMemoryAttributes()`

    - #### createLRUMemoryAttributes

          public static EvictionAttributes createLRUMemoryAttributes(int maximumMegabytes,
                                                                     ObjectSizer sizer,
                                                                     EvictionAction evictionAction)

      Creates and returns memory LRU eviction attributes with the given `evictionAction`, given `sizer`, and given `maximumMegabytes`.

      For a region with `DataPolicy.PARTITION`, even if maximumMegabytes are supplied, the EvictionAttribute `maximum`, is always set to `" local max memory "` specified for the `PartitionAttributes`.

      Parameters:
        `maximumMegabytes` - the maximum allowed bytes in the Region
        `sizer` - calculates the size in bytes of the key and value for an entry.
        `evictionAction` - the action to take when the maximum has been reached.
      Returns:
        memory LRU eviction attributes with the given `evictionAction`, given `sizer`, and given `maximumMegabytes`
      See Also:
        `createLRUMemoryAttributes()`

    - #### createLRUMemoryAttributes

          public static EvictionAttributes createLRUMemoryAttributes(ObjectSizer sizer)

      Creates and returns memory LRU eviction attributes with default action, given `sizer`, and default maximum.

      For a region with `DataPolicy.PARTITION`, even if maximumMegabytes are supplied, the EvictionAttribute `maximum`, is always set to `" local max memory "` specified for the `PartitionAttributes`.

      Parameters:
        `sizer` - calculates the size in bytes of the key and value for an entry.
      Returns:
        memory LRU eviction attributes with default action, given `sizer`, and default maximum
      Since:
        GemFire 6.0
      See Also:
        `createLRUMemoryAttributes()`

    - #### createLRUMemoryAttributes

          public static EvictionAttributes createLRUMemoryAttributes(ObjectSizer sizer,
                                                                     EvictionAction evictionAction)

      Creates and returns memory LRU eviction attributes with given `evictionAction`, given `sizer`, and default maximum.

      For a region with `DataPolicy.PARTITION`, even if maximumMegabytes are supplied, the EvictionAttribute `maximum`, is always set to `" local max memory "` specified for the `PartitionAttributes`.

      Parameters:
        `sizer` - calculates the size in bytes of the key and value for an entry.
        `evictionAction` - the action to take when the maximum has been reached.
      Returns:
        memory LRU eviction attributes with given `evictionAction`, given `sizer`, and default maximum
      Since:
        GemFire 6.0
      See Also:
        `createLRUMemoryAttributes()`

    - #### getObjectSizer

          public abstract ObjectSizer getObjectSizer()

      An `ObjectSizer` is used by the `EvictionAlgorithm.LRU_MEMORY` algorithm to measure the size of each Entry as it is entered into a Region. A default implementation is provided, see `createLRUMemoryAttributes()` for more. An `ObjectSizer` is used by `EvictionAlgorithm.LRU_HEAP` to estimate how much heap will be saved when evicting a region entry.
      Returns:
        the sizer used by `EvictionAlgorithm.LRU_MEMORY` or `EvictionAlgorithm.LRU_HEAP`, for all other algorithms null is returned.

    - #### getAlgorithm

          public abstract EvictionAlgorithm getAlgorithm()

      The algorithm is used to identify entries that will be evicted.
      Returns:
        a non-null EvictionAlgorithm instance reflecting the configured value or NONE when no eviction controller has been configured.

    - #### getMaximum

          public abstract int getMaximum()

      The unit of this value is determined by the definition of the `EvictionAlgorithm` set by one of the creation methods e.g. `createLRUEntryAttributes()`.
      - If the algorithm is LRU_ENTRY then the unit is entries.
      - If the algorithm is LRU_MEMORY then the unit is megabytes.
      - If the algorithm is LRU_HEAP then the unit is undefined and this method always returns zero. Note, in geode 1.4 and earlier, this method would throw UnsupportedOperationException for LRU_HEAP.
      Returns:
        maximum value used by the `EvictionAlgorithm` which determines when the `EvictionAction` is performed.

    - #### getAction

          public abstract EvictionAction getAction()

      Returns:
        action that the `EvictionAlgorithm` takes when the maximum value is reached.

    - #### equals

          public boolean equals(Object obj)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### createLIFOEntryAttributes

          @Deprecated
          public static EvictionAttributes createLIFOEntryAttributes(int maximumEntries,
                                                                                 EvictionAction evictionAction)

      Deprecated. For internal use only.
      Parameters:
        `maximumEntries` - the number of entries to keep in the Region
        `evictionAction` - the action to perform when evicting an entry
      Returns:
        an EvictionAttributes for the LIFOCapacityController
      Since:
        GemFire 5.7

    - #### createLIFOMemoryAttributes

          @Deprecated
          public static EvictionAttributes createLIFOMemoryAttributes(int maximumMegabytes,
                                                                                  EvictionAction evictionAction)

      Deprecated. For internal use only.
      Parameters:
        `maximumMegabytes` - the maximum allowed bytes in the Region
        `evictionAction` - the action to perform when evicting an entry
      Returns:
        an EvictionAttributes for the MemLIFOCapacityController
      Since:
        GemFire 5.7

    - #### convertToConfigEvictionAttributes

          public RegionAttributesType.EvictionAttributes convertToConfigEvictionAttributes()

    - #### isNoEviction

          public boolean isNoEviction()