Release date: 2017-03-25
This is a stable, final release. The "incubating" suffix is required by the Apache Software Foundation until the project becomes a fully accepted (graduated) Apache project.
Changes on the FTL side
-
Added
node?next_siblingandnode?previous_siblingto move sideways in a node trees (see reference...). This works with XML DOM nodes, or with any customTemplateNodeModelEximplementations. -
Added new
@@keys to XML DOM models:@@next_sibling_element,@@previous_sibling_element. These get the sibling node if that's an element, with the extra that they silently skip any whitespace text and comment and processing instruction between them. (See more about@@keys here...) -
Bug fixed (FREEMARKER-42):
?firstnow works with FTL collections (things that can be listed but doesn't support getting items by index), not only with sequences. The practical importance of this is that?firstnow always works on JavaSet-s (which is useful forSet-s with well defined ordering), while earlier it has failed depending on theobject_wrapperconfiguration setting.
Changes on the Java side
-
FREEMARKER-24: Added workaround (not enabled by default) to expose Java 8 default methods (and the bean properties they define) to templates, despite that
java.beans.Introspector(the official JavaBeans introspector) ignores them, at least as of JRE 1.8.0_66. To enable this workaround, either increase the value of theincompatibleImprovementsconstructor argument ofDefaultObjectWrapperorBeansWrapperthe used to 2.3.26, or set itstreatDefaultMethodsAsBeanMemberssetting totrue. Note that if you leave theobject_wrappersetting of theConfigurationon its default, it's enough to increase theincompatibleImprovementssetting of theConfigurationto 2.3.26, as that's inherited by the defaultobject_wrapper. -
Added the
freemarker.template.TemplateNodeModelExinterface which extends theTemplateNodeModelinstance with two methods,TemplateNodeModelEx getNextSibling()andTemplateNodeModelEx getPreviousSibling()methods. This is required bynode?next_siblingandnode?previous_siblingin the templates. This new interface is already implemented by the standard W3C DOM node wrapper of FreeMarker. -
Made
+operator when adding two hashes significantly faster (be removing the overhead caused be throwing and then catching an exception). -
Better error messages when someone tries to get an invalid
@@...subvariable of an XML DOM node. (Now it's not issued by the XPath implementation, which just sees it as a syntactical error.) -
Added
Configuration.isXxxExplictlySetandConfiguration.unsetXxxmethods for the Configuration settings:locale,time_zone,default_encoding. (This can be utilized in frameworks to detect if the application has missed setting these. The backward compatible default values are often unwanted, as they are the default locale, time zone and file encoding of the Java environment.) -
The
localeanddefault_encodingconfiguration settings now supports the special"JVM default"value when set from Java.propertiesfile, or viaConfiguration.setSettings(Properties), or via the#settingdirective. Earlier only thetime_zonesetting has supported this value. -
Bug fixed: The OSGi
Bundle-RequiredExecutionEnvironmententry inMETA-INF/MANIFEST.MFhas incorrectly stated that the minimum required version isJ2SE-1.4, while it's in factJ2SE-1.5. Also the highest utilized version was raised toJavaSE-1.8. -
Bug fixed: If the
incompatible_improvementssetting is set to 2.3.26 (or higher),exp?interpretalways gets the parser-related settings from the template that it's called from. Earlier, sometimes it got those from the topmost (main) template instead. Similarly, the generated name of the template that?interpretcreates will always refer to the template where's it's called from. -
Bug fixed:
MultiTemplateLoader, when it's in sticky mode (the default), and theTemplateLoaderthat was successfully used for a given name last time doesn't find the template now (let's call it the stickedTemplateLoader), and thusMultiTemplateLoaderfalls back to trying all theTemplateLoader-s in order, will now skip the stickedTemplateLoader, as that was already attempted in the sameMultiTemplateLoader.findTemplateSourceinvocation. -
Bug fixed:
NodeModel.mergeAdjacentText(Node)didn't merged all adjacent text nodes, only pairs of adjacent text nodes. (Luckily this method is hardly ever used, and the more often usedNodeModel.simplify(Node)was working correctly.) -
Performance improvements in the static utility methods of
NodeModel:simplify(Node),mergeAdjacentText(Node),removeComments(Node),removePIs(Node). -
Added warning to the JavaDoc of
NodeModel.parsemethods to inform users about the possibility of XML External Entity (XXE) attacks if the source XML (not a template) comes from untrusted source. This is just an XML fact (i.e., that in an XML you can have external entities and they can be exploited), and has no much to do with FreeMarker. Also note that FreeMarker itself never callsNodeModel.parse; these are merely convenience methods that some applications directly call themselves to create aNodeModelfrom an XML file. As this method encapsulates the call to the platform XML parser, we thought it's better to point this risk out. -
DefaultObjectWrapper, only with itsincompatible_improvementsset to 2.3.26 (see how here...), wrapsjava.util.Enumeration-s intofreemarker.template.DefaultEnumerationAdapter(a new class) instead of intofreemarker.ext.beans.EnumerationModel(as far asuseAdaptersForContainersistrue, which is the default). This adapter is cleaner thanEnumerationModelas it only implements the minimally required FTL type, which avoids some ambiguous situations. (Note that Java API methods aren't exposed anymore as subvariables; if you really need them, you can use?api). -
DefaultIteratorAdapternow supports?api. It was an oversight that it didn't. -
Configuration.setSetting(String, String)andsetSettingsnow allowsnullvalue fortemplate_loader(becauseConfiguration.setTemplateLoader(null)is also allowed for a while.). -
The
freemarker.template.TemplateCollectionModelExinterface and is not experimental anymore, so now it has backward compatibility guarantees. Note that theTemplateCollectionModelEx.contains(TemplateModel)method was removed from it. -
freemarker.template.DefaultNonListCollectionAdapterclass is not experimental anymore, so now it has backward compatibility guarantees. -
BeansWrapperConfiguration.classIntrospectorFactoryis not a protected field anymore, but a private one. Especially as the class of that field (ClassIntrospectorBuilder) was package private, it's pretty much sure that nobody depends on this field. -
Various smaller code cleanups.
Other changes
-
FREEMARKER-17: Removed the Servlet- and JSP-related
*.dtdfiles to simplify licensing. We can operate without them as before, as validation with them was disabled earlier too. At this point, everything in the source code of the FreeMarker engine, and everything in the producedfreemarker.jarwas created inside the FreeMarker project. -
FREEMARKER-27: Moved some content from the
NOTICESfiles over to theLICENSEfile, to follow the Apache Incubator guidelines closer. -
Various smaller JavaDoc improvements.
