Hello, My colleague Mark Malynn (CC’d) has been using apache Freemarker on an internal Oath (e.g. Yahoo/AOL) project that we are intending to open source. This project is an Immutable Offheap Cache which is used to store and access data off-heap for high-performance java server applications.
As a part of our offering, we provide out of the box primitive collections classes that mirror FastUtils, and we are using Freemarker to generate source files needed to implement those primitive collections. Mark built a Maven plugin for Freemarker that we use as a part of our build process. We built this because the Freemarker project does not provide one natively and other plugins we found do not offer the power level we needed (we generate sources from multiple templates during both build and test phases of the pipeline). When working with our internal open sourcing team, they suggested that we first reach out to you to gauge interest in hosting this plugin as a part of the Freemarker project. This made sense to us as well. Please let us know if it makes sense to contribute this as a part of Freemarker. We can support it as needed. Below the is the existing project README.md: freemarker-maven-plugin Background This plugin is used to generate files using FreeMarker template files and JSON data files. FreeMarker Template Files FreeMarker template files must reside in the template sub-directory under the sourceDirectory. For the default configuration, this is: src/main/freemarker/template. By convention, file names for FreeMarker template files use the .ftl extension. For details on the FreeMarker template syntax, see: Getting Started <https://freemarker.apache.org/docs/dgui_quickstart.html> and Template Language Reference <https://freemarker.apache.org/docs/ref.html>. JSON Data Files The JSON data files must reside in the data sub-directory under sourceDirectory. For the default configuration, this is: src/main/freemarker/data. For each JSON data file, freemarker-maven-plugin will generate a file under the outputDirectory. The name of the generated file will be based on the name of the JSON data file. For example, the following JSON file: <sourceDirectory>/data/my/package/MyClass.java.json will result in the following file being generated: <outputDirectory>/my/package/MyClass.java This plugin parses the JSON data file into a Map<String, Object> instance (hereafter, referred to as the data map). The parser allows for comments. After parsing the file, the plugin will add a pomProperties entry into the data map, which is itself a map containing the properties defined in the pom. Thus, your template can reference the pom property my_property using ${pomProperties.my_property}. If you have a period or dash in the property name, use ${pomProperties["my.property"]}. This plugin requires one top-level field in the JSON data file: templateName. This field is used to locate the template file under <sourceDirectory>/template that is used to generate the file. This plugin provides the data map to FreeMarker as the data model to process the template identified by templateName. This plugin currently assumes that the JSON data file encoded using UTF-8. Example JSON data file: { // An end-of-line comment. # Another end-of-line comment "templateName": "my-template.ftl", /* A multi-line comment */ "myString": "a string", "myNumber": 1, "myListOfStrings": ["s1", "s2"], "myListOfNumbers": [1, 2], "myMap": { "key1": "value1", "key2": 2 } } Installation pom.xml Add the following snippet within the <plugins> tag of your pom.xml: <plugin> <groupId>com.oath</groupId> <artifactId>freemarker-maven-plugin</artifactId> <version>${freemarker-maven-plugin.version}</version> <configuration> <!-- Required. Specifies the compatibility version for template processing --> <freeMarkerVersion>2.3.23</freeMarkerVersion> </configuration> <executions> <!-- If you want to generate files during other phases, just add more execution tags and specify appropriate phase, sourceDirectory and outputDirectory values. --> <execution> <id>freemarker</id> <!-- Optional, defaults to generate-sources --> <phase>generate-sources</phase> <goals> <!-- Required, must be generate --> <goal>generate</goal> </goals> <configuration> <!-- Optional, defaults to src/main/freemarker --> <sourceDirectory>src/main/freemarker</sourceDirectory> <!-- Optional, defaults to target/generated-sources/freemarker --> <outputDirectory>target/generated-sources/freemarker</outputDirectory> </configuration> </execution> </executions> </plugin> Usage FreeMarker Configuration Typically, users of this plugin do not need to mess with the FreeMarker configuration. This plugin explicitly sets two FreeMarker configurations: 1. the default encoding is set to UTF-8 2. the template loader is set to be a FileTemplateLoader that reads from <sourceDirectory>/template. If you need to override these configs or set your own, you can put them in a <sourceDirectory>/freemarker.properties file. If that file exists, this plugin will read it into a java Properties instance and pass it to freemarker.core.Configurable.setSettings() to establish the FreeMarker configuration. See this javadoc <https://freemarker.apache.org/docs/api/freemarker/template/Configuration.html#setSetting-java.lang.String-java.lang.String-> for configuration details. Code Coverage By default the code coverage report is not generated. You can generate code coverage on your dev machine with the following maven command: mvn clean initialize -Dclover-phase=initialize Bring up the coverage report by pointing your browser to target/site/clover/dashboard.html under the root directory of the local repository. Contribute See Contributing.md License Licenced under the Apache 2.0 license. See: LICENSE.txt — Benjamin Grant Jackson
