Module gg.jte.runtime

Package gg.jte

Class TemplateEngine

java.lang.Object

gg.jte.TemplateEngine

public final class TemplateEngine
extends Object

jte is a simple, yet powerful template engine for Java. All jte templates are compiled to Java class files, meaning jte adds essentially zero overhead to your application. jte is designed to introduce as few new keywords as possible and builds upon existing Java features, so that it is very easy to reason about what a template does.
Read more at the official documentation

Method Summary

Modifier and Type	Method	Description
void	cleanAll()	Cleans the directory containing the compiled template classes.
void	clearCache()	Clears all cached templates.
static TemplateEngine	create(CodeResolver codeResolver, ContentType contentType)	Creates a new template engine.
static TemplateEngine	create(CodeResolver codeResolver, Path classDirectory, ContentType contentType)	Creates a new template engine.
static TemplateEngine	create(CodeResolver codeResolver, Path classDirectory, ContentType contentType, ClassLoader parentClassLoader)	Creates a new template engine.
static TemplateEngine	create(CodeResolver codeResolver, Path classDirectory, ContentType contentType, ClassLoader parentClassLoader, String packageName)	Creates a new template engine.
static TemplateEngine	createPrecompiled(ContentType contentType)	Creates a new template engine.
static TemplateEngine	createPrecompiled(Path classDirectory, ContentType contentType)	Creates a new template engine.
static TemplateEngine	createPrecompiled(Path classDirectory, ContentType contentType, ClassLoader parentClassLoader)	Creates a new template engine.
static TemplateEngine	createPrecompiled(Path classDirectory, ContentType contentType, ClassLoader parentClassLoader, String packageName)	Creates a new template engine.
List<String>	generateAll()	Generates all template classes in the sources directory, to the compiled template classes directory.
Map<String,Class<?>>	getParamInfo(String name)	Obtain parameter information about a specific template.
List<String>	getTemplatesUsing(String name)
boolean	hasTemplate(String name)
List<String>	precompileAll()	Compiles all templates located in the sources directory, to the compiled template classes directory.
List<String>	precompileAll(List<String> classPath)	Compiles all templates located in the sources directory, to the compiled template classes directory.
void	prepareForRendering(String name)	Prepares the template with the given name for rendering
TemplateEngine	reloadPrecompiled(TemplateEngine precompiler)	Useful, if this engine is in precompiled mode (probably production) but you still want to be able to apply a hotfix without deployment.
TemplateEngine	reloadPrecompiled(Path classDirectory)	Useful, if this engine is in precompiled mode (probably production) but you still want to be able to apply a hotfix without deployment.
void	render(String name, Object param, TemplateOutput output)	Renders the template with the given name.
void	render(String name, Map<String,Object> params, TemplateOutput output)	Renders the template with the given name.
void	setBinaryStaticContent(boolean binaryStaticContent)	Setting, that UTF-8 encodes all static template parts at compile time.
void	setClassPath(List<String> classPath)	The class path used for compiling templates.
void	setCompileArgs(String... compileArgs)	Sets additional compiler arguments for jte templates.
void	setExtensions(Map<String,Map<String,String>> extensionSettings)	Optional - Extensions this template engine should load.
void	setHtmlCommentsPreserved(boolean htmlCommentsPreserved)	By default, jte omits all HTML/CSS/JS comments, when compiling with ContentType.Html.
void	setHtmlInterceptor(HtmlInterceptor htmlInterceptor)	Interceptor that is called during template rendering when one of the configured htmlTags is rendered.
void	setHtmlPolicy(HtmlPolicy htmlPolicy)	Policy that checks the parsed HTML at compile time.
void	setHtmlTags(String... htmlTags)	Intercepts the given html tags during template compilation and calls the configured htmlInterceptor during template rendering.
void	setKotlinCompileArgs(String... compileArgs)	Sets additional compiler arguments for kte templates.
void	setProjectNamespace(String projectNamespace)	"group/artifact" of the project using jte.
void	setTargetResourceDirectory(Path targetResourceDirectory)	Directory in which to generate non-java files (resources).
void	setTrimControlStructures(boolean value)	Trims control structures, resulting in prettier output.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

create

public static TemplateEngine create(CodeResolver codeResolver,
 ContentType contentType)

Creates a new template engine. All templates are compiled to Java class files on demand. A JDK is required. Every template has its own class loader. This is recommended when running templates on your developer machine.

Parameters:

codeResolver - to lookup jte templates

contentType - the content type of all templates this engine manages

Returns:

a fresh TemplateEngine instance

create

public static TemplateEngine create(CodeResolver codeResolver,
 Path classDirectory,
 ContentType contentType)

Creates a new template engine. All templates are compiled to Java class files on demand. A JDK is required. Every template has its own class loader. This is recommended when running templates on your developer machine.

Parameters:

codeResolver - to lookup jte templates

classDirectory - where template class files are compiled to

contentType - the content type of all templates this engine manages

Returns:

a fresh TemplateEngine instance

create

public static TemplateEngine create(CodeResolver codeResolver,
 Path classDirectory,
 ContentType contentType,
 ClassLoader parentClassLoader)

Creates a new template engine. All templates are compiled to Java class files on demand. A JDK is required. Every template has its own class loader. This is recommended when running templates on your developer machine.

Parameters:

codeResolver - to lookup jte templates

classDirectory - where template class files are compiled to

contentType - the content type of all templates this engine manages

parentClassLoader - the parent classloader to use, or null to use the application class loader as parent

Returns:

a fresh TemplateEngine instance

create

public static TemplateEngine create(CodeResolver codeResolver,
 Path classDirectory,
 ContentType contentType,
 ClassLoader parentClassLoader,
 String packageName)

Creates a new template engine. All templates are compiled to Java class files on demand. A JDK is required. Every template has its own class loader. This is recommended when running templates on your developer machine.

Parameters:

codeResolver - to lookup jte templates

classDirectory - where template class files are compiled to

contentType - the content type of all templates this engine manages

parentClassLoader - the parent classloader to use, or null to use the application class loader as parent

packageName - the package name, where template classes are generated to

Returns:

a fresh TemplateEngine instance

createPrecompiled

public static TemplateEngine createPrecompiled(Path classDirectory,
 ContentType contentType)

Creates a new template engine. All templates must have been precompiled to Java class files already. The template engine will load them from the specified classDirectory. No JDK is required. All templates share one class loader with each other. This is recommended when running templates in production. How to precompile templates.

Parameters:

classDirectory - where template class files are located

contentType - the content type of all templates this engine manages

Returns:

a fresh TemplateEngine instance

createPrecompiled

public static TemplateEngine createPrecompiled(ContentType contentType)

Creates a new template engine. All templates must have been precompiled to Java class files already. The template engine will load them via the application class loader. This means all template classes must be bundled in you application JAR file. No JDK is required. This is recommended when running templates in production. How to precompile templates.

Parameters:

contentType - the content type of all templates this engine manages

Returns:

a fresh TemplateEngine instance

createPrecompiled

public static TemplateEngine createPrecompiled(Path classDirectory,
 ContentType contentType,
 ClassLoader parentClassLoader)

Creates a new template engine. All templates must have been precompiled to Java class files already. The template engine will load them from the specified classDirectory. No JDK is required. All templates share one class loader with each other. This is recommended when running templates in production. How to precompile templates.

Parameters:

classDirectory - where template class files are located

contentType - the content type of all templates this engine manages

parentClassLoader - the parent classloader to use, or null to use the application class loader as parent (only has an effect if classDirectory is not null)

Returns:

a fresh TemplateEngine instance

createPrecompiled

public static TemplateEngine createPrecompiled(Path classDirectory,
 ContentType contentType,
 ClassLoader parentClassLoader,
 String packageName)

Creates a new template engine. All templates must have been precompiled to Java class files already. The template engine will load them from the specified classDirectory. No JDK is required. All templates share one class loader with each other. This is recommended when running templates in production. How to precompile templates.

Parameters:

classDirectory - where template class files are located

contentType - the content type of all templates this engine manages

parentClassLoader - the parent classloader to use, or null to use the application class loader as parent (only has an effect if classDirectory is not null)

packageName - the package name, where template classes are generated to

Returns:

a fresh TemplateEngine instance

render

public void render(String name,
 Object param,
 TemplateOutput output)
            throws TemplateException

Renders the template with the given name. It is preferred to use this method, if all your templates have exactly one parameter.

Parameters:

name - the template name relative to the specified root directory, for instance "pages/welcome.jte".

param - the param passed to the template.

output - any implementation of TemplateOutput, where the template will be written to.

Throws:

TemplateException - in case the template failed to render, containing information where the error happened.

render

public void render(String name,
 Map<String,Object> params,
 TemplateOutput output)
            throws TemplateException

Renders the template with the given name. Parameters in the params map are mapped to the corresponding parameters in the template. Template parameters with a default value don't have to be provided in the map.

Parameters:

name - the template name relative to the specified root directory, for instance "pages/welcome.jte".

params - the parameters passed to the template as key value pairs.

output - any implementation of TemplateOutput, where the template will be written to.

Throws:

TemplateException - in case the template failed to render, containing information where the error happened.

hasTemplate

public boolean hasTemplate(String name)

getTemplatesUsing

public List<String> getTemplatesUsing(String name)

getParamInfo

public Map<String,Class<?>> getParamInfo(String name)
                                  throws TemplateException

Obtain parameter information about a specific template.

Parameters:

name - the template name relative to the specified root directory, for instance "my/example.jte".

Returns:

a map containing all template parameters names and their classes

Throws:

TemplateException - in case parameter information is not available (jte classes must be compiled with -parameters compiler flag.)

prepareForRendering

public void prepareForRendering(String name)

Prepares the template with the given name for rendering

Parameters:

name - the template name relative to the specified root directory, for instance "pages/welcome.jte".

cleanAll

public void cleanAll()

Cleans the directory containing the compiled template classes.

generateAll

public List<String> generateAll()

Generates all template classes in the sources directory, to the compiled template classes directory. This only generates .java files, not .class files.

Returns:

list of .java template files that were generated

precompileAll

public List<String> precompileAll()

Compiles all templates located in the sources directory, to the compiled template classes directory.

Returns:

list of .java template files that were compiled

precompileAll

public List<String> precompileAll(List<String> classPath)

Compiles all templates located in the sources directory, to the compiled template classes directory.

Parameters:

classPath - additional class path arguments for the Java compiler. See also setClassPath(List)

Returns:

list of .java template files that were compiled

clearCache

public void clearCache()

Clears all cached templates. Future invocations of render methods will result in reloaded template classes.

reloadPrecompiled

public TemplateEngine reloadPrecompiled(TemplateEngine precompiler)
                                 throws TemplateException

Useful, if this engine is in precompiled mode (probably production) but you still want to be able to apply a hotfix without deployment. This template engine will be entirely unaffected by this call. Instead, a fresh template engine will be created. When this call succeeds, you can safely switch the template engine reference to the new instance. The old instance including all old templates should then be subject to garbage collection.
This only works if you're running on the JDK and if templates have their own classloader.

Parameters:

precompiler - a template engine that is configured exactly as you usually would precompile your templates.

Returns:

a fresh template engine with a warmed up cache.

Throws:

TemplateException - in case there was a compilation error, in this case you should keep the current engine running!

reloadPrecompiled

public TemplateEngine reloadPrecompiled(Path classDirectory)
                                 throws TemplateException

Useful, if this engine is in precompiled mode (probably production) but you still want to be able to apply a hotfix without deployment. This template engine will be entirely unaffected by this call. Instead, a fresh template engine will be created. When this call succeeds, you can safely switch the template engine reference to the new instance. The old instance including all old templates should then be subject to garbage collection.
Basically you could recompile all templates on your build server, upload them to your production server and call this method afterwards.
This only works if templates have their own classloader.

Parameters:

classDirectory - the class directory to load the new templates from.

Returns:

a fresh template engine with a warmed up cache.

Throws:

TemplateException - in case there was an error during class loading, in this case you should keep the current engine running!

setCompileArgs

public void setCompileArgs(String... compileArgs)

Sets additional compiler arguments for jte templates.
This is a template compilation setting and has no effect when loading precompiled templates.

Parameters:

compileArgs - for instance templateEngine.setCompileArgs("--enable-preview", "--release", "" + Runtime.version().feature());

setKotlinCompileArgs

public void setKotlinCompileArgs(String... compileArgs)

Sets additional compiler arguments for kte templates.
This is a template compilation setting and has no effect when loading precompiled templates. Currently, only -jvm-target is supported.

Parameters:

compileArgs - for instance templateEngine.setCompileArgs("-jvm-target", "17");

setTrimControlStructures

public void setTrimControlStructures(boolean value)

Trims control structures, resulting in prettier output.
This is a template compilation setting and has no effect when loading precompiled templates.

Parameters:

value - true, to enable

setHtmlPolicy

public void setHtmlPolicy(HtmlPolicy htmlPolicy)

Policy that checks the parsed HTML at compile time.
This is a template compilation setting and has no effect when loading precompiled templates.

Parameters:

htmlPolicy - the policy

Throws:

NullPointerException - if policy is null

setHtmlTags

public void setHtmlTags(String... htmlTags)

Intercepts the given html tags during template compilation and calls the configured htmlInterceptor during template rendering.
This is a template compilation setting and has no effect when loading precompiled templates.

Parameters:

htmlTags - tags to be intercepted, for instance setHtmlTags("form", "input");

setHtmlInterceptor

public void setHtmlInterceptor(HtmlInterceptor htmlInterceptor)

Interceptor that is called during template rendering when one of the configured htmlTags is rendered. This allows to integrate existing frameworks into jte.

Parameters:

htmlInterceptor - the interceptor

setHtmlCommentsPreserved

public void setHtmlCommentsPreserved(boolean htmlCommentsPreserved)

By default, jte omits all HTML/CSS/JS comments, when compiling with ContentType.Html. If you don't want this behavior, you can disable it here.
This is a template compilation setting and has no effect when loading precompiled templates.

Parameters:

htmlCommentsPreserved - true, to preserve HTML comments in templates

setBinaryStaticContent

public void setBinaryStaticContent(boolean binaryStaticContent)

Setting, that UTF-8 encodes all static template parts at compile time. Only makes sense if you use a binary output, like Utf8ByteOutput.
This is a template compilation setting and has no effect when loading precompiled templates.

Parameters:

binaryStaticContent - true, to pre-generate UTF-8 encoded byte arrays for all static template parts

setClassPath

public void setClassPath(List<String> classPath)

The class path used for compiling templates.
This is a template compilation setting and has no effect when loading precompiled templates.

Parameters:

classPath - list of elements on the class path

setTargetResourceDirectory

public void setTargetResourceDirectory(Path targetResourceDirectory)

Directory in which to generate non-java files (resources). Typically, set by plugin rather than end user. Optional - if null, resources will not be generated
This is a template compilation setting and has no effect when loading precompiled templates.

Parameters:

targetResourceDirectory - directory to generate resources in

setProjectNamespace

public void setProjectNamespace(String projectNamespace)

"group/artifact" of the project using jte. Typically, set by plugin rather than end user. If null, the compiler will make one up.
This is a template compilation setting and has no effect when loading precompiled templates.

Parameters:

projectNamespace - "groupId/artifactId"

setExtensions

public void setExtensions(Map<String,Map<String,String>> extensionSettings)

Optional - Extensions this template engine should load. Currently, the following extensions exist:

• gg.jte.models.generator.ModelExtension
• gg.jte.nativeimage.NativeResourcesExtension

Sample usage: templateEngine.setExtensions(Map.of("gg.jte.models.generator.ModelExtension", Map.of()));