Hi, Dan and Woonsan Thanks for all of the feedback.
1. Yes, the current design is one output source file per json data file. 2. We would intend to use the open source version and update as needed. 3. We don't anticipate any significant development to meet our needs. As you said, this is a fairly simple concept. I could imagine some other use case that would need some tweaks. We would be able to support the plugin as needed. My questions / assumptions. 1. I assume we would host this as a separate repository under the apache project, say apache/freemarker-maven-plugn. Is this right? 2. I assume the plugin would follow an independent release cycle...would you manage the publication throug the existing freemarker project credentials? 3. Would you want us to use some specific CI/CD process for the project? If so, is it documented somewhere? 4. I assume we would need to update the Freemarker website with documentation; I will have Mark and Myself sign CLAs through our open source team to contribute to Freemarker; I will tweak the packaging and copyright to something appropriate, and we can then share the source with you. I will also review the recommended properties at https://freemarker.apache.org/ docs/pgui_quickstart_createconfiguration.html. -Ben On Wed, Aug 15, 2018 at 1:42 PM, Daniel Dekany <[email protected]> wrote: > It's quite focused on the specific use case, but I guess many use > cases where FreeMarker is involved with Maven is similar. (Or not... I > don't have the data to tell honestly.) Anyway, as an internal project > it's expected to be specialized on one case. Things can be > generalized/extended further after contribution. (Then of course > question is if the existing solution is solid enough so that it worths > building upon it, or it will be refactored beyond recognition. But > this we can try to guess if we see the source code.) > > Another important question is if what are the plans of your company > with this plugin. Let's say this comes to Apache. After that, do you > plan to use the Apache version of the plugin, contributing to it when > you need some improvement? Is such a thing expected at all, or you > don't expect that you will develop the plugin further? Any of you is > interested to improve it regardless, in your free time? > > A note regarding the the default FreeMarker configuration... I would > recommend setting a few more things according to > https://freemarker.apache.org/docs/pgui_quickstart_ > createconfiguration.html. > > > Tuesday, August 14, 2018, 6:08:21 PM, Ben Jackson 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. > > > > 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 > > -- > Thanks, > Daniel Dekany > > -- Benjamin Grant Jackson
