Sizing Examples
The following examples illustrate both pooled and individual cache-sizing configurations.
Note:
Some of the following examples include allocations for off-heap storage. Off-heap data storage (i.e., the off-heap tier) is only available with the BigMemory products.
Pooled Resources
The following configuration sets pools for all of this CacheManager's caches:
<ehcache xmlns...
Name="CM1"
maxBytesLocalHeap="100M"
maxBytesLocalOffHeap="10G"
maxBytesLocalDisk="50G">
...
<cache name="Cache1" ... </cache>
<cache name="Cache2" ... </cache>
<cache name="Cache3" ... </cache>
</ehcache>
Note:
Size-based cache capacity constraints at heap tier (maxBytesLocalHeap) is deprecated now and not expected to work from Java 17 onwards. Consider maxEntriesLocalHeap instead.
CacheManager CM1 automatically allocates these pools equally among its three caches. Each cache gets one third of the allocated heap, off-heap, and local disk. Note that at the CacheManager level, resources can be allocated in bytes only.
Explicitly Sizing Caches
You can explicitly allocate resources to specific caches:
<ehcache xmlns...
Name="CM1"
maxBytesLocalHeap="100M"
maxBytesLocalOffHeap="10G"
maxBytesLocalDisk="60G">
...
<cache name="Cache1" ...
maxBytesLocalHeap="50M"
...
</cache>
<cache name="Cache2" ...
maxBytesLocalOffHeap="5G"
...
</cache>
<cache name="Cache3" ... </cache>
</ehcache>
Note:
Size-based cache capacity constraints at heap tier (maxBytesLocalHeap) is deprecated now and not expected to work from Java 17 onwards. Consider maxEntriesLocalHeap instead.
In the example above, Cache1 reserves 50Mb of the 100Mb local-heap pool; the other caches divide the remaining portion of the pool equally. Cache2 takes half of the local off-heap pool; the other caches divide the remaining portion of the pool equally. Cache3 receives 25Mb of local heap, 2.5Gb of off-heap, and 20Gb of the local disk.
Caches that reserve a portion of a pool are not required to use that portion. Cache1, for example, has a fixed portion of the local heap but may have any amount of data in heap up to the configured value of 50Mb.
Note that caches must use the same sizing attributes used to create the pool. Cache1, for example, cannot use maxEntriesLocalHeap to reserve a portion of the pool.
Mixed Sizing Configurations
If a CacheManager does not pool a particular resource, that resource can still be allocated in cache configuration, as shown in the following example.
<ehcache xmlns...
Name="CM2"
maxBytesLocalHeap="100M">
...
<cache name="Cache4" ...
maxBytesLocalHeap="50M"
maxEntriesLocalDisk="100000"
...
</cache>
<cache name="Cache5" ...
maxBytesLocalOffHeap="10G"
...
</cache>
<cache name="Cache6" ... </cache>
</ehcache>
Note:
Size-based cache capacity constraints at heap tier (maxBytesLocalHeap) is deprecated now and not expected to work from Java 17 onwards. Consider maxEntriesLocalHeap instead.
CacheManager CM2 creates one pool (local heap). Its caches all use the local heap and are constrained by the pool setting, as expected. However, cache configuration can allocate other resources as desired. In this example, Cache4 allocates disk space for its data, and Cache5 allocates off-heap space for its data. Cache6 gets 25Mb of local heap only.
Using Percents
The following configuration sets pools for each tier:
<ehcache xmlns...
Name="CM1"
maxBytesLocalHeap="1G"
maxBytesLocalOffHeap="10G"
maxBytesLocalDisk="50G">
...
<!-- Cache1 gets 400Mb of heap, 2.5Gb of off-heap, and 5Gb of disk. -->
<cache name="Cache1" ...
maxBytesLocalHeap="40%">
</cache>
<!-- Cache2 gets 300Mb of heap, 5Gb of off-heap, and 5Gb of disk. -->
<cache name="Cache2" ...
maxBytesLocalOffHeap="50%">
</cache>
<!-- Cache2 gets 300Mb of heap, 2.5Gb of off-heap, and 40Gb of disk. -->
<cache name="Cache3" ...
maxBytesLocalDisk="80%">
</cache>
</ehcache>
Note:
You can use a percentage of the total JVM heap for the CacheManager maxBytesLocalHeap. The CacheManager percentage, then, is a portion of the total JVM heap, and in turn, the Cache percentage is the portion of the CacheManager pool for that tier.
Note:
Size-based cache capacity constraints at heap tier (maxBytesLocalHeap) is deprecated now and not expected to work from Java 17 onwards. Consider maxEntriesLocalHeap instead.
Sizing Without a Pool
The CacheManager in this example does not pool any resources.
<ehcache xmlns...
Name="CM3"
... >
...
<cache name="Cache7" ...
maxBytesLocalHeap="50M"
maxEntriesLocalDisk="100000"
...
</cache>
<cache name="Cache8" ...
maxEntriesLocalHeap="1000"
maxBytesLocalOffHeap="10G"
...
</cache>
<cache name="Cache9" ...
maxBytesLocalHeap="50M"
...
</cache>
</ehcache>
Note:
Size-based cache capacity constraints at heap tier (maxBytesLocalHeap) is deprecated now and not expected to work from Java 17 onwards. Consider maxEntriesLocalHeap instead.
Caches can be configured to use resources as necessary. Note that every cache in this example must declare a value for local heap. This is because no pool exists for the local heap; implicit (CacheManager configuration) or explicit (cache configuration) local-heap allocation is required.