So, based on the discussion below, I have concluded that the most basic Maven artifact of FM3 will be "freemarker-core" (so that's similar to freemarker.jar today, but somewhat leaner, as it doesn't contain servlet/jsp support for example), and its base package will be org.apache.freemarker.core. That will enclose some subpackages (like the equivalent of FM2 freemarker.cache), all of which belongs to freemarker-core.jar. Basic classes like Configuration, Template, Environment, will be all directly inside org.apache.freemarker.core.
Any more thoughts on this? Wednesday, January 11, 2017, 8:58:29 PM, Daniel Dekany wrote: > Wednesday, January 11, 2017, 3:50:50 PM, Woonsan Ko wrote: [snip] >>> (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? [snip] -- Thanks, Daniel Dekany
