Need better documentation of the XML config (3.x)

[Trevin Beattie]

I’m working on upgrading a Spring Boot project which was using ehcache 2.8 to use 3.10 instead.  The ehcache.xml file has to be completely rewritten, but ehcache’s documentation (https://www.ehcache.org/documentation/3.10/xml.html) only gives a brief description of the top-level elements and some sparse examples, and the XSD (https://www.ehcache.org/schema/ehcache-core-3.10.xsd) is not a human-friendly document nor does it describe all of the possible elements and attributes.  Some of the specific things I’m looking for are:

• How do I configure persistent disk storage for the cache?  The document suggests the <persistence> element for configuring storage and happens to show that “directory” is an attribute (as opposed to a child element) in one of its examples (under an unrelated topic), but it doesn’t indicate whether this element supports any additional attributes or children nor can I find anything in the documentation on how to set the caches to use this storage.  (This would be things like overflowToDisk and maxElementsOnDisk in ehcache 2.)
• How do I set a cache size limit in bytes?  The document suggests the <resources> child element of a <cache> but once again fails to describe what goes in this element, and the given examples only show two child elements <heap> and <offheap> each with a “unit” attribute and value, but it doesn’t explain the difference between these elements, doesn’t show the <disk> element anywhere (which I found in the XSD), and doesn’t list the possible units.
• What are the possible <expiry> settings?  The document doesn’t give any examples of this, much less any documentation.  The XSD shows it may contain one of the <class>, <tti>, <ttl>, or <none> elements and has a description of each, but it’s difficult to suss how to write these from just the XSD.
• What are the equivalents, if any, of these ehcache 2 cache attributes?
  • eternal — prevent cache entries from expiring after any amount of time
  • overflowToDisk — controls whether elements that exceed the in-memory cache size get written to disk (see first bullet point)
  • memoryStoreEvectionPolicy — determines which elements are evicted from a cache when full; one of “LRU” (Least Recently Used), “LFU” (Least Frequently Used), or “FIFO” (First In, First Out; i.e. oldest).  The document suggests the <eviction-advisor> element may be used for this but doesn’t show any examples or list of available advisors; even the page about Evection Advisor (https://www.ehcache.org/documentation/3.10/eviction-advisor.html) only shows one example (OddKeysEvictionAdvisor) but doesn’t say where that class comes from and I can’t even find its source code.
• The document lists an <integration> child of a <cache> element (“configure a CacheLoaderWriter for a cache-through pattern”) but doesn’t go into any more detail about what this means, and I can’t find this element in the XSD either.
• What are the possible configuration options for <service> elements?  Is this necessary for using JSR-107 features like statistics, as shown in one of the examples on the JSR-107 page (https://www.ehcache.org/documentation/3.10/107.html)?

[Trevin Beattie]

I may also be missing something more fundamental.  When running unit tests I find that Eh107CacheManager doesn’t contain any of my configured caches, even though I have ehcache.xml available under src/main/resources and my main application class is annotated with @EnableCaching.  My current cache configuration is below:

<config xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xmlns='http://www.ehcache.org/v3'
xmlns:jsr107='http://www.ehcache.org/v3/jsr107'
xsi:schemaLocation="http://www.ehcache.org/v3 http://www.ehcache.org/schema/ehcache-core.xsd">

  <persistence directory="${java.io.tmpdir}"/>

  <cache-template name="cacheDefaults">
    <key-type>com.activeos.cache.ActiveOSCacheKey</key-type>
    <value-type>java.io.Serializable</value-type>
    <expiry>
      <tti unit="seconds">300</tti>
    </expiry>
    <resources>
      <heap unit="MB">150</heap>
      <disk unit="entries">1000</disk>
    </resources>
    <jsr107:mbeans enable-management="false" enable-statistics="true"/>
  </cache-template>

  <cache alias="defaultCache" uses-template="cacheDefaults">
    <resources>
      <heap unit="MB">10</heap>
    </resources>
  </cache>

  <cache alias="stats" uses-template="cacheDefaults">
  </cache>

  <cache alias="bar" uses-template="cacheDefaults">
  </cache>

  <cache alias="foo" uses-template="cacheDefaults">
  </cache>

</config>

The code is looking for the cache with:

import javax.cache.*;

…

    @Autowired
    CacheManager cacheManager;

    private Cache<CacheKey, Serializable> getCache(String cacheName) {

        Cache<CacheKey, Serializable> cache =
                cacheManager.getCache(cacheName,
                        CacheKey.class, Serializable.class);
        if (cache == null) {
            throw new CacheException(String.format(
                    "Can't find %s cache!", cacheName));
        } else {
            return cache;
        }

    }

[Trevin Beattie]

Something else that was not mentioned anywhere in the Ehcache documentation is that it doesn’t even look at the ehcache.xml configuration file unless I add “spring.cache.jcache.config=classpath:ehcache.xml” to the Spring Boot application properties.  I found this out from a Baeldung article (https://www.baeldung.com/spring-boot-ehcache).