APPLIES TO:

Oracle Coherence - Version 3.2.2 to 3.7.1.1

Information in this document applies to any platform.

GOAL

Default size for all caches using local-scheme is unlimited. This document helps
on configuring a cache to be size limited.

SOLUTION

In order to set a size limit on a cache, the <high-units> element of <local-scheme>

must be configured. Here is an example:

<local-scheme>
<scheme-name>local</scheme-name>
<high-units>1000</high-units>
</local-scheme>

This cache will be limited to 1000 objects. If the limit is exceeded, 25% of the items
will be pruned from the cache by default. This behavior can be configured by setting
<low-units>:

<local-scheme>
<scheme-name>local</scheme-name>
<high-units>1000</high-units>
<low-units>900</high-units>
</local-scheme>

This cache will be pruned to 900 units if the high-units count is exceeded.

To configure a size limited backing map for a distributed cache:

<distributed-scheme>
<scheme-name>distributed</scheme-name>
<backing-map-scheme>
<local-scheme>
<high-units>10000</high-units>
</local-scheme>
<backing-map-scheme>
</distributed-scheme>

With this configuration, every storage enabled node will be capable of storing up to
10000 objects.

The same technique can be used to size limit a near cache:

<near-scheme>
<scheme-name>near</scheme-name>

<front-scheme>
<local-scheme>
<high-units>1000</high-units>
</local-scheme>
</front-scheme>

<back-scheme>
<distributed-scheme>
...
</distributed-scheme>
</back-scheme>

<autostart>true</autostart>
</near-scheme>

High units can also be configured in terms of bytes instead of number of objects in
the cache. This can only be done in distributed cache backing maps because objects
are stored in binary (serialized) form. Here is an example:

<distributed-scheme>
<scheme-name>distributed</scheme-name>
<backing-map-scheme>
<local-scheme>
<high-units>10485760</high-units>
<unit-calculator>BINARY</unit-calculator>
</local-scheme>
<backing-map-scheme>
</distributed-scheme>

In the example above, the backing map for the distributed scheme is limited to 10mb
of storage. Note that the units are expressed in number of bytes. Starting with
Coherence 3.4, the units can be expressed in megabytes as such:

<high-units>10m</high-units>

Here are some additional tips to keep in mind:

 High units are per storage node. For instance, 5 storage nodes with a high-
units configuration of 10mb can theoretically store up to 50mb. However this
implies a perfect distribution which is normally not the case.
 High units are per named cache. If two caches are mapped to a scheme
(service) and the scheme specifies a high units of 10mb, then each cache will
have a high units of 10mb, meaning 20mb of storage total. This is especially
important to keep in mind when using a wildcard (*) naming convention.
 For backing maps, high units only take primary storage into account. With a
backup count of 1 (the default) a high-units setting of 10mb really means that
up to 20mb of heap space will be required on that node for that cache, 10mb
for the actual cache entries, and a further 10mb for the backup storage.
  The entire heap of a dedicated storage node cannot be used for storage. In
other words, a 1gb heap cannot hold 1gb of cache data. At the very most,
~75% can be used for cache storage (around 750mb.) If the storage node is
performing grid functions (such as entry processors, filters, or aggregations)
then the total high-units setting should be less than 75%.

A sample configuration could look like this: 1gb JVM with 700mb dedicated
storage. Half of the storage is primary and half is backup. Therefore, the total high-
units for that node should not exceed 350mb.