2.3.20

Page Contents

• FTL 方面的变化

• Java 方面的变化

• Other changes

发布日期：2013-06-27

如果您是 IDE /工具作者，则注意这些变化。

FTL 方面的更改

• 错误消息质量改进：

• 现在，许多错误消息都更加有用，特别是对于那些不熟悉 FreeMarker 的用户。例如，可以识别出一些最常见的用户错误，并显示解决问题的技巧，从而减少了支持成本或员工花费的时间来解决这些错误。

  • 现在确保TemplateException.getMessage()返回的消息中包含模板中的错误位置。无论如何，堆栈跟踪始终显示此信息，但是某些用户只看到“消息”，而不是堆栈跟踪，并且通常不包含该位置。

  • 现在，堆栈跟踪的模板语言部分更加详细，更易于理解。这对于使用复杂的宏和函数库的应用程序特别有用。

  • 修复了一些小错误，这些错误使错误信息错误或缺少。

  • 现在，错误消息的布局更加一致，并且通常更易于阅读。

• 关于布尔到字符串转换和格式的更改：

• ?c(计算机语言格式)现在也适用于布尔值，无论boolean_format为何，始终给出"true"或"false"。这样，在还呈现人类可读文本的上下文中生成 JavaScript 是安全的。

  • 如果boolean_format设置设置为默认"true,false"值以外的任何值，则布尔值将自动转换为字符串(模板语言期望使用字符串值)，而不是给出错误。这有助于您在布尔值后保留那些?string -s。这与数字和日期的逻辑相同，数字和日期总是根据相应的格式设置自动转换为字符串。除此以外，提供的默认布尔格式对于自动转换是无用的(但对于?string仍然存在，以实现向后兼容)，因此必须手动设置。 (无论如何，我们当然无法提出明智的默认值，因为布尔值很大程度上取决于应用程序，更不用说本地化问题了.)

就像数字和日期一样，在以下情况下不会发生自动转换：

• 比较，即someBoolean == 'true'仍然是错误

  • 方法调用，其中参数的声明类型为String，但实际值为布尔值；还是一个错误

  • 当布尔值用作expr[key]中的键时，仍然是错误(其他类型也没有自动转换，因为数字键和字符串键的含义不同)

  • 相反的方向，即字符串到布尔值的转换；不会发生

• 新的数字内置代码：abs，is_nan，is_infinite。就像n?abs将给出n的绝对值。

• 序列的新内置代码：join。像[1, 2, 3]?join(", ")将给出字符串"1, 2, 3"。

• 如果将incompatible_improvements设置(请参见here)设置为2.3.20或更高，则?html会像?xhtml一样转义撇号。强烈建议使用此格式，因为否则，如果在使用单引号(<foo bar='${val}'>)而不是普通引号(<foo bar="${val}">)的属性值内使用插值，则插值可能会产生格式不正确的 HTML/XML。请注意，?html并没有这样做，因为很久以前没有跨浏览器的方法可以这样做，但是这不再是一个 true 的问题。另请注意，这是从 2.4 开始的默认行为。

• 错误修复\ [390](以及其他改进)：?js_string和?json_string未能逃脱u2028-u2029行终止符(JavaScript 的问题)和u007F-u009F控制字符(JSON 可能是一个问题，具体取决于实现)。此外，\，<和>的转义变得更加安全，因为现在无法确定它们不属于<!，]]>或</的一部分时，它们将被转义。早先只有在知道它们是这些模式的一部分时才转义，因此可以从两个相邻的插值中组合这些模式。此外，从现在起<?和-->也被视为危险模式，并将触发<和>逃逸。

• 修正了错误：下列内置字符串没有将数字，日期(现在是布尔值)左值强制转换为字符串，而是引发了类型错误：contains index_of，last_index_of，left_pad，right_pad，matches，replace， split，new。内置的其他字符串已经进行了很长时间的转换。这是偶然的不一致。

• 修正了错误：使用默认的算术引擎，现在支持将无限(正数或负数)与 0 进行比较以确定其符号。

Java 方面的更改

• BeansWrapper自省缓存的改进：

• 向BeansWrapper添加了公共 API 以清除类缓存：clearClassIntrospecitonCache()，removeFromClassIntrospectionCache(Class)

  • 显着提高了多核性能：

• 在 Java 5 或更高版本上运行时使用ConcurrentHashMap。

  • 在缓存未命中后自省类时，缓存不会阻止 Reader

  • 如果多个线程需要内省尚未缓存的同一个类，则只有其中一个可以这样做，其他线程将 await 其结果。

  • 错误修复\ [361]：检测到类重载时，死锁的可能性很小。重新设计了锁定功能，以防止将来发生此类疏忽。

  • 内部清理的结果是，内部可见的软件包freemarker.ext.beans API 稍有更改。除了 FreeMarker 开发人员外，任何人都不应在该程序包中定义类，因此它不应破坏任何内容。但是，如果有人在那里进行了一些内部黑客攻击，请重新编译以查看它是否仍然有效。

• 无名模板(那些由new Template(null, ...)直接创建而不是通过Configuration加载的模板)无法包含或导入其他模板，并且在尝试使用时会抛出NullPointerException。现在，它们解析相对路径，就好像它们位于模板根目录中一样。

• 错误修复：正则表达式内置函数和一些 Logger 库(最重要的是 Log4J)在 Google App Engine 平台上不可用。此修复程序仅存在于 GAE 兼容版本 2.3.20-gae 中。

• 向Configuration：CacheStorage getCacheStorage()添加了新方法

• 根据模板语言运算符的规则向Environment添加了新方法，以便在TemplateModel -s 之间进行比较：applyEqualsOperator，applyEqualsOperatorLenient，applyLessThanOperator，applyLessThanOrEqualsOperator，applyGreaterThanOperator，applyWithGreaterThanOrEqualsOperator

• 添加了新方法Environment.isInAttemptBlock()，以检查我们是否在#attempt块内。这对于TemplateExceptionHandler -s 很有用，因为它们不需要将错误打印到输出，因为#attempt仍会回滚错误。内置的TemplateExceptionHandler -s(DEBUG_HANDLER和HTML_DEBUG_HANDLER)已经利用了它。

• 添加了便利构造函数Template(String name, String sourceCode, Configuration cfg)。

• 现在，TemplateException -s 和TemplateModelExcepton -s 可以有Throwable原因，而不仅仅是Exception(这是一个旧的疏忽，至今仍未解决)。

• 现在，在 JBoss Tools FreeMarker IDE 下分析错误消息不再包含通常的位置行，因此，在 Eclipse“问题”视图中可以立即看到实际的错误描述。 (这是 FreeMarler 本身的“黑客”；它试图检测它是否在插件下运行，然后更改其行为.)

• 主要涉及工具(如 IDE 插件)的作者：

• 错误消息格式(Throwable.getMessage()返回的内容)对于TemplateException -s 进行了较大的更改，对于ParseException -s 进行了一些更改。不太可能有人依靠这些消息，但是如果您尝试解析这些消息，请注意这一点。

  • 修复了ParseException包含 0 作为行号和列号的词法错误的错误。现在，它包含正确的信息。

  • 添加了ParseException.getEditorMessage()：与在 IDE-s 中一样，错误标记已经向用户显示了错误位置，该位置不应在错误消息中重复。因此，在 IDE 中，您应该使用此方法而不是getMessage()。 (在 JBoss 工具下：FreeMarker 现在尝试以检测它是否在插件下运行，然后它已经执行了此操作，只是它仍然显示列号，因为错误标记位置中缺少该列号.)

  • 已添加ParseException.getTemplateName()

  • 添加了Configuration.getSupportedBuiltInNames()。由于新的内置插件(expr?builtin_name)通常会添加到新的 FreeMarker 版本中，因此自动完成或语法高亮显示应使用此集合而不是固定的名称集合。

  • TemplateElement.getDescription()返回的格式已进行重大更改。这就是 FTL 堆栈的踪迹，也许还显示了一些轮廓视图(树视图)。它总是供人类阅读(到目前为止，对于其他任何东西都太不一致了)，因此这不太可能破坏任何东西。

  • freemarker.debug中有一些较小的更改，并且预计还会有更多更改，因此被标记为实验性的。据我们所知，没有人使用过它，因此它不应破坏任何东西。

• 处于仅实验状态，但是freemarker.jar现在是 OSGiBinding 包(请参阅freemarker.jar/META-INF/MANIFEST.MF)。根据用户反馈，Binding 包描述可能会在将来更改。因此，请提供反馈，特别是如果您是 OSGimaven！

• 改进了HTML_DEBUG_HANDLER生成的 HTML(黄底红字错误消息)。最重要的是，现在它将自动换行。其他更改很小，例如现在它可以脱离 CDATA 部分，或者现在它的颜色不那么强烈。

• 新的Template方法getActualTagSyntax()：告诉模板是使用传统语法还是方括号语法。由于语法可以在模板中覆盖，因此它也可能由自动检测决定，到目前为止，这并不是一件容易的事。

• 添加了一些 Util 方法，这些方法可用于在自定义指令中生成错误消息：ClassUtil.getFTLTypeDescription(TemplateModel)，getShortClassName，getShortClassNameOfObject

• 错误修复\ [364]：freemarker.template.EmptyMap(如果没有参数，则传递给TemplateDirectiveModel -s)现在允许remove(key)，clear()和putAll(anyEmptyMap)，因为它们仍然不起作用。

• 错误修复\ [375]：NullPointerException上的 IBM J9 VM(不在 Sun/Oracle 实施上)NullPointerException，当 Java 实现合法地为某些BeanInfo getter 返回null时。

• 错误修复：克隆Configuration不会深度克隆存储auto_imports和auto_includes设置的数据结构，因此可能导致别名问题。

• 错误修复\ [377]：在失败的方法调用之后，异常处理程序可能在targetObject.toString()失败的极少数情况下失败，从而引发甚至attempt指令都无法捕获的运行时异常。

• 错误修复\ [391]：如果模板名称中包含的*不是路径步骤中的唯一字符，则它会抛出NegativeArraySizeException而不是FileNotFoundException。

• 使用默认的算术引擎，当一些数字为 0 且数字的符号不同时，比较操作的性能优化。

• TemplateElement.getCanonicalForm()中的一些较小的修订，那里的质量也有所提高。

• 借助 Information Mosaic，修复了classic_compatible模式(此模式是为了帮助从 FreeMarker 1 迁移)中的错误：

• 当使用null/missing 参数值调用宏时，它导致了与 FreeMarker 2.3 中类似的错误

  • 当散列 Literals 包含对null/missing 变量的引用(如{ 'a': missingVar })时，它会引起类似 2.3 的错误

  • 当序列 Literals 包含对null/missing 变量的引用时(如[1, missingVar])，它导致了类似 2.3 的错误。

  • 当.(点)或[key]运算符的左侧为null或缺少变量时(如missingVar.subVar)，它导致了类似 2.3 的错误。

  • 尝试将BeanModel -s 视为字符串时，对于大多数子类而言，它会因类型错误而失败，如 2.3 中所示。在 FreeMarker 1 中，所有BeanModel -s 均为TemplateScalarModel -s，因此应该成功。此修复程序仅在 FreeMarker 强制字符串化的情况下起作用(字符串内置在左侧，并且串联(+)和插值(${...})可以做到)，否则不幸的是，它仍然会失败。

  • classic_compatible设置现在接受值_以及true(别名1)和false(别名0)。 2表示true，但是在早期 2.x 经典兼容模式下模拟错误。当前，这仅影响布尔值如何转换为字符串。 1始终为"true"/""，但2表示BeansWrapper包装的值是"true"/"false"，以Boolean.toString()为准。请注意，就像 FreeMarker 2.3 中一样，someBoolean?string将始终根据boolean_format设置始终格式化布尔值。

• 错误修复\ [394]：当尝试使用Error而不是Exception访问DefaultObjectWrapper中的可选 Jython(或 W3C DOM)类失败时，加载DefaultObjectWrapper类本身失败，而不是 Jython(或 W3C DOM)支持被禁用。从现在开始，它会在那里生存任何类型的Throwable，如果Throwable不是ClassNotFoundException，它将也记录Throwable。

• 在null/missing 变量不是括号内的最后一步的情况下，改进了(thisVarIsMissing.foo)!default和类似的“括号”存在运算符和存在内置函数的性能。在那种情况下，现在的速度大约是 Java 6 的 30 倍。在其他情况下(所有变量都存在，或者缺少最后一步)，性能大约与以前相同(相对较快)。

• 添加了接口freemarker.cache.CacheStorageWithGetSize，该接口允许查询实现它的CacheStorage中的缓存条目的当前数量。它由所有现成的CacheStorage实现方式实现。还将getStrongSize()和getSoftSize()添加到MRUCacheStorage。

• 版本和构建信息更改：

• 每晚内部版本号的形式已更改为符合 Maven/JSR 277.以前的2.3.19mod现在类似于2.3.20-nightly_20130605T130506Z(请注意最后一个如何指向目标发行版本，而不是最后一个发行版本)。

  • 发行候选版本和预览版本号的形式已更改为与 Maven/JSP 277 兼容：2.4pre2现在是2.4.0-pre02，2.4rc1现在是2.4.0-rc01。

  • 向Configuration添加了新的静态方法以查询构建日期：getBuildDate()。这也由主命令行类打印。

• 各种内部代码清除。

Other changes

• JavaDoc 的许多改进，大部分在基本(最常用)类的文档中。

• FreeMarker 源代码已移至 GitHub(https://github.com/freemarker/freemarker)，其他项目资源仍保留在 sourceforge.net 上。

• 项目结构清理，基于 Ivy 的构建脚本。