2.3.20
Page Contents
发布日期: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 本身的“黑客”;它试图检测它是否在插件下运行,然后更改其行为.)
-
错误消息格式(
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 的构建脚本。