Wednesday, January 11, 2017, 3:50:50 PM, Woonsan Ko wrote: > 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.,
Yes, that's the plan. > 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? Indeed, maybe that's better, but I'm not sure. Technically both works the same (as far as I see). If we just use o.a.freemarker directly, because each Maven module can have Java subpackages, it's not obvious if o.a.freemarker.foo is just a subpackage inside o.a.freemarker:freemarker, or it's inside o.a.freemarker:freemarker-foo (unless you happen to know that there's a freemarker-foo). So in that sense, o.a.freemarker.core is superior. OTOH, I wonder which is the most intuitive for the users. Any other opinions about this? > (BTW, I have assumed FM3 should structured like a maven multi-module > project. I guess Gradle should have the same concept.) Yes. > 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. But that's exactly what I want to avoid. It has caused many problems in FM 2. That they are internal means that you can't use them at all, because if some people do that, even accidentally (IDE auto completion...), we will break their code. Yes their mistake, but still... certainly you wont refactor internal code so freely anymore. >> (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.) (If is o.a.f.core is preferred then yes.) >> 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.) (Then yes.) > 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 -- Thanks, Daniel Dekany
