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 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. (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 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 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
