On Wed, Jan 11, 2017 at 5:55 AM, Daniel Dekany <[email protected]> wrote: > A bit of prelude first... This is about FreeMarker 3 development (FM3 > from now on). If life and the community allows it, there will be tons > of smaller and quite a few bigger changes in FM3. I intend to drop > together a mail like this for most "change sets", so we can see if > more discussion (and voting in worse case) is needed. Generally, I > will wait for answers for ~72 hours, then even if there was no answer, > I will assume that it's accepted (because anything can be undone later > after all, it's just extra work). > > So, to the subject. Please tell your opinion of the points below. > > > (1) Using org.apache.freemarker (o.a.f) as top level package
+1 > > As it was discussed long ago, FreeMarker 3 (FM3 from now on) will use > a separate parent package from FM2, org.apache.freemarker (o.a.f from > now on). (I also had idea that it could be org.apache.freemarker.v3, > but org.apache.freemarker is surely look cleaner.) The main point of > that is that hence FM2 and FM3 can be used together in the same "class > path", which is important because the main point of FM3 is to get rid > of the backward compatibility baggage. > > This was discussed once, but if anyone has anything add, do it. > > > (2) Unify freemarker.template and freemarker.core, under o.a.f > > In FM2 we have a separate freemarler.template package, which contains > the most commonly used classes (Configuration, Template, TemplateModel > classes), and there's a freemarker.core package which contains some > less often used ones (such as Environment), and lots of classes that > are public but was marked as internal (AST and such), and of course > non-public internals too. The root "freemarker" package itself is unused. > > There were two recurring problems with this in FM2: > > - What is most- and least commonly used is a blurry line, so it's not > very helpful classification for the API users. Especially if we hide > the internal but sadly public classes (and we do that on the JavaDoc > level even in FM2), the concern (topic) of the two packages isn't > clear. Both deal with core engine stuff really. (And > freemarker.template is just a misnomer... at least it never made > sense to me. Why "template"?) > > - The freemarker.template package and the freemarker.core package needs to > cross-reference each other a lot (as their concerns aren't well > separated from engineering point of view either). As Java's > visibility rules are rather simplistic (and the Java 9 module system > won't be common place anytime soon), this forces us to make things > public that shouldn't be that, or to do hacks with "_XxxApi" > classes. > > Therefor I believe we should just get rid of the freemarker.template > and freemarker.core spearation, and move their contents into o.a.f. Maybe we foresee a possibility to have extension modules in the future. Just as theoretical examples, freemarker-jsp jar, freemarker-spring jar, etc., assuming the core can be packaged as freemarker-core jar. For the possibility, wouldn't it help to name the main package name to o.a.freemarker.core instead of o.a.freemarker? (BTW, I have assumed FM3 should structured like a maven multi-module project. I guess Gradle should have the same concept.) Regarding the internal classes, I'd personally prefer putting into o.a.freemarker.core.internal. It could give a good insight for advanced API users at least. > (One the same time we should move out some classes from it, but see > later.) > > > (3) Move TemplateModel interfaces and standard implementations from > o.a.f to o.a.f.model +1 (If o.a.f.core is preferred, that can be o.a.f.core.model.) > > Template models is a topic that's easy to understand for the users > (mentally and technically separate from the other concerns), so we > could decrease the surface area of the o.f package API with this. > > As of the TemplateModel implementations, let's say for now that we > move them over from o.a.f too. Though there will be some more moving > around in that department, together with BeansWrapper and its friends, > but that's for another day. > > > (4) Rename freemarker.cache to o.f.templateloader +1 (or o.a.f.core.templateloader.) Regards, Woonsan > > Because, it was misnomer. Template loading is the main topic of the > package (caching of the TemplateLoader-ed templates is part of it). > > -- > Thanks, > Daniel Dekany >
