2.3.21

Added ranges with exclusive end: start..<end (also can be written as start..!end). More...

Added length limited ranges: start..*length: For example, 10..*4 gives [10, 11, 12, 13], 10..*-4 gives [10, 9, 8, 7], and 10..*0 gives []. When these kind of ranges are used for slicing, the slice will end without error if the end of the sliced sequence or string is reached before the specified range length was reached. Thus, for example, to take the first 10 characters from the string s, or less if s is shorter than 10 characters, you can use s[0..*10]. More...

Square bracket now accepts range values from any source, like <#assign r = 1..3> ${'foobar'[r]} will print "oob". Earlier it has only supported ranges that were specified directly inside the square brackets, like 'foobar'[1..3].

When slicing a sequence with a right-unbounded range, it's now allowed to have a range start index that's one higher than the last index of the sliced sequence. For example, ['x', 'y'][2..] is not an error anymore, but an empty sequence. (Of course, ['x', 'y'][3..] is still an error.)

someString?substring(from, toExclusive) and someString?substring(from) are now deprecated; use this slicing expression instead: someString[from..<toExclusive] and someString[from..]. A warning if you are processing XML: Since slicing expressions work both for sequences and strings, and XML nodes in FTL are typically both sequences and strings at the same time, there the equivalent expression is someXmlNode?string[from..<toExclusive] and exp?string[from..], because without the ?string it would slice the node sequence instead of the text value of the node.

If the incompatible_improvements in the FreeMarker configuration is set to at least 2.3.21, right-unbounded ranges become readable (like #list-able). Earlier they could only be used for slicing, and behaved like empty sequences otherwise.

someString?keep_before(substring[, flags]): More...

someString?keep_after(substring[, flags]): More...

someString?remove_beginning(substring): More...

someString?remove_ending(substring): More...

someString?ensure_starts_with(substring[, substitution[, flags]]): More...

someString?ensure_ends_with(substring): More...

Added new kind of date_format/datetime_format/time_format setting values: XML Schema formats, starting with "xs" and ISO 8601:2004 formats, starting with "iso". The format string can be continued with various space (or _) separated options, like h or m or s or ms for setting shown accuracy, nz or fz for setting time zone offset visibility, and u or, fu for using UTC time zone . For example, to use ISO 8601 with minute precision and without the zone offset being shown, set the datetime_format setting to "iso m nz", so then the output will be like 2014-09-03T20:56. More...

Because anything that's accepted as date_format/datetime_format/time_format setting value can also be used with the ?string and ?date/?time/?datetime build-ins, you can use the new formats like someDate?string.xs and someString?date.xs. (For the "xs" and "iso" formats, _ can be used instead of space, which means that, for example, you can write lastModified?string.iso_m_u instead of the more verbose lastModified?string["iso m u"].)

That "iso" and "xs" are now possible date_format/datetime_format/time_format setting values also means that such values can now be parsed too via ?date/?time/?datetime. The main application is with processing XML DOM-s, as there values are coming in as strings, and now you can do something like order.confirmDate?date.xs to convert them to real dates.

The ?iso_... built-ins are now deprecated in favor of the new setting values described above. They can be set as the default date/time/date-time format, seamlessly fit into the formatting architecture (and thus can parse strings too), and has more/better options (ms always shows 3 millisecond digits, fz for forcing showing time zone offset).

If the "incompatible improvements" configuration setting is at least 2.3.21, the ?iso_... built-ins won't show time zone offset for java.sql.Time values anymore. Most databases store time values that aren't in any time zone, but just store hour, minute, second, and decimal second field values, so showing the time zone doesn't make sense. (Notable exceptions are PostgreSQL "time with time zone" columns, where mzTime?string.iso_fz could be used.)

Added ?is_time, ?is_datetime, ?is_date_only (should be called ?is_date, but that was already taken) and ?is_unknown_date_like to check the exact type of a date-like value.

?is_date is now a deprecated name, use ?is_date_like instead. This is because ?is_date sounds like it checks if the value is a date without time part, but actually it also returns true for time, date-time, and unknown date-like values.

Added ?date_if_unknown, ?time_if_unknown and ?datetime_if_unknown built-ins, which mark a date-like value with some of the sub-types: date without time, time, or date-time, respectively. However, if the value already holds this information, the built-in has no effect. That is, it will never convert the sub-type of a value, it only adds the sub-type if it was unknown.

Bug fixed: ISO 8601 dates (via ?iso_... and "iso" format settings) now use proleptic Gregorian calendar for the years before 1582, rather than Julian calendar. This is (indirectly) required by the standard, and it's also how the default Sun/Oracle Java XML Schema date/time/dateTime parser works.

Fixed glitch where if an #if had and #else or #elseif, the #if/#else/#elseif wasn't hidden in the FTL stack trace when the error was inside its nested block.

Some new context sensitive hints in undefined variable exception error messages.

Fixed unclosed directive error messages at end of file where the wrong unclosed directive name was reported

Better type error messages when accessing XML data (applies when wrapped with freemarker.ext.dom):

Trying to use obj.someMethod without () on a place where method value is not expected will recommend calling the method.

Trying to use methods like obj.getFoo or obj.isFoo without ()on a place where method value is not expected will recommend using the obj.foo form.

Messages are now much more readable when rendered in environments that don't obey to line-breaks. (This often happens in improperly implemented HTML error pages and logs viewers.)

Better FTL instruction stack traces:

Bug fixed: ?substring has thrown low level java.lang.IndexOutOfBoundsException-s instead of more descriptive TemplateModelException-s with FTL stack trace.

Bug fixed: Slicing with ranges sometimes thrown low level java.lang.IndexOutOfBoundsException-s instead of more descriptive TemplateModelException-s with FTL stack trace.

Bug fixed [402]: Fixed misleading parser error message when a directive called without its required parameters (like <#list>) was reported as unknown directive.

Bug fixed [222]: Poor quality error message when someString[someIndex] fails with string index out of bounds.

Bug fixed [27]: Not very good quality error messages when #import-ing a template whose parsing fails.

The default of the object_wrapper setting (Configuration.getObjectWrapper()) changes from ObjectWrapper.DEFAULT_WRAPPER to another almost identical DefaultObjectWrapper singleton, returned by new DefaultObjectWrapperBuilder(Version).build(). The new default object wrapper's "incompatible improvements" version is set to the same as of the Configuration. (See later regarding the 2.3.21 "incompatible improvements" of BeansWrapper and DefaultObjectWrapper). Furthermore, the new default object wrapper doesn't allow changing its settings; setter methods will throw IllegalStateException. (If anything tries to call setters on the old default in your application, that's a dangerous bug that won't remain hidden now. As the old default is a singleton too, potentially shared by independently developed components, most of them expects the out-of-the-box behavior from it (and the others are necessarily buggy). Also, then concurrency glitches can occur (and even pollute the class introspection cache) because the singleton is modified after publishing.)

The default of the template_loader setting (Configuration.getTemplateLoader()}) changes to null, which means that FreeMarker will not find any templates. Earlier the default was a FileTemplateLoader that used the current directory as the root. This was dangerous and fragile as you usually don't have good control over what the current directory will be. Luckily, the old default almost never looked for the templates at the right place anyway, so pretty much all applications had to set template_loader, so it's unlikely that changing the default breaks your application.

Instead of new DefaultObjectWrapper(...) and new BeansWrapper(...), from now on you should use new DefaultObjectWrapperBuilder(version).build() and new BeansWrapperBuilder(version).build(). (The builder objects have properties (configuration settings) like BeansWrapper has, which specify the properties of the objects created.) The created objects are singletons (VM-wide, or at least Web-Application-wide) and read-only (means, non-configurable, hence safe to share). The main benefit of using these factories instead of creating new instances is that it allows FreeMarker to share the class introspection caches (an internal part of BeansWrapper-s/DefaultObjectWrapper-s that is expensive to populate) among the returned instances. This allow sharing the caches (and the object wrappers) between components that aren't aware of each other and use FreeMarker internally.

Deprecated the static fields ObjectWrapper.DEFAULT_WRAPPER, BEANS_WRAPPER and SIMPLE_WRAPPER, because these ObjectWrapper-s are configurable (not read-only), and thus dangerous to use as singletons (a badly behaving 3rd party component can mess them up). Use the factories described above instead. They are also more flexible, as you can specify the desired incompatible-improvements version for them and various other BeansWrapper settings.

Deprecated all SimpleHash, SimpleCollection and SimpleSequence constructors that didn't take an ObjectWrapper argument, as they have usually used ObjectWrapper.DEFAULT_WRAPPER as the default, which itself is deprecated.

BeansWrapper, DefaultObjectWrapper and SimpleObjectWrapper now implements the freemarker.template.utility.WriteProtectable interface with which the configuration properties of the object wrapper can be set permanently to read-only by calling writeProtect(). An attempt to call a setter on a such ObjectWrapper will immediately cause IllegalStateException. (This is what's used for the singletons returned by the getInstance methods too; see earlier).

ParseException-s now also store the end-location of the error, not just its start-location. This is useful if you want to underline the error in the source code, not just point at it.

Configuration.getSupportedBuiltInDirectiveNames() can be used to return the names of directives supported by FreeMarker.

TemplateExceptions now expose the position of the error (template name, line, column, end line, end column) similarly to ParseException-s. Where applicable, they also expose the blamed expression in its canonical FTL source form; this is mostly useful for InvalidReferenceException-s.

Earlier, null argument values has only matched overloaded methods where the corresponding parameter had Object type, not a subclass of it. That's clearly a bug. Now it considers all overloads where the parameter type is non-primitive, and just like the Java language, it choses the one with the most specific type among them. This is the most important fix, and also the most risky one regarding backward-compatibility. Like if you have m(Object o) and m(String s) in a Java class, earlier for a m(null) call in the template it has chosen m(Object o), but now it will choose m(String s) instead (because String is also null-able and is more specific than Object). Furthermore, if you also had m(File f) in the same class, now it will cause an ambiguity exception, since the specificity of File and String can't be compared (same rule as under Java language), while earlier that wasn't a problem as only m(Object o) was seen as applicable.

The behavior of numbers with overloaded method selection was heavily reworked:

Method choice ambiguity errors now occur much less often. Ambiguities was and are resolved by selecting the compatible methods then choosing the one with the most specific parameter types among them. The changes are:

FTL sequence values (like Java List-s or FTL [x, y, ...] constants) were not seen as applicable to a parameter with array type if there were multiple overloaded methods with the same number of parameters but with different types on the position of the array parameter. That is, if you had f(String[]) and f(String) in Java, then f(['foo', 'bar']) in the template reported no compatible overloads. Now it will choose f(String[]). Note that if there's also an f(List) or even an f(Collection), it will prefer those over arrays. (For consistency, this conversion will work even if the argument is a List that come directly from Java (as opposed to be created inside FTL), i.e., when it was wrapped then unwrapped to the original List object.) For a multidimensional array parameter type, this conversion works recursively, so you can pass in a sequence-of-sequences as the argument.

FTL sequence values that wrapped a Java array (when FreeMarker was also aware of that via AdapterTemplateModel or WrapperTemplateModel) were not seen as applicable to a parameter with List type if there were multiple overloaded methods with the same number of parameters but with different types on the position of the array parameter. So this is pretty much like the issue described in the previous point, but for array to List conversion. The array to List conversion will be avoided if possible, but it will be attempted if there's no other alternative. Note that unlike with List to array conversions, here FreeMarker can't cope with multi-dimensional lists, that is, an array-of-arrays won't be converted to a List-of-List-s.

FTL string to Java char/Character conversion now works for overloaded method parameters; earlier it has worked for non-overloaded methods only. If the string length is 1, it will be seen as compatible with parameters with char or Character type.

Decreased the chance of choosing the wrong target Java type when unwrapping multi-typed FTL values: When unwrapping a parameter value that implements multiple FTL types (e.g. string and hash) but doesn't implement AdapterTemplateModel or WrapperTemplateModel, a decision has to be made if to what Java type the value should be unwrapped to (e.g. to String or to Map). In earlier versions that decision was made based on the most specific common super type of the parameters types of the given parameter position. However, it's quite common that the common super type is too generic, usually Object. Now BeansWrapper stores "type flags" for each parameter position of overloaded methods, from which it can tell whether a potential target Java type occurs in any of the overloads on the given parameter position.

In many cases, less specific hint class was used for unwrapping than that was possible within the limitations of the applied hint generation algorithm. (The unwrapping hint has influence when there's an ambiguity regarding how to create a Java object form an FTL value. In the vast majority of the cases, a too generic hint has no effect.) (This is a highly technical topic. The way it works is that a single common unwrapping hint class is chosen for a given argument position shared by the overloads that has the same number of parameters, and that hint class has to be as specific as possible while it must fit all those parameter types. The issue with the too generic hints had several instances: (a) When the most specific common class/interface of two same-position parameter types was searched, if there was multiple common classes/interfaces that had no relationship (this is always at most one class and one or more unrelated interfaces), due to the ambiguity it has felt back to using Object as the unwrapping hint. Now if there's a non-Object class among them in such case, it will be chosen as the hint (i.e., we ignore the common interfaces). Otherwise if only a single interface remains by removing Cloneable, Serializable, and Comparable (in that order), that will be chosen. Only then it falls back to Object. (b) The common most specific class of a primitive type and the corresponding boxing class was sometimes Object instead of the boxing class. This has depended on Java's internal ordering of the methods, and so were quite unpredictable, like the result could change after upgrading Java under the application. (c) The common superclass of a numerical primitive value and a numerical non-primitive value was always Object, now if they are a primitive-boxing class pair, then it's the boxing class, otherwise it's Number. (d) If the varags parameter position was not the same in all the overloaded varargs methods, sometimes some varargs arguments where unwrapped with too generic hints. When this happened was unpredictable as it depended on Java's internal method ordering again.)

When unwrapping method call arguments before calling a Java method, if the argument was an AdapterTemplateModel and the target parameter type was primitive, AdapterTemplateModel.getAdaptedObject(Class hint) has received the primitive type of the target parameter (like int instead of Integer) as the hint. This did not make sense since getAdaptedObject can only return Object-s, not primitive values. Yet, BeansWrapper has expected the returned value to be of the primitive type, otherwise it has discarded it. Exactly the same problem occurs with WrapperTemplateModel. Thus, ultimately, if the target parameter type was primitive and some of these interfaces were implemented, their return value was always discarded and FreeMarker has felt back to other means of unwrapping. Now BeansWrapper always passes in and expects the boxing type (like Integer) instead of the primitive type.

URLTemplateLoader and its subclasses and WebApplicationTemplateLoader now has a setURLConnectionUsesCaches(Boolean) method. It's recommended to set this property to false from its default backward compatible value, null. As FreeMarker has its own template cache with its own update delay setting (template_update_delay, Configuration.setTemplateUpdateDelay(int)), it shouldn't cause performance problems. The null value will leave the caching of the java.net.URLConnection on its default, which is usually true.

If incompatible_improvements is set to 2.3.21 (or higher) and templates are loaded through Configuration.getTemplate, and the TemplateLoader in use has URLConnectionUsesCaches left on null, it will behave as if it was set to false. Note that this incompatible_improvements trick only works if the template is loaded through Configuration.getTemplate (or TemplateCache).