Handlebars Java Precompiled Template Cache Sizing and Trusted Source Boundaries

Direct Answer

Handlebars.java provides no native cache limit or eviction policy. You must wrap the template store with a size-bounded cache (Caffeine or Guava) and restrict the TemplateLoader to a read-only classpath location containing only build-time artifacts. There is no documented configuration property in the library to cap the cache.

Heap-Based Limit

Set the maximum entry count based on measured per-template heap cost, not a fixed number. Profile a representative template set (e.g., 500–1,000 templates) with VisualVM or JProfiler to determine the average retained size of a Template object plus its generated JavaScript source string. Multiply that average by your target cache budget (e.g., 50 MB) to derive the entry cap. In practice, simple templates often average 5–15 KB each; complex ones with many partials can exceed 50 KB.

Trusted Source Boundary

1. Precompile templates at build time (Maven/Gradle plugin) into target/classes/templates or src/main/resources/templates.
2. Package only that directory in the JAR. Do not mount a writable volume or allow filesystem paths at runtime.
3. Use a ClassPathTemplateLoader pointed at the packaged prefix (e.g., /templates/). This loader reads from the sealed JAR, preventing post-deployment modification.
4. If you must support external overrides in a controlled way, layer a second, read-only config directory via a composite loader that delegates to the classpath loader first.

Cache Wrapper Pattern

import com.github.jknack.handlebars.Handlebars;
import com.github.jknack.handlebars.Template;
import com.github.jknack.handlebars.io.ClassPathTemplateLoader;
import com.github.jknack.handlebars.io.TemplateLoader;
import com.github.benmanes.caffeine.cache.Caffeine;
import com.github.benmanes.caffeine.cache.LoadingCache;

public final class BoundedTemplateCache {
    private final LoadingCache<String, Template> cache;
    private final Handlebars handlebars;

    public BoundedTemplateCache(int maxEntries) {
        TemplateLoader loader = new ClassPathTemplateLoader("/templates", ".hbs");
        this.handlebars = new Handlebars(loader);
        this.cache = Caffeine.newBuilder()
                .maximumSize(maxEntries)
                .build(key -> handlebars.compile(key));
    }

    public Template get(String name) {
        return cache.get(name);
    }
}

Configure maxEntries from the profiled per-template size and your heap budget. The cache evicts least-recently-used entries automatically.

Verification Steps

1. Run a load test that touches more templates than maxEntries; confirm eviction via Caffeine stats (cache.stats().evictionCount()).
2. Scan the deployed JAR: jar tf app.jar | grep templates/ — only .hbs or precompiled .js files should appear.
3. Attempt to write to the template path at runtime; the ClassPathTemplateLoader will throw IOException.

One Diagnostic Needed

What is the average retained heap size of a single compiled Template object in your application (measured with your actual templates)? This number directly determines the safe maximumSize for your container's heap limit.