Woonsan Ko <[email protected]> írta:
>Hi Mark,
>
>Thanks a lot for the elaborated answers!
>Now I understand the use case and its goodness by having "spec" json
>file for each "generated source" with being able to use the shared
>FreeMarker "template".
>
>I'm just thinking aloud, but from user's perspective, I'm thinking of
>an example structure (package structure is up to users) like this:
>
>- [Template]
>src/main/freemarker/com/example/templates/generic-code-gen-template.ftl
>- [Spec] src/main/freemarker/com/example/Foo.spec.json
>- [Spec] src/main/freemarker/com/example/Bar.spec.json
>
>==> Generating Foo.java and Bar.java under the outputDirectory.
I miss the ".java" from that. The original logic is that you remove the ".json"
from the end, and that's the output file name. Like you could have a
foo.xml.json, and now it generates foo.xml, not a java file.
So, I guess that the containing directory decides the purpose of the file is
find.
That all this is inside /src/main/freemarker is more questionable though.
Similarly as docgen has /src/main/docgen (and that uses FreeMarker too BTW),
this should have some more specific name as well.
A more interesting question is if this plugin could support the other approach
as well, where you have one template per output file, and usually one shared
data-model. That's the logic that FMPP follows for example (with some twist,
like its XML file transformation feature works more like this plugin). Of
course, FMPP targets a different use case than this plugin, but maybe it can do
both without becoming messy.
>(Just trying to find a more intuitive and conventional project
>structure here...)
>
>The "spec" json file can possibly split metadata such as "template"
>from the 'model':
>
>{
> "template": "/com/example/templates/generic-code-gen-template.ftl",
>// possibly a relative path as well?
> "model": {
> "myString": "a string",
> "myNumber": 1,
> "myListOfStrings": ["s1", "s2"],
> "myListOfNumbers": [1, 2],
> "myMap": {
> "key1": "value1",
> "key2": 2
> }
> }
>}
>
>Perhaps the maven plugin module could be shipped with a versioned JSON
>schema file to avoid any confusions or support any other potential
>tooling, too.
>
>Regards,
>
>Woonsan
>
>On Wed, Aug 15, 2018 at 4:52 PM, Mark Malynn <[email protected]> wrote:
>> Hi Woonsan,
>>
>> Before writing our freemarker-maven-plugin, I looked for a maven templating
>> plugin that would meet our needs and could not find one. The basic
>> limitation of those existing plugins is that I could only generate one
>> source file per template file. I needed to be able to generate multiple
>> source files per template file.
>>
>> With regards to your inline comments:
>>
>> 1) I separated template and data directories because it was easier to code
>> and I happen to like that organization better. I'd be willing to add support
>> for just one directory that contains both templates and data models (and I'd
>> be willing to have that be the default configuration).
>>
>> 2) Using a naming convention to identify the template (from the name of the
>> json file) prevents my main use case (to generate multiple class source
>> files using the same template).
>>
>> 3) I agree that using the well known json field 'templateName' seems
>> 'hacky' (from a freemarker point of view). However, from the point of view
>> of the maven plugin it works nice. It provides the flexibility I need with
>> the minimum fuss. I will entertain another mechanism as long as it supports
>> my main use case.
>>
>> -Mark
>>
>> On Wed, Aug 15, 2018 at 11:02 AM, Woonsan Ko <[email protected]> wrote:
>>>
>>> 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
>>
>>
>
