Apache FreeMarker is configured using the freemarker.properties file.
This configuration is mandatory in order to make FreeMarker work with your own templates.
The first step entails retrieving a copy of this file. See MergeTransformMicroService page for more details.
This file is a Java .properties file (key syntax = value).
The second step entails changing or entering the keys according to requirements.
The only key that must be changed is the "template_loader" key, which is used to define the template loader.
Freemarker.properties file keys
Key | Description | ||||||||||||||||||||||||||||||||||||||||
| template_loader | |||||||||||||||||||||||||||||||||||||||||
Template loader. Default value: freemarker.cache.MultiTemplateLoader( \ [com.hardis.adelia.mergedocengine.freemarker.conf.ClassTemplateLoader(com.hardis.adelia.mergedocengine.ProcessTemplate.CLASS_FOR_OBJECT_BUILDER_EXPRESSION, "/com/hardis/adelia/mergedocengine/freemarker/lib")]) The "\" character indicates a line break in a key's value. You need to add your own loader to the APE's default loader. There are several types of loader available, depending on the format of your template deliverables, i.e.
Loader "com.hardis.adelia.mergedocengine.freemarker.conf.FileTemplateLoader"The parameters are as follows:
For example, if your user templates are in "c:\billingTemplates" and "c:\reportingTemplates" directories:
Loader "com.hardis.adelia.mergedocengine.freemarker.conf.ClassTemplateLoader"The parameters are as follows:
For example, if your user templates are in a JAR file located in the "/myTemplates" package (the JAR file must be present in the Java CLASSPATH):
Loader "com.hardis.adelia.mergedocengine.freemarker.conf.ZipFileTemplateLoader"The parameters are as follows:
For example, if your user templates are in the "c:\billingTemplates.zip" (accessible from the file root) and "c:\reportingTemplates.zip" (accessible from the "year2019" sub-directory) files:
| |||||||||||||||||||||||||||||||||||||||||
default_encoding | |||||||||||||||||||||||||||||||||||||||||
Default encoding of templates read from a locale with no associated encoding. Default value: UTF-8 | |||||||||||||||||||||||||||||||||||||||||
template_update_delay | |||||||||||||||||||||||||||||||||||||||||
Defines the time in milliseconds that needs to elapse before the template cache management module checks whether there is a more recent version of a template than the one in the cache. The default value is 5 s. In the template development phase, this value indicates the minimum wait time between when the template is saved (saving a change for example) and its availability to be processed (to test the result of the change) by the FreeMarker engine. So a value in the region of one second needs to be indicated. In the production phase, it may be beneficial to have a very large value to avoid affecting the engine's performance under heavy load. | |||||||||||||||||||||||||||||||||||||||||
locale | |||||||||||||||||||||||||||||||||||||||||
Defines the locale used by default if no locale is specified in the Web services parameters. | |||||||||||||||||||||||||||||||||||||||||
template_exception_handler | |||||||||||||||||||||||||||||||||||||||||
Defines the error handling strategy during template processing. Default value: "rethrow" | |||||||||||||||||||||||||||||||||||||||||
boolean_format | |||||||||||||||||||||||||||||||||||||||||
Defines the alphanumeric values used to convert a FreeMarker boolean value into an alphanumeric string in the ${ booleanValue } interpolation. Default values: yes, no ("yes" for true and "no" for false) | |||||||||||||||||||||||||||||||||||||||||
extSharedVariables | |||||||||||||||||||||||||||||||||||||||||
Used to define one or more variables which are shared by all the templates. The syntax must be a Map. For example: extSharedVariables = { "sharedNumberVar": 10, \
These variables may be manipulated in the templates by using ${ sharedNumberVar }, ${sharedSequenceVar[1]} , ${sharedHashVar.subVar1} interpolations, etc. Important: if a level-one variable in the data model has the same name as a shared variable, the data model variable will "hide" the shared variable. | |||||||||||||||||||||||||||||||||||||||||
Injecting environment variables into freemarker.properties
The APE allows you to inject environment variables into the freemarker.properties file. These can only appear in the key values (and not as a key name) of the Java .properties file.
Declaring a variable
A variable's syntax must be as follows:
/*<variable name>*/ (without spaces), where <variable name> is made up of a series of one or more characters: "a" to "z", "A" to "Z", "0" to "9" or "_".
When running the APE, each variable identified in the freemarker.properties file is replaced by its value (/*<variable name>*/ variable declaration is replaced by its value).
Defining a variable
A variable can be:
- either an environment variable
- or a system property defined when starting the APE.
Environment variable
An environment variable is a user variable shared by one or more processes. Its definition mode is specific to each operating system.
System property
In Java, a system property is defined by the following syntax:
-D<variable name>=<variable value>
Notes:
- The system property takes priority over the environment variable. If the same variable is defined as both an environment variable and a system property, the system property value will be taken into account,
- When running the APE, if a variable is not defined, its declaration is left as it is.
Example
Here is an example of a template_loader key of a freemarker.properties file which declares:
- a FileTemplateLoader template loader, the "baseDir" parameter of which is defined by a TEST_ENV_VAR1 environment variable, and
- another template loader, the value of which is defined by a TEST_ENV_VAR2 environment variable.
template_loader=freemarker.cache.MultiTemplateLoader( \
[com.hardis.adelia.mergedocengine.freemarker.conf.FileTemplateLoader(java.io.File ("/*TEST_ENV_VAR1*/")), \
/*TEST_ENV_VAR2*/, \
com.hardis.adelia.mergedocengine.freemarker.conf.ClassTemplateLoader(com.hardis.adelia.mergedocengine.ProcessTemplate.CLASS_FOR_OBJECT_BUILDER_EXPRESSION, "/com/hardis/adelia/mergedocengine/freemarker/lib"), \
com.hardis.adelia.mergedocengine.freemarker.conf.ClassTemplateLoader(com.hardis.adelia.mergedocengine.ProcessTemplate.CLASS_FOR_OBJECT_BUILDER_EXPRESSION, "/com/hardis/adelia/apeexternallibs/freemarker/lib")])
The user defines the TEST_ENV_VAR1 variable as an environment variable and the TEST_ENV_VAR2 variable as a system property. Here is the APE start syntax in Windows and Linux:
Windows
set TEST_ENV_VAR1=./templatesDir1
ape-dev.bat -Dmanagement.endpoint.shutdown.enabled=true -Dserver.port=8080 -DTEST_ENV_VAR2=com.hardis.adelia.mergedocengine.freemarker.conf.FileTemplateLoader(java.io.File(\"d:/ape/templatesDir2\"))"
Linux
export TEST_ENV_VAR1=./templatesDir1
↑ Top of pagesh ape-dev.sh -Dmanagement.endpoint.shutdown.enabled=true -Dserver.port=8080 -DTEST_ENV_VAR2='com.hardis.adelia.mergedocengine.freemarker.conf.FileTemplateLoader(java.io.File(\"/home/userape/ape/templatesDir2\"))'