# Mustache.java for Java 8 templating and asynchronous callbacks
> Mustache.java is a small, dependency-free Java implementation of mustache.js for applications that render data into Mustache templates. It supports scoped Java objects, collections, template inheritance, optional concurrent callbacks and an invokedynamic compiler, but its default configuration is explicitly unsafe for templates supplied by untrusted parties.
**spullara/mustache.java** — Implementation of mustache.js for Java
- Repository: https://github.com/spullara/mustache.java
- Website: http://www.javarants.com/the-ideal-web-application-templating-system-b301fa4a1f49
- Stars: 1,960 · Forks: 283
- Language: HTML
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/spullara-mustache-java
## Mustache.java's template trust boundary
Mustache.java renders Mustache templates against Java data and is aimed at developers building server-side Java applications, mockups and tests. Its core use is straightforward: sections iterate or conditionally display content, values resolve through Java fields, methods or maps, and partials can compose larger templates. The README names Twitter as a production deployment, but it does not document deployment architecture, configuration or operational experience, so that statement alone does not establish suitability for another system.
The security boundary is unusually explicit. The README states that the default implementation is "UNSAFE" when templates come from untrusted parties. It points to `SafeMustacheFactory` and says that templates and partials should be allowlisted. This is not a general warning attached to template languages. It tells adopters that the normal template loading and compilation path should not be exposed directly to template authors outside the application's trust boundary.
The project addresses this problem in two separate ways. Applications can keep templates as application-owned resources and use a configured template root. If templates originate outside that boundary, the documentation specifically directs developers to `SafeMustacheFactory` and an allowlist. The README does not describe a complete allowlist configuration example, so adopters need to inspect the API documentation and test that each permitted template and partial is rejected unless explicitly allowed.
## Scoped objects and the Mustache.java rendering pipeline
The implementation is a derivative of mustache.js and follows its specification tests apart from whitespace differences. Instead of relying only on a single JSON-like document, Mustache.java accepts an array of scopes. A template value can resolve through a non-private field, a method, or a map. Nested scopes are particularly useful for Java object graphs because a section such as `{{#items}}` can expose each `Item` and then expose that item's collection of features.
Collections do not need to implement a library-specific list abstraction. The README states that any `Iterable` can provide list-like behavior. A `DecoratedCollection` adds access to first, last and index information. That gives applications a path from plain domain collections to richer template metadata without requiring every domain type to match a special interface.
Compilation and rendering are also extensible. The project describes a pluggable system that can override almost all compilation and rendering behavior. The ordinary compiler is one module, while a code-generation module creates guards and mustache code and the `indy` module uses code generation with invokedynamic to compile templates into bytecode. Those alternatives are not interchangeable automatically. The README says performance improvements are often application specific, so the module choice should follow workload evaluation rather than assumptions based on compilation technique.
## Adding compiler 0.9.10 and preparing a first render
The README recommends using Maven dependencies rather than building the repository. For Java 8 and newer, add the `compiler` artifact at version `0.9.10`. It has no external dependencies according to the project documentation.
```xml
com.github.spullara.mustache.java
compiler
0.9.10
```
Java 6 and Java 7 applications have a separate documented dependency line using version `0.8.18`. Since release 0.9.0, the newer line is Java 8 only, so using the modern dependency on an older runtime is not supported by the README.
The first example needs a template and Java backing data. Save this template under a name chosen for your application's configured classpath or file-system template root, such as `items.html`.
```html
{{#items}}
Name: {{name}}
Price: {{price}}
{{#features}}
Feature: {{description}}
{{/features}}
{{/items}}
```
Provide a scope with an `items()` method that returns `List- `. Each item needs `name`, `price` and `features`, while each feature needs `description`. The README's backing classes use non-private fields, which are resolved by Mustache.java. Its example output contains two item groups, each followed by its feature lines.
The repository also contains an `example` module with an end-to-end Java program using `DefaultMustacheFactory`, `MustacheFactory`, `Mustache` and `Writer`. The example listing is truncated before the factory setup and execution calls, and the README does not supply a complete first-run command. The safe next project-specific step is therefore to use the documented example module as the executable reference for factory construction and template loading rather than infer an undocumented `main` command.
## Callback evaluation and optional concurrent execution
Normal evaluation is serial. If a method invoked by a template blocks, rendering pauses until the callback returns. The README illustrates this with a feature `description()` method that calls `Thread.sleep(1000)`. That behavior keeps ordering straightforward, but it also means that a slow value lookup becomes part of the render's critical path.
Mustache.java offers an explicit alternative. When a callback returns a `Callable` and the `MustacheFactory` was configured with an `ExecutorService`, Mustache.java executes that work in another thread. The project associates this mode with scheduled tasks, streaming behavior and asynchronous I/O. The README does not publish cancellation, timeout, exception aggregation or result-ordering rules, so those points require direct API and test verification before asynchronous callbacks handle external operations.
The distinction between Java 8 functions is important. A Java 8 `Function` represents a function or lambda after substitution. If the engine must parse the function's returned text as another template, the README directs developers to `TemplateFunction`, which performs pre-substitution re-parsing. Choosing the wrong abstraction changes whether returned text is emitted as data or interpreted as template content.
This is optional concurrency, not a permanently asynchronous renderer. Applications that need predictable output, small data sets or no shared state may gain little from `ExecutorService`. Applications that call slow services from template-facing methods may benefit, but the callback API alone does not establish safe limits on thread use or ordering.
## Template roots, inheritance and capture support
Mustache.java supports classpath and file-system template roots. It also states that both defaults and manually configured roots are supported. This gives applications a choice between packaging templates with the application and loading them from disk. Neither choice by itself solves the untrusted-template problem: the separate `SafeMustacheFactory` guidance remains relevant when templates originate outside a controlled source.
Template inheritance is implemented using Mustache extensions rather than being left entirely to mustache.js. The README links specification issue 38 and gives the structure `{{