Any opinions about these proposed changes? (Sooner or later we will
also get to the trickier changes... new features and such. Right now I
just want FM to "lose weight" quickly.)
- No brainers:
- Drop support for the IncompatibleImprovements values before 3.0.0
(As FM3 breaks backwards compatible anyway, they are pointless.)
- Similarly, remove @Deprecated methods/classes (except those that
were marked as @Deprecated because they shouldn't be public -
those will be dealt with when restructuring the packages).
- Remove "since" and "@Since" comments, because they refer to the
pre-FM3 things, that are under a separate package anyway.
- Replace all public int constants with enums
- Configuration:
- Change the default of Configuration.templateExceptionHandler to
TemplateExceptionHandler.RETHROW_HANDLER
- Remove Configuration.logTemplateExceptions setting, and behave as
FM2 does when it's set to false. This means that we only log an
exception if we don't throw it at the caller (because otherwise
the caller is expected to handle or log it).
logTemplateExceptions=false is also the recommended setting for
FM2, but it can't be the default there due to backward
compatibility constraints.
- Change the default of Configuration.defaultEncoding to UTF-8.
Earlier it has defaulted the platform default, but that's quite
fragile, as it's a property of the server installation, not of
your application. Many Linux servers have utf-8 as the default
nowadays, so you don't even notice that you rely on that until the
application is moved to a server with a different default charset,
while your templates and data of course won't be magically
converted to that.
- Make most of freemarker.template.utility (like StringUtil-s)
internal. They just add to the things that you can't evolve because
of backward compatibility constraints, while providing such API-s is
not the topic of FreeMarker, and certainly almost nobody uses them
deliberately. Now, these things has to be accessible from multiple
FM packages, yet they are internal to FM, and Java doesn't support
that. So I would use a "_" prefix, like "_StringUtil" (this trick is
also used in FM2). Thus they don't show up during auto-completion
(at least in Eclipse, because you haven't started the class name to
complete with "_"). Also if you as a user just see something like
StringUtil in your code, you may don't notice the problem (you maybe
believe it's commons-lang StringUtil). But if you see _StringUtils,
you know something is wrong.
- Use more modern builder class conventions: fluent API and, maybe
Xxx.Builder instead of XxxBuilder class? See
DefaultObjectWrapperBuilder as an FM2 example.
- Drop these long deprecated FTL directives
(http://freemarker.org/docs/ref_depr_directive.html):
- "call" directive (deprecated by <@...> very long ago)
- "transform" directive (also deprecated by <@...>)
- "comment" directive (deprecated by <#-- ... --> very long ago)
- "foreach" - we use "list" instead in all official documentations,
and only "list" supports the stuff like the "else", "sep", "items"
directives.
- Drop these long deprecated built-ins directives
(http://freemarker.org/docs/ref_depr_builtin.html):
"default", "if_exists", "exists", "web_safe".
--
Thanks,
Daniel Dekany
