在简单的示例中,可以使用 java.lang 和 java.util 包下的类,还有用户自定义的 Java Bean来构建数据对象。
- 使用 java.lang.String 来构建字符串
- 使用java.lang.Number 来派生数字类型
- 使用 java.lang.Boolean 来构建布尔值
- 使用 java.util.List 或 Java 数组构建序列
- 使用 java.util.Map 来构建哈希表
- 使用自定义的 bean 类来构建哈希表,bean中的项和bean的属性对应
数据模型
在内部,模板中可用的变量都是实现了 freemarker.template.TemplateModel 接口的 java 对象。
但在自己的数据模型中,可以使用基本的Java集合类作为变量,因为这些变量会在内部被替换为适当的 TemplateModel 类型;这种功能特性被称为 object wrapping 对象包装。
对象包装功能可以透明地把任何类型的对象转换为实现了 TemplateModel 接口类型的实例。
这就是的下面的转换成为可能,如在模板中 java.sql.ResultSet 转换为序列变量,把 javax.servlet.ServletRequest 对象转换成包含请求属性的哈希表变量,甚至可以遍历 XML 文档作为 FTL变量。
包装这些对象,需要使用合适的,也就是所谓的对象包装器是钱(也可能是自定义的实现)。
标量
4中类型的变量:
- 布尔值 —— 实现TemplateBooleanModel接口
- 数字 —— 实现TemplateNumberModel接口
- 字符串 —— 实现TemplateScalarModel接口
- 日期 —— 实现TemplateDateModel接口
容器
哈希表
FreeMarker中的哈希表是实现了 TemplateHashModel 接口的对象。TemplateHashModelEx接口扩展了TemplateHashModel接口;经常使用的实现类是SimpleHash,该类实现了TemplateHashModelEx接口。
序列
序列是实现了TemplateSequenceModel接口的Java对象。经常使用的实现类是SimpleSequence。
集合
集合是实现了TemplateCollectionModel接口的Java对象。通常使用的实现类是SimpleCollection。
方法
方法变量实现了 TemplateMethodModel 接口。这个接口仅包含一个方法:TemplateModel exec(java.util.List arguments),当使用方法调用表达式去调用方法时,exec方法将会被调用。形参将会包含FTL方法调用形参的值,exec方法的返回值给出了FTL方法调用表达式的返回值。
TemplateMethodModelEx接口扩展了TemplateMethodModel接口。
例如:
public class IndexOfMethod implements TemplateMethodModel {public TemplateModel exec(List args) throws TemplateModelException {if (args.size() != 2) {throw new TemplateModelException("Wrong arguments");}return new SimpleNumber(((String) args.get(1)).indexOf((String) args.get(0)));}
}
将一个方法实例放入根数据模型中,
root.put("indexOf", new IndexOfMethod());
在模板中调用:
<#assign x = "something">
${indexOf("met", x)}
${indexOf("foo", x)}
输出为:
2
-1
指令@
指令变量实现了TemplateDirectiveModel接口。
节点变量
节点变量体现了树形结构中的节点。节点变量的引入是为了帮助用户在数据模型中处理XML文档,也可以用户构建树状模型。
节点变量实现TemplateNodeModel接口。
对象包装
当往容器中添加一些对象时,可以是任意java对象类型的参数,而不一定是TemplateModel。这是因为模板实现会默默地用合适的TemplateModel对象来替换原有对象。比如向容器中加入一个String,也许它将被替换为一个SimpleScalar实例来存储相同的文本。
至于什么类型的Java对象可以被替换,又使用什么样的TemplateModel来实现,它可以被实现的容器自身来控制,也可以委派给ObjectWrapper的一个实例。
ObjectWrapper是一个接口,其中只定义了一个方法:TemplateModel wrap(java.lang.Object obj)。可以传递一个object类型的对象,它会返回对应的TemplateModel对象,如果不行则抛出TemplateModelException一场。替换原则是在ObjectWrapper的实现类中编码实现的。
最重要的ObjectWrapper实现类是FreeMarker核心包提供的:
public interface ObjectWrapper {ObjectWrapper BEANS_WRAPPER = BeansWrapper.getDefaultInstance();ObjectWrapper DEFAULT_WRAPPER = DefaultObjectWrapper.instance;ObjectWrapper SIMPLE_WRAPPER = SimpleObjectWrapper.instance;
我们使用java.util.HashMap作为根的哈希表,而不是SimpleHash或其他特定的FreeMarker类,因为Template.process(...)自动包装了给定的数据模型参数的对象,所以它才会起作用。它使用受Configuration设置的对象包装器。因此,编写简单的FreeMarker应用程序就不需要知道TemplateModel。注意根的类型不需要一定是java.util.Map,它也可以是实现了TemplateHashModel接口的被包装的对象。