Hi Benjamin, Thanks for the proposal. IIUC, it looks similar to maven-velocity-plugin [1], which generates .java files based on Velocity template files with configured parameters (models). But, the module on your end reads models from .json file in addition. Am I in correct understanding? If so, the scope should not be too big. It could be useful to many people. Please see my comments inline below as well.
[1] https://github.com/nativelibs4java/maven-velocity-plugin On Tue, Aug 14, 2018 at 12:08 PM, Ben Jackson <[email protected]> wrote: > 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. Why not simply src/main/freemarker? > > 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. Why not simply with a different extension? e.g, src/main/freemarker/com/example/MyClass.ftl.data.json for src/main/freemarker/com/example/MyClass.ftl. > > 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 > } > } Isn't the json file intended for model provision to the FreeMarker template? If so, it doesn't look good to me to have "templateName" in the model json file. Convention might be better as mentioned above. Regards, Woonsan > > 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
