bootique / bootique-mvc Goto Github PK

Create a module supporting Mustache templates. The actual integration will be based on Jersey MVC. Late we may create modules for Freemarker and JSP templates.

This module will depend on bootique-jersey, and template rendering will be done via JAX-RS.

The main Mustache template loading mechanism is controlled by Bootique, while loading templates for "partials" (i.e. includes) happens via built-in Mustache mechanism implemented in com.github.mustachejava.resolver.DefaultResolver (cascading lookup in classpath, filesystem, and URL).

This appears to work most fo the time (especially for classpath templates), but in general it is really undeterministic. We should implement a more controlled approach:

• if a "partial" resource location is an asbolute URI, resolve it as such
• otherwise resolve it against the app "templateBase"

Now that we have both Jetty and Jersey module versions compatible with Jakarta EE, let's provide bootique-mvc-jakarta* versions of the MVC packages.

Currently Mustache templates are reloaded on every render call, which is rather inefficient. Let's support caching of compiled templates in MustacheTemplateRenderer, with reload interval configurable via YAML:

mvc:
   templateTtl: 30s

For backwards compatibility, the default (if TTL is unset) will be "reload every time". This configuration is not Mustache-specific, so we will need to open a task to support it in Freemarker provider as well.

bootique/bootique#72 provides late resolving to folder resource URLs. Let's upgrade to take advantage of that.

Mustache-java supports multi-threaded template rendering. Model writers will need to provide Callable return types for this to happen. But the framework also needs to be configured with a thread pool according to this:

If you change description to return a Callable instead it will automatically be executed in a separate thread if you have provided an ExecutorService when you created your MustacheFactory [..] This enables scheduled tasks, streaming behavior and asynchronous i/o..

MVC Template object is just a pointer to a template location. It never changes, so there's no reason to create it every time. If we can cache it, it can precalculate template URL and resolve the real template much faster.

Currently MVC template location is tied to the REST resource package path. This may be a good default occasionally, still I find it annoying and prefer to ties templates to the view classes that are separate from REST API (controller). So redoing the TemplateResolver API to take an arbitrary class, and using view as the default.

Currently we don't have a unified template resolving mechanism that works the same way for Mustache and Freemarker and for root templates and included templates (see #24) . This causes confusion as well as security concerns. Let's implement a single mechanism across the board that works the following way:

• (current behavior) the app must define a single "templateBase" that can be a web URL, a filesystem path or a classpath base
• (current behavior) Root templates associated with the views should resolve against "templateBase" by building a path based on the view package (e.g. for org.example.MyView the path for the root template may be org/example/xyz.mustache or org/example/xyz.ftl)
• A subtemplate specified with an absolute path (starting with a "/") will be resolved against "templateBase"
• A subtemplate with a relative path will be resolved against the view path. E.g. my/subtemplate.mustache will be resolved as org/example/my/subtemplate.mustache
• Perform security checks to avoid breaking out of the "templateBase" by using otherwise permissible ../

Upgrade Notes

• Root template names starting with / may no longer work, as the package name will not be prepended to them. You will need to remove the slash if you want them resolved relative to the view Java class.

bootique-jetty 0.14 introduced a breaking APi change. So lets upgrade ASAP.

New module to support FreeMarker templates

For now you need to restart server after template change or use some other tools for prototyping. It will be really great if bootique-mvc can reload template in runtime. This may be configurable, to disable on production.

Implies an upgrade to the latest bootique (0.19), bootique-jetty (0.17), bootique-jeresey (0.18)

• add config documentation
• change "contribute" API to "extend"

Part of the overall deprecated API cleanup per bootique/bootique#214

Current template resolving mechanism inherited from jersey-mvc is not very user-friendly. Per Jersey AbstractTemplateProcessor.resolve, it looks for a package with the name of the resource Java class (e.g. com.foo.MyResource results in com/foo/MyResource/template.mustache).

We should probably use an algorithm like this:

template_path = basePath + resource_package_path + template_name_with_ext

and then the lookup strategy should be based on 'basePath' value... If it has a URL prefix, resolve it as a URL, if it starts with classpath:, resolve as classpath, otherwise treat it like a file. (analogous to staticResourceBase in JettyModule). This will ensure predictability of the template resolution.

Perhaps we can drop Jersey MVC all together, avoiding its APIs like Viewable and @Template

We just implemented a common bootique-mvc configuration for template TTL, and switched the Mustache engine to use it (see #3). Let's do the same thing for Freemarker.

There are some breaking change in 0.20 ... Upgrading all standard modules